coyote: CGCMDWINDOW__DEFINE

Description
Creates a "command" window for IDL traditional commands (Plot, Contour, 
Surface, etc. or for Coyote Graphics routines, cgPlot, cgContour, cgSurf, etc.). 
In addition, the window contents can be saved as PostScript files or as raster image 
files. If ImageMagick is installed on your machine, the raster image files can be 
created in very high quality from PostScript files. This program can be used in 
place of a normal draw widget or as a stand-alone program.
The program is designed to work with any IDL traditional graphics routine
that is a procedure and includes no more than four positional parameters.
Any number of keywords can be used to specify properties of the graphical
output. Any number of graphics commands can be "added" the the window.
Simply use the AddCommand method to add commands.
If your program does not load its own color tables, the color tables in
effect when this program is initiated are used to display the graphics
commands.
To create PostScript output from within the program, your graphics program
has to be written in such a way that it can work properly in the PostScript
device. This means there are no Window commands, WSet commands, and the like
that are not allowed in the PostScript device. Such commands are allowed in 
programs, of course, if they are "protected". Usually such protection looks 
like this::
   IF (!D.Flags AND 256) NE 0 THEN Window, ...
The Coyote Graphics program `cgDisplay` is a good program for opening graphics 
"windows", because such PostScript protection is built into the program. In a PostScript 
device, cgDisplay produces a "window" with the same aspect ratio as the current
display graphics window, which is an aid in producing PostScript output that
looks like the same output in the display window.
Much better looking raster files can be created from the graphics window contents,
if the raster files are created by converting PostScript files to the raster 
file. If the ImageMagick "convert" command can be found on your machine, you
will have the option to create raster files using this method. I *highly*
recommend doing so, as fonts and other plot annotation will be of much higher
quality using this method.
This program has been designed to work with other Coyote Graphics routines: `cgPlot`,
`cgContour`, `cgSurf`, and so on, although I expect it to work with any IDL
traditional graphics routine, if the routine is well written.
Categories
Graphics
Author
FANNING SOFTWARE CONSULTING::
   David W. Fanning 
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com
Copyright
Copyright (c) 2011, Fanning Software Consulting, Inc.
History
Change History::
   Separated from old cgWindow program 22 Jan 2012, by David W. Fanning.
   Fixed a typo in PackageCommand method that prevented extra keywords from
      being collectd. 26 Jan 2012. DWF.
   Fixed a problem with MULTI keyword. 31 Jan 2012. DWF.
   Added a COPY method. 7 Feb 2012. DWF.
   Fixed a problem with input filenames in the AutoRasterFile method. 22 Feb 2012. DWF.
   Modified Draw_Widget creation routine to account for events that were added in 
      different versions of IDL. 23 Feb 2012. DWF.
   Added ability to use IM_WIDTH keyword to set the width of raster file output
      created with ImageMagick. 3 April 2012. DWF.
   Forgot to specify the GROUP_LEADER when calling cgPS_Open. Caused cgPS_Config to
      run though its block when cgWindow was called from a blocking widget program.
      5 June 2012. DWF.
   Added the ability to save the file name and directory of the last output file, so
       that subsequent file saves can use that last name and directory as a starting
       default filename. 11 July 2012. DWF.
   In decompling cgWindow from cgCmdWindow, I accidentally named the WASPECT keyword ASPECT. Restored
        original name in this version. 13 July 2012. DWF.
   I added a new method, ReplaceEscapeSequences, that can evaluate escape sequences in
        string parameters and keywords to call the appropriate cgSymbol value at run-time.
        This eliminates the need for alternate keywords. 27 July 2012. DWF.
   Added WDestroyObjects keyword to destroy objects parameters, if needed. 11 November 2012. DWF.
   Not adding IM_WIDTH parameter from cgWindow_GetDefs. 19 November 2012. DWF.
   Modified ReplaceEscapeSequence method to use cgCheckForSymbols. 24 November 2012. DWF.
   Modified to allow keywords to turn off messages from cgPS_Open and cgPS_Close with keywords. 27 November 2012. DWF.
   The output filename was not specified correctly when making PDF file automatically. Fixed. 2 Dec 2012. DWF.
   Renamed the MULTI keyword to WMULTI, as it was suppose to be. 11 Feb 2013. DWF.
   Misspelled keyword in PackageCommand method. 21 February 2013. DWF.
   Modified GUI so there is only one Raster Image File choice, depending on if ImageMagick is
      installed. 21 May 2013. DWF.
   I made the IM_WIDTH field in the object a pointer, so it could remain an undefined variable, 
       if necessary. 20 FEB 2014. DWF.
   Typo in the spelling of DESTROYOBJECTS when restoring a graphic visualization. Fixed. 20 Feb 2015. DWF.
