>  Docs Center  >  Libraries  >  Markwardt  >  CMPS_FORM






  This function puts up a form the user can configure a PostScript
  device driver. The function result (if the user selects either the
  ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
  procedure by means of its _Extra keyword. User's predefined
  configurations may be retrieved from a common block.


  Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
  Based almost entirely on, but a totally revamped version of, CMPS_FORM by
  FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com

Major Topics

  Device Drivers, Hardcopy Output, PostScript Output


  This is a pop-up form widget. It is a modal or blocking widget.
  Keywords appropriate for the PostScript DEVICE command are returned.
  Use your LEFT mouse button to move the "Plot Window" around the page.
  Use your RIGHT mouse button to draw your own "Plot Window" on the page.
  formInfo = CMPS_FORM(/Help)

Calling Sequence

    formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)

Optional Inputs

    XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.
    YOFFSET -- Optional yoffset of the top-level base of cmps_form. Default is
    to try to center the form on the display.

Input Keyword Parameters

    BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.
    BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
    (All widget programs block under IDL 4.0.)
    COLOR -- The initial configuration of the color switch.
    DEFAULTS -- A stucture variable of the same type and structure as the
    RETURN VALUE of cmps_form. It will set initial conditions. This makes
    it possible to start cmps_form up again with the same values it had the
    last time it was called. For example:
      mysetup = cmps_form()
      newsetup = cmps_form(Defaults=mysetup)
    ENCAPSULATED -- The initial configuration of the encapsulated switch.
    FILENAME -- The initial filename to be used on the form.
    HELP -- Prints a helpful message in the output log.
    INCHES -- The initial configuration of the inches/cm switch.
    INITIALIZE -- If this keyword is set, the program immediately returns the
    "localdefaults" structure. This gives you the means to configue the
    PostScript device without interrupting the user.
    SELECT -- used only when INITIALIZE is set. Set SELECT to a
              string which identifies the predefined configuration to
              be returned by cmps_form when INITIALIZE is set. This is
              a convenient way to select a predefined config
    LANDSCAPE -- The initial configuration of the landscape/portrait switch.
    LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
    then it is added as a predefined configuration entry called "Local".
    See below for a further discussion of predefined configurations.
    PREDEFINED -- An alternate way to specify predefined
                  configurations. Pass an array of structures to
                  populate the "predefined" dropbox in the
                  dialog. This array, if specified, overrides the the
                  common block technique.
    XOFFSET -- The initial XOffSet of the PostScript window.
    YOFFSET -- The initial YOffSet of the PostScript window.
    XSIZE -- The initial XSize of the PostScript window.
    YSIZE -- The initial YSize of the PostScript window.
    ASPECT -- The aspect ratio of the window (Y/X). This keyword can
              substitute for one of XSIZE or YSIZE.
    PRESERVE_ASPECT -- Set this keyword if you want to hold the
                      aspect ratio constant.
    PAPERSIZE -- If set, allows user to specify the size of the paper
                media to be printed on, as a scalar string. NOTE:
                this specification cannot be passed to DEVICE, but
                can be selected for completeness's sake. Default is
    MARGINSIZE -- Size of the margins on all sides. Default is 0.25 inches.
                  When MARGINSIZE is non-zero, a graphic cannot directly
                  abut the edge of the page. This is normally a good thing,
                  since there is often a non-printable region which borders
                  the page.
  DEFAULTPAPER -- Default paper size to use, when it is unspecified
                  in a predefined, "local", or "default"
                  configuration. This value also overrides any
                  configuration from common blocks. European users
                  will probably set this to 'A4'.
  PARENT -- if this widget is invoked by another widget program,
            then this keyword parameter must be set to the top level
            widget which is to serve as the group leader. Failure
            to do so will result in unexpected behavior. IDL 4
            programs do not need to pass this parameter. Default:

Output Keyword Parameters

    CANCEL -- This is an OUTPUT keyword. It is used to check if the user
    selected the "Cancel" button on the form. Check this variable rather
    than the return value of the function, since the return value is designed
    to be sent directly to the DEVICE procedure. The varible is set to 1 if
    the user selected the "Cancel" button. Otherwise, it is set to 0.
    CREATE -- This output keyword can be used to determine if the user
    selected the 'Create File' button rather than the 'Accept' button.
    The value is 1 if selected, and 0 otherwise.
    PAPERSIZE -- If set to a named variable, any newly selected paper
    size is returned in that variable.
    XPAGESIZE -- Size of paper in "X" dimension, in units given by
                the returned config structure.
    YPAGESIZE -- Size of paper in "Y" dimension, in units given by
                the returned config structure.
    PAGEBOX -- specifies the page rectangle relative to the plot
              window, in normalized units. A 4-vector of the form
              [XLL, YLL, XUR, YUR] is returned, giving the positions
              of the lower left (LL) and upper right (UR) corners of
              the page with respect to the plot window. Thus, the
              following command:
                    PLOT, x, y, position=PAGEBOX
              will construct a graphic whose plot region exactly
              fills the page (with no margin around the edges).
              Naturally, the page is usually larger than the
              graphics window, so the normalized coordinates will
              usually fall outside the range [0,1].
              However, the bounding box constructed by the
              Postscript driver includes only the graphics window.
              Anything drawn outside of it may be clipped or

