# coyote: CGCMDWINDOW__DEFINE

- coyote/Graphics
- [Source code]

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.