s method initializes the object that is at the heart of the Coyote Graphics system.
allows you to both configure the draw widget for events and to load a command into
 command window.
Params
class: out, optional, type=struct
    The object class structure definition. Occasionally useful.
Keywords
adjustsize: in, optional, type=boolean
   Set this keyword to adjust default character size to the display window size.
background: in, optional, type=string
   The background color of the window. Only use if the ERASEIT property is also set.
delay: in, optional, type=float
   Set this keyword to the amount of "delay" you want between commands in the command list.
dimensions: in, optional, type=intarr(2)
   Set this keyword to a two-element array giving the xsize and ysize
   of the draw widget.
eraseit: in, optional, type=boolean
   If this property is set, the cgWindow erases with the background color before
   displaying the commands in the window's command list.
im_density: in, optional, type=integer, default=300
   Set this keyword to the sampling density when ImageMagick creates raster image
   file from PostScript outout.
im_options: in, optional, type=string, default=""
   Set this keyword to any ImageMagick options you would like to pass along to the
   ImageMagick convert command when creating raster image files from PostScript output.
im_resize: in, optional, type=integer, default=25
   Set this keyword to percentage that the raster image file created my ImageMagick
   from PostScript output should be resized.
im_raster: in, optional, type=boolean, default=1
   Set this keyword to zero to create raster files using the create_png etc. keywords
   directly, instead of via ImageMagick.
im_transparent: in, optional, type=boolean, default=0
   Set this keyword to allow ImageMagick to create transparent backgrounds when it
   makes raster image files from PostScript output.
multi: in, optional, type=Intarr(5)
   Set this keyword to the !P.MULTI setting you want to use for the window.
   !P.MULTI is set to this setting before command execution, and set back to
   it's default value when the commands are finished executing.
noexecutecommands: in, optional, type=boolean, default=0
   Set this keyword to 1 to prevent the window from executing the commands and to
   0 if you want the window to execute the commands.
palette: in, optional, type=byte
   Use this keyword to pass in an N-by-3 (or 3-by-N) byte array containing the
   R, G, and B vectors of a color table. It is probably easier to use cgLoadCT or
   XCOLORS to load color tables for the window, but this is provided as another option.
pdf_path: out, optional, type=string
   Set this keyword to the name of the path to the Ghostscript command for converting PS to PDF.
pdf_unix_convert_cmd: out, optional, type=string
   Set this keyword to the name of an alternative UNIX command to convert PostScript to PDF.
ps_charsize: in, optional, type=float
   The PostScript character size.
ps_decomposed: in, optional, type=boolean, default=0
   Set this keyword to zero to set the PostScript color mode to indexed color and to
   one to set the PostScript color mode to decomposed color.
ps_delete: in, optional, type=boolean, default=1
   Set this keyword to zero if you want to keep the PostScript output ImageMagick creates
   when making raster file output.
ps_encapsulated: in, optional, type=boolean, default=0
   Set this keyword to configure cgPS_Config to produce encapsulated PostScript output by default.
ps_font: in, optional, type=integer
   Set this keyword to the type of font you want to use in PostScript output. It sets the 
   FONT keyword on the cgPS_Config command. Normally, 0 (hardware fonts) or 1 (true-type fonts).
ps_metric: in, optional, type=boolean, default=0
   Set this keyword to configure cgPS_Config to use metric values and A4 page size in its interface.
ps_quiet: in, optional, type=boolean, default=0
   Set this keyword to set the QUIET keyword on cgPS_Open.
ps_scale_factor: in, optional, type=float
   Set his keyword to the PostScript scale factor you wish to use in creating PostScript output.
ps_tt_font: in, optional, type=string
   Set this keyword to the name of a true-type font to use in creating PostScript output.
storage: in, optional
   A storage location for any kind of IDL variable. This functions like a user value in
   a widget program. 
update: in, optional, type=boolean, default=1
   Set this keyword to zero if you do not want the updates to be done immediately
   after the properties are changed.
wid: in, optional, type=integer
   The draw window index number. Not to be used by the user. Used by the draw widget
   Notify_Realize callback routine when the draw widget is realized.
xomargin: in, optional, type=intarr(2)
   Sets the !X.OMargin system variable when multiple plots are displayed in the window.
yomargin: in, optional, type=intarr(2)
   Sets the !Y.OMargin system variable when multiple plots are displayed in the window.
s method saves the window object reference in a linked-list system variable.
 definition module for the cgCmdWindow object
Private
This method invalidates a widget ID. It is used for restored
visualizations, so that the current window doesn't get inadvertenly
destroyed by a widget identifier from an old program.
s method lists the command indicated by the command index. In the
ence of the command index, all commands are listed.
Returns
The command, packaged as a cgWindow_Command object, is returned.