Return Value

    formInfo = { cmps_form_INFO, $
                  xsize:0.0, $ ; The x size of the plot
                  xoff:0.0, $ ; The x offset of the plot
                  ysize:0.0, $ ; The y size of the plot
                  yoff:0.0 $ ; The y offset of the plot
                  filename:'', $ ; The name of the output file
                  inches:0 $ ; Inches or centimeters?
                  color:0, $ ; Color on or off?
                  bits_per_pixel:0, $ ; How many bits per image pixel?
                  encapsulated:0,$ ; Encapsulated or regular PostScript?
                  isolatin1:0,$ ; Encoded with ISOLATIN1?
                  landscape:0 } ; Landscape or portrait mode?
  The calling procedure for this function in a widget program will
  look something like this:
    info.ps_config = cmps_form(/Initialize)
    formInfo = cmps_form(Cancel=canceled, Create=create, $
    IF NOT canceled THEN BEGIN
        IF create THEN BEGIN
          thisDevice = !D.Name
          Set_Plot, "PS"
          Device, _Extra=formInfo
          Enter Your Graphics Commands Here!
          Device, /Close
          Set_Plot, thisDevice
          info.ps_config = formInfo
        ENDIF ELSE
          info.ps_config = formInfo
  None. Designed to work originally in conjunction with XWindow, a
  resizable graphics window. [ NOTE: this modified version of
  cmps_form, by Craig Markwardt, is incompatible with the original
  version of XWINDOW. ]

Modification History

  Based on cmps_form of : David Fanning, RSI, March 1995.
  Major rewrite by: Craig Markwardt, October 1997.
    - Drawing and updating of form and sample box are now modular
    - Option of storing more than one predefined postscript configuration
    - Selection of paper size by name
    - Access to predfined configurations through (optional) common
  Several additions, CM, April 1998 VERSION CM2.0
    - better integration of paper sizes throughout program.
      Predefined configurations now also know about paper.
    - allow passing predefined configurations instead of using

Common Block

    - addition of ISOLATIN selection, and streamlining of dialog
  Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
  Added SELECT keyword, CM, 09 Dec 1998
  Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
  Added "Choose" button for filename selection, 19 Sep 1999
  Added ability to program different button names, 19 Sep 1999
  Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
    Oct 1999
  Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
  Added aspect to cmps_form_numevents (per Aaron Barth), 18 Oct 1999
  Corrected small bug under Initialize keyword (inches), 18 Oct 1999
  Made call to *_pscoord more consistent, 18 Oct 1999
  Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
  Small cosmetic cleanup, CM, 01 Feb 2000
  Fix for IDL 5.5's handling of structures with arrays, CM, 11 Dec 2001
  Replaced obsolete PICKFILE call with DIALOG_PICKFILE, Jeff Guerber,
    24 Sep 2004
    instead of EXECUTE, Jeff Guerber, 24 Sep 2004.
  Set CANCELBUTTON and CREATEBUTTON immediately on entry, so they're
    defined even if user kills the window, Jeff Guerber, 24 Sep 2004.

Common Blocks

  The user may store frequently used or helpful configurations in a
  common block, and cmps_form() will attempt to access them. This
  provides a way for the user to have persistent, named,
  NOTE: this format has changed since the last version. You may
  have to quit your IDL session for the changes to take effect
  properly. If you have place a predefined configuration in your
  startup file, you should review the new format.
        cmps_form_DEFAULT_PAPERSIZE - a string designating the default
                                    paper size, when none is given.
                                    The predefined configurations
                                    offerred by this program will
                                    respect the default value. (See
                                    also the DEFAULTPAPER keyword.)
        cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
                            each containing information about one
                            predefined configuration, such as its
                            name and size of paper. Each "config"
                            element is a cmps_form_INFO structure,
                            which contains the actual postscript
  See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
  to make a list of configurations. One possibility would be to
  declare and populate the common block from within the user's
  start-up script, allowing the same configurations to appear in
  every session.
  cmps_form() takes its initial list of configurations from this
  common block if it exists. A default list is provided ala the
  procedure cmps_form_LOAD_CONFIGS. Any modifications that take place
  during the cmps_form() widget session are not transferred back to
  the common block upon return. It might be useful to be able to do
  this, through some form of 'save' procedure.
  Also, if the PREDEFINED keyword is used, then the common block is
  not consulted.

© 2023 NV5 Geospatial |  Legal
My Account    |    Contact Us