This page was created by the IDL library routine `mk_html_help2`.

Last modified: Mon Aug 25 17:13:29 2025.

# Directory Listing of Routines

# general/tools/tplot/xtplot

- CMPS_FORM
  This function puts up a form the user can configure a PostScript
- XTPLOT_TIMEBAR
  plot vertical (or horizontal) lines on TPLOTs at specified times (or values)

# Routine Descriptions

## CMPS_FORM

[Next Routine] [List of Routines]

     NAME:
       CMPS_FORM

     PURPOSE:
       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.

     AUTHOR:
       Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
       craigm@lheamail.gsfc.nasa.gov
       $Id: cmps_form.pro 16717 2015-01-23 22:08:42Z moka $

       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

     PROCEDURE:
       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.

     HELP:
       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
                  non-interactively.

        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
                     'Letter'.

        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:
                 NONE.

     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
                   discarded.

     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?

     USAGE:

      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, $
                              Defaults=info.ps_config)

         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
         ENDIF

     MAJOR FUNCTIONS and PROCEDURES:

       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
           block
       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
           appearance
       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
       Transfer DEFAULTS and LOCALDEFAULTS values via STRUCT_ASSIGN,/NOZERO
         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,
       configurations.

       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.

         COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, $
                                   cmps_form_STDCONFIGS

            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
                                 configuration.

       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.

      $Id: cmps_form.pro 16717 2015-01-23 22:08:42Z moka $

(See general/tools/tplot/xtplot/cmps_form.pro)

## XTPLOT_TIMEBAR

[Previous Routine] [List of Routines]

    NAME:                  timebar
    PURPOSE:
                           plot vertical (or horizontal) lines on TPLOTs at specified times (or values)
    CALLING SEQUENCE:      timebar,t
    INPUTS:                t: dblarr of times at which to draw vertical lines,
                           seconds since Jan, 1, 1970.  (Or a single datavalue at which to draw a horizontal
                           line in units of the TPLOT variable named in VARNAME).
    KEYWORD PARAMETERS:
          DATABAR:    Set to plot horizontal lines.  *** Must set VARNAME also (for the time being) ***.
          COLOR:      byte or bytarr of color values
          LINESTYLE:  int or intarr of linestyles
          THICK:      int or intarr of line thicknesses
       for any of the above keywords, a scalar input will apply to all times
          VERBOSE: print more error messages; useful for debugging
          VARNAME: TPLOT variable name or index indicating panel in which to plot bar
          BETWEEN: array of two TPLOT variable names indicating
               between which two panels to plot timebar
                           TRANSIENT:  timebar,t,/transient called once plots a
               timebar. Called twice, it deletes the timebar.
                                    Note:  1) all other keywords except VERBOSE
                                    be the same for both calls. 2) COLOR will most
                                    likely not come out what you ask for, but
                                    since it's transient anyway, shouldn't matter.
    OUTPUTS:
    OPTIONAL OUTPUTS:
    COMMON BLOCKS:         tplot_com
    EXAMPLE:
          load_3dp_data,'95-01-01',2 & get_pmom
          tplot,['Np','Tp','Vp']
          t=time_double('95-01-01/1:12')
          timebar,t             ;put a white line at 1:12 am, Jan, 1, 1995
          ctime,t1,t2           ;select two times from the plot
          timebar,[t1,t2],color=!d.n_colors-2 ;plot them in red
    SEE ALSO:
      "CTIME","TPLOT"
    CREATED BY:            Frank V. Marcoline
    LAST MODIFICATION:     2009/05/14, W.M.Feuerstein
    FILE:                  timebar.pro
    VERSION:               1.91

(See general/tools/tplot/xtplot/xtplot_timebar.pro)