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