MERIS IDL General Purpose Tools

mpi_plot functions

Last modified: Wed Dec 05 10:45:08 2001.

List of Routines

ADJUSTPOSITION
CW_DRAWCOLOR
ERROR_MESSAGE
FSC_COLOR
FSC_DROPLIST
FSC_FIELD
FSC_FILESELECT
FSC_INPUTFIELD
FSC_PLOTWINDOW
FSC_PSCONFIG__DEFINE
MPI_AXIS__DEFINE
MPI_PLOT
MPI_PLOTCONFIG__DEFINE
PICKCOLORNAME
PSCONFIG
PSWINDOW
TVREAD

Routine Descriptions

ADJUSTPOSITION

[Next Routine] [List of Routines]

NAME:
AdjustPosition

PURPOSE:
This is a program for interactively adjusting the plot position
coordinates. The result of the function is a four-element floating
point array of normalized coordinates, suitable for passing to the
POSITION keyword of most IDL graphics commands.

AUTHOR:

FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com

CATEGORY:

Graphics

CALLING SEQUENCE:

position = AdjustPosition(startingPosition)

OPTIONAL INPUTS:

startingPosition - A four-element array of normalized coordinates
of the form [x0, y0, x1, y1].

OUTPUTS:

position - The adjusted plot position. A four-element array of normalized coordinates.

INPUT KEYWORDS:

GROUP_LEADER - The group leader of this program. This keyword
is required to ensure modal operation when calling from
another widget program.

TITLE - The title of the window. "Adjust Plot Position in Window..." by default.

XOFFSET - The X offset of the program on the display. Calculated from the
upper left-hand corner of the display.

YOFFSET - The Y offset of the program on the display. Calculated from the
upper left-hand corner of the display.

OUTPUT KEYWORDS:

CANCEL - Returns a 1 if the user selects the Cancel button. Returns 0 otherwise.
Note that if the use cancels, the "position" parameter is set to the value of
the "startingPosition" parameter.

DEPENDENCIES:

Reqires FSC_FIELD and FSC_PLOTWINDOW from the Coyote Library:

http://www.dfanning.com/programs/fsc_field.pro
http://www.dfanning.com/programs/fsc_plotwindow.pro

MODIFICATION HISTORY:

Written by David Fanning, March 2001.

(See $IDL_LOCAL\mpi_plot\adjustposition.pro)

CW_DRAWCOLOR

[Previous Routine] [Next Routine] [List of Routines]

NAME:
CW_DRAWCOLOR

PURPOSE:
This compound widget is used to place a label or color name next
to a color patch. Clicking on the color patch allows the user
to select another color

AUTHOR:

CATEGORY:

Graphics

CALLING SEQUENCE:

colorpatchID = CW_DrawColor(parent)

REQUIRED INPUTS:

parent - The identifier of a parent base widget.

OUTPUTS:

colorpatchID - The widget identifier of the top-level base of this compound widget

INPUT KEYWORDS:

COLOR - The name of the color to be displayed. Color names come from PickColorName.
COLUMN - Set this keyword to stack widgets in a column. Default is in a row.
EVENT_FUNC - The name of an event handler function for this compound widget.
EVENT_PRO -The name of an event handler procedure for this compound widget.
INDEX - An index number where the color should be loaded. !D.Table_Size-2, by default.
LABEL_LEFT - Set this keyword to have the label text aligned on the left of the label. Default is to center.
LABEL_RIGHT - Set this keyword to have the label text aligned on the right of the label. Default is to center.
LABELSIZE - This is the X size of the label widget (containing the label) in device coordinates. Default is natural size.
LABELTEXT - This is the text on the label. Example, "Background Color", etc.
TITLE - This is the title on the PickColorName program that allows the user to select another color.
UVALUE - A user value for the widget.
XSIZE - The xsize (in pixel units) of the color patch. By default, 20.
YSIZE - The xsize (in pixel units) of the color patch. By default, 20.

OUTPUT KEYWORDS:

OBJECT - The object reference. Use this to call methods, etc.

DEPENDENCIES:

Reqires FSC_COLOR and PICKCOLORNAME from the Coyote Library:

http://www.dfanning.com/programs/fsc_color.pro
http://www.dfanning.com/programs/pickcolorname.pro

MODIFICATION HISTORY:

Written by David Fanning, March 2001.

(See $IDL_LOCAL\mpi_plot\cw_drawcolor.pro)

ERROR_MESSAGE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
    ERROR_MESSAGE

 PURPOSE:
    The purpose of this function  is to have a device-independent
    error messaging function. The error message is reported
    to the user by using DIALOG_MESSAGE if widgets are
    supported and MESSAGE otherwise.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

    Utility.

 CALLING SEQUENCE:

    ok = Error_Message(the_Error_Message)

 INPUTS:

    the_Error_Message: This is a string argument containing the error
       message you want reported. If undefined, this variable is set
       to the string in the !Error_State.Msg system variable.

 KEYWORDS:

    NONAME: If this keyword is set the name of the calling routine
       is not printed along with the message.

    TRACEBACK: Setting this keyword results in an error traceback
       being printed to standard output with the PRINT command.

    In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE
    routines can also be used.

 OUTPUTS:

    Currently the only output from the function is the string "OK".

 RESTRICTIONS:

    The "Warning" Dialog_Message dialog is used by default. Use keywords
    /ERROR or /INFORMATION to select other dialog behaviors.

 EXAMPLE:

    To handle an undefined variable error:

    IF N_Elements(variable) EQ 0 THEN $
       ok = Error_Message('Variable is undefined', /Traceback)

 MODIFICATION HISTORY:

    Written by: David Fanning, 27 April 1999.
    Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
    Added _Extra keyword. 10 February 2000. DWF.
    Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
    Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
    Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.

(See $IDL_LOCAL\mpi_plot\error_message.pro)

FSC_COLOR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       FSC_COLOR

 PURPOSE:
       The purpose of this function is to obtain drawing colors
       by name and in a device-decomposition independent way. The
       color names and values may be read in as a file, or 88
       color names and values are supplied from the program. These
       were obtained from the file rgb.txt, found on most X-Window
       distributions. Representative colors were chose from across
       the color spectrum. To see a list of colors available, type:
       Print, FSC_Color(/Names).

 AUTHOR:

       FANNING SOFTWARE CONSULTING:
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics, Color Specification.

 CALLING SEQUENCE:

       color = FSC_COLOR(theColor, theColorIndex)

 NORMAL CALLING SEQUENCE FOR DEVICE-INDEPENDENT COLOR:

       axisColor = FSC_COLOR("Green", !D.Table_Size-2)
       backColor = FSC_COLOR("Charcoal", !D.Table_Size-3)
       dataColor = FSC_COLOR("Yellow", !D.Table_Size-4)
       Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
       OPlot, Findgen(11), Color=dataColor

 OPTIONAL INPUT PARAMETERS:

       TheColor: A string with the "name" of the color. To see a list
           of the color names available set the NAMES keyword.

           Valid names depend on the colors loaded in the program, but
           typically include such these colors as these:

              Black       Pink
              Magenta     Aqua
              Cyan        SkyBlue
              Yellow      Beige
              Green       Charcoal
              Red         Gray
              Blue        Orchid
              Navy        White

           The color WHITE is used if this parameter is absent. To see a list
           of the color names available in the program, type this:

              Print, FSC_COLOR(/Names)

       TheColorIndex: The color table index where the specified color is loaded.
           The color table index parameter should always be used if you wish to
           obtain a color value in a color-decomposition-independent way in your
           code. See the NORMAL CALLING SEQUENCE for details.

 RETURN VALUE:

       The value that is returned by FSC_COLOR depends upon the keywords
       used to call it and on the version of IDL you are using. In general,
       the return value will be either a color index number where the specified
       color is loaded by the program, or a 24-bit color value that can be
       decomposed into the specified color on true-color systems.

       If you are running IDL 5.2 or higher, the program will determine which
       return value to use, based on the color decomposition state at the time
       the program is called. If you are running a version of IDL before IDL 5.2,
       then the program will return the color index number. This behavior can
       be overruled in all versions of IDL by setting the DECOMPOSED keyword.
       If this keyword is 0, the program always returns a color index number. If
       the keyword is 1, the program always returns a 24-bit color value.

       If the TRIPLE keyword is set, the program always returns the color triple,
       no matter what the current decomposition state or the value of the DECOMPOSED
       keyword. Normally, the color triple is returned as a 1 by 3 column vector.
       This is appropriate for loading into a color index with TVLCT:

          IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color

       But sometimes (e.g, in object graphics applications) you want the color
       returned as a row vector. In this case, you should set the ROW keyword
       as well as the TRIPLE keyword:

          viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row))

       If the ALLCOLORS keyword is used, then instead of a single value, modified
       as described above, then all the color values are returned in an array. In
       other words, the return value will be either an NCOLORS-element vector of color
       table index numbers, an NCOLORS-element vector of 24-bit color values, or
       an NCOLORS-by-3 array of color triples.

       If the NAMES keyword is set, the program returns a vector of
       color names known to the program.

 INPUT KEYWORD PARAMETERS:

       ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color
              triples, for all the known colors, instead of for a single color.

       DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
              a color table index or a 24-bit color value, respectively.

       FILENAME: The string name of an ASCII file that can be opened to read in
              color values and color names. There should be one color per row
              in the file. Please be sure there are no blank lines in the file.
              The format of each row should be:

                  redValue  greenValue  blueValue  colorName

              Color values should be between 0 and 255. Any kind of white-space
              separation (blank characters, commas, or tabs) are allowed. The color
              name should be a string, but it should NOT be in quotes. A typical
              entry into the file would look like this:

                  255   255   0   Yellow

       NAMES: If this keyword is set, the return value of the function is
              a ncolors-element string array containing the names of the colors.
              These names would be appropriate, for example, in building
              a list widget with the names of the colors. If the NAMES
              keyword is set, the COLOR and INDEX parameters are ignored.

                 listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)

       ROW:   If this keyword is set, the return value of the function when the TRIPLE
              keyword is set is returned as a row vector, rather than as the default
              column vector. This is required, for example, when you are trying to
              use the return value to set the color for object graphics objects. This
              keyword is completely ignored, except when used in combination with the
              TRIPLE keyword.

       SELECTCOLOR: Set this keyword if you would like to select the color name with
              the PICKCOLORNAME program. Selecting this keyword automaticallys sets
              the INDEX positional parameter. If this keyword is used, any keywords
              appropriate for PICKCOLORNAME can also be used. If this keyword is used,
              the first positional parameter can be either a color name or the color
              table index number. The program will figure out what you want.

       TRIPLE: Setting this keyword will force the return value of the function to
              *always* be a color triple, regardless of color decomposition state or
              visual depth of the machine. The value will be a three-element column
              vector unless the ROW keyword is also set.

       In addition, any keyword parameter appropriate for PICKCOLORNAME can be used.
       These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.

 OUTPUT KEYWORD PARAMETERS:

       CANCEL: This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
              Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.

       COLORSTRUCTURE: This output keyword (if set to a named variable) will return a
              structure in which the fields will be the known color names (without spaces)
              and the values of the fields will be either color table index numbers or
              24-bit color values.

       NCOLORS: The number of colors recognized by the program. It will be 88 by default.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       None.

 ADDITIONAL PROGRAMS REQUIRED:

   PICKCOLORNAME: This file can be found in the Coyote Library:

             http://www.dfanning.com/programs/pickcolorname.pro

 EXAMPLE:

       To get drawing colors in a device-decomposed independent way:

           axisColor = FSC_COLOR("Green", !D.Table_Size-2)
           backColor = FSC_COLOR("Charcoal", !D.Table_Size-3)
           dataColor = FSC_COLOR("Yellow", !D.Table_Size-4)
           Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
           OPlot, Findgen(11), Color=dataColor

       To set the viewport color in object graphics:

           theView = Obj_New('IDLgrView', Color=FSC_Color('Charcoal', /Triple))

       To change the viewport color later:

           theView->SetProperty, Color=FSC_Color('Antique White', /Triple)

 MODIFICATION HISTORY:
       Written by: David Fanning, 19 October 2000. Based on previous
          GetColor program.
       Fixed a problem with loading colors with TVLCT on a PRINTER device. 13 Mar 2001. DWF.
       Added the ROW keyword. 30 March 2001. DWF.
       Added the PICKCOLORNAME code to the file, since I keep forgetting to
          give it to people. 15 August 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_color.pro)

FSC_DROPLIST

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
   FSC_DROPLIST

 PURPOSE:
   The purpose of this compound widget is to provide an alternative
   to the DROPLIST widget offered in the IDL distribution. What has
   always annoyed me about a droplist is that you can't get the current
   "value" of a droplist easily. This compound widget makes this and
   other tasks much easier.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)

   The return value of the FSC_Droplist (droplistObj in this example) is
   an object reference. Interaction with the droplist will occur through
   object methods.

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

 Any keyword that is appropriate for the Widget_Droplist function can be used.
 In addition, these keywords are explicitly defined.

   EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
   EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
   FORMAT -- A format specifier for the "format" of the values in the droplist.
   INDEX -- The index number of the current selection.
   SPACES -- A two-element array that indicates the number of blank spaces to be added
             to the the beginning and end of the formatted values. If a single number
             is provided, this number of blank spaces is added to both the beginning
             and the end of the value.
   TITLE -- The title of the droplist widget.
   UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
   UVALUE -- The normal "user value" of the droplist.
   VALUE -- An array of the droplist "selections". May be any data type.

 COMMON BLOCKS:

   None.

 DEPENDENCIES:

   Requires ERROR_MESSAGE from the Coyote Library..

 EVENT STRUCTURE:

   An event is returned each time the droplist value is changed. The event structure
   is defined like this:

   event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure.
             ID: 0L, $             ; The ID of the compound widget's top-level base.
             TOP: 0L, $            ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $        ; The event handler ID. Filled out by IDL.
             INDEX: 0L, $          ; The index number of the current selection.
             SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
             SELF:Obj_New() }      ; The object reference of the compound widget.

 PUBLIC OBJECT METHODS:

   GetID -- A function with no arguments that returns the widget identifier
      of the droplist widget.

      droplistID = droplistObj->GetID()

   GetIndex -- A function with no arguments that returns the index
      number of the current droplist selection.

      currentIndex = droplistObj->GetIndex()

   GetSelection -- A function with no arguments that returns the current
      droplist selection.

      currentSelection = droplistObj->GetSelection()

   GetUValue -- A function with no arguments that returns the "user value"
      of the compound widget i.e., the value set with the UVALUE keyword).

      myUValue = droplistObj->GetUValue()

   GetValues -- A function with no arguments that returns the "values" or
      "selections" for the droplist.

      possibleSelections = droplistObj->GetValues()

   Resize -- A procedure that sets the X screen size of the droplist. It is
      defined like this:

      PRO Resize, newSize, ParentSize=parentSize

      The "newSize" keyword is the new X screen size. If this argument is
      missing, the screen X size of the compound widget's parent is used.
      The parentSize keyword is an output keyword that returns the X screen
      size of the compound widget's parent.

      droplistObj->Resize, 400

      Note that not all devices (e.g., X Windows devices) support droplist resizing.

   SetIndex -- A procedure that sets the current droplist selection based on
      the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex

      droplistObj->SetIndex, newIndex

   SetSelection -- Whereas a regular droplist widget can only be set by index
      number, this compound widget can also be set by a "selection". The new selection
      can be any data type and corresponds to one of the "values" of the droplist.

      droplistObj->SetSelection, newSelection


 EXAMPLE:

   An example program is provided at the end of the FSC_DROPLIST code. To run it,
   type these commands:

      IDL> .Compile FSC_DROPLIST
      IDL> Example

 MODIFICATION HISTORY:

   Written by: David Fanning, 17 Jan 2000. DWF.
   Added FORMAT and SPACES keywords 28 April 2000. DWF.
   Fixed a small problem with event processing when the EVENT_FUNC keyword
      was used. 29 Dec 2000. DWF.
   Attached the UNAME value to the TLB of the compound widget instead
      of to the droplist widget itself. 11 Jan 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_droplist.pro)

FSC_FIELD

[Previous Routine] [Next Routine] [List of Routines]

NAME:
FSC_FIELD

PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. One weakness
of the CW_FIELD compound widget is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
will be helpful. For example, you can now assign an event handler
to the compound widget, ask for positive numbers only, and limit
the number of digits in a number, or the number of digits to the
right of a decimal point. The program is written as a widget object,
which allows the user to call object methods directly, affording
even more flexibility in use. This program replaces the earlier
programs FSC_INPUTFIELD and COYOTE_FIELD.

The program consists of a label widget next to a one-line text widget.
The "value" of the compound widget is shown in the text widget. If the
value is a number, it will not be possible (generally) to type
alphanumeric values in the text widget. String values behave like
strings in any one-line text widget.

AUTHOR:

CATEGORY:

General programming.

TYPICAL CALLING SEQUENCE:

fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)

INPUT PARAMETERS:

parent -- The parent widget ID of the compound widget. Required.

INPUT KEYWORDS:

COLUMN Set this keyword to have the Label widget above the Text widget.
The default is to have the Label widget in a row with the Text widget.

CR_ONLY Set this keyword if you only want Carriage Return events returned to
your event handler. If this keyword is not set, all events are returned.
Setting this keyword has no effect unless either the EVENT_PRO or
EVENT_FUNC keyword is used.

DECIMAL Set this keyword to the number of digits to the right of the decimal
point in floating point or double precision numbers. Ignored for STRING values.

DIGITS Set this keyword to the number of digits permitted in integer numbers.

EVENT_FUNC Set this keyword to the name of an event handler function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.

EVENT_PRO Set this keyword to the name of an event handler procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.

FIELDFONT The font name for the text in the text widget.

FRAME Set this keyword to put a frame around the compound widget.

LABEL_LEFT Set this keyword to align the text on the label to the left.

LABEL_RIGHT Set this keyword to align the text on the label to the right.

LABELFONT The font name for the text in the label widget.

LABELSIZE The X screen size of the label widget.

NAME A string containing the name of the object. The default is ''.

NOEDIT Set this keyword to allow no user editing of the input text widget.

NONSENSITIVE Set this keyword to make the input text widget non-sensitive.

POSITIVE Set this keyword if you want only positive numbers allowed.

SCR_XSIZE The X screen size of the compound widget.

SCR_YSIZE The Y screen size of the compound widget.

TITLE The string text placed on the label widget.

UNDEFINED Set this keyword to the value to use for "undefined" values. If
not set, then !Value.F_NAN is used for numerical fields and a
NULL string is used for string fields. This applies to values
obtained with the GET_VALUE method or the GET_VALUE function.

UVALUE A user value for any purpose.

VALUE The "value" of the compound widget. Any type of integer, floating, or string
variable is allowed. The data "type" is determined automatically from the
value supplied with this keyword. Be sure you set the type appropriately for
your intended use of the value.

XSIZE The X size of the text widget in the usual character units.

OUTPUT KEYWORDS:

OBJECT Set this keyword to a named variable to receive the compound widget's
object reference. This is required if you wish to call methods on the object.
Note that the object reference is also available in the event structure
generated by the widget object. Note that the object reference will be
necessary if you want to get or set values in the compound widget.

COMMON BLOCKS:

None.

RESTRICTIONS:

None.

EVENT STRUCTURE:

All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.

event = { FSC_FIELD_EVENT, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
VALUE: Ptr_New(), $ ; A pointer to the widget value.
TYPE:"" ; A string indicating the type of data in the VALUE field.
}

Note that if the field is "empty", the VALUE will be a pointer
to an undefined variable. You should check this value before you
use it. You code will look something like this:

IF N_Elements(*event.value) EQ 0 THEN $
Print, 'Current Value UNDEFINED.' ELSE $
Print, 'Current Value: ', *event.value

GETTING and SETTING VALUES:

Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
Traditional compound widgets have the ability to get and set the "value"
of the compound widget identifier (e.g., fieldID in the calling
sequence above). Unfortunately, it is impossible to retreive a variable
in this way when the variable is undefined. In practical terms, this
means that the undefined variable must be set to *something*. You can
determine what that something is with the UNDEFINED keyword, or I will set
it to !VALUES.F_NAN for numerical fields and to the null string for string
fields. In any case, you will have to check for undefined variables before
you try to do something with the value. For a numerical field, the code
might look something like this:

fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
currentValue = fieldObject->Get_Value()
IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue

Additional examples are provided in the numerical example fields in Example Program below.

Setting the value of the compound widget is the same as calling the Set_Value
method on the object reference. In other words, these two statements are equivalent.

fieldObject->Set_Value, 45.4
Widget_Control, fieldID, Set_Value=45.4

The data type of the value is determined from the value itself. Be sure you set it appropriately.

OBJECT PROCEDURE METHODS:

GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:

CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Name -- A scalar string name of the object.
NoEdit -- A 1 means the widget is non-editable.
NonSensitive -- A 1 means the widget is non-sensitive.
NonSensitive -- Set this keyword to make the widget non-sensitive.
Positive -- Indicates if the Positive number flag is set (1) or not (0).
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.

MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.

Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.

objectRef->Resize, screen_xsize_value

Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.

objectRef->Set_Value, 5

SetEdit -- This procedure turns editing on (value of 1) or off (value of 0).

SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:

CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
LabelSize -- The X screen size of the Label Widget.
Name -- A scalar string name of the object. (default = '')
NoEdit -- Set this keyword to make the widget non-editable.
NonSensitive -- Set this keyword to make the widget non-sensitive.
Positive -- Set this keyword to indicate only positive numbers are allowed.
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.

SetSensitive -- This procedure turns text widget sensitivity on (value of 1) or off (value of 0).

OBJECT FUNCTION METHODS:

Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:

IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()

GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.

GetLabelSize -- Returns the X screen size of the label widget. No parameters.

GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.

GetTextSize -- Returns the X screen size of the text widget. No parameters.

PRIVATE OBJECT METHODS:

Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.

MoveTab -- This method moves the cursor to end of the text in the widget identified
by the nexttab field. (This will be set with the SetTabNext method.)

Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.

ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.

Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.

EXAMPLE:

An example program is provided at the end of the FSC_FIELD code. To run it,
type these commands:

IDL> .Compile FSC_Field
IDL> Example

MODIFICATION HISTORY:

Written by: David Fanning, 18 October 2000. Based heavily on an earlier
FSC_INPUTFIELD program and new ideas about the best way to write
widget objects.
Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
Modified the way the value is returned in the GET_VALUE method and the
GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
methods. 19 Jan 2001. DWF.
Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 21 July 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_field.pro)

FSC_FILESELECT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
   FSC_FILESELECT

 PURPOSE:
   The purpose of this compound widget is to provide a means
   by which the user can type or select a file name. The
   program is written as an "object widget", meaning that
   the guts of the program is an object of class FSC_FILESELECT.
   This is meant to be an example of the obvious advantages of
   writing compound widget programs as objects.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

   General programming.

 CALLING SEQUENCE:

   filenameID = FSC_FileSelect(parent)

 INPUT PARAMETERS:

   parent -- The parent widget ID of the compound widget. Required.

 INPUT KEYWORDS:

   Event_Pro -- The event handler procedure for this compound widget.By default: "".
   Event_Func -- The event handler function for this compound widget. By default: "".

      If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.

   DirectoryName -- The initial name of the directory. By defaut: current directory.
   Filename -- The initial file name in the filename text widget.
   Filter -- The file filter. By default: "*".
   Frame -- Set this keyword for a frame around the compound widget.
   LabelFont -- The font for the label widget. By default: "".
   LabelName -- The text on the label widgt. By default: "Filename: ".
   LabelSize -- The X screen size of the label widget. By default: 0.
   MustExist -- A flag that indicates selected files must exist. By default: 0.
   NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.

     If this keyword is not set, the compound widget will automatically resize itself to
     the largest widget in its parent base widget. It will do this by changing the size of
     the text widgets holding the file and directory names.

   Read -- Set this keyword to have file selection for reading a file. By default: 1.
   SelectDirectory -- The default directory for file selection. In other words, this is the
     default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
   SelectFont -- The font for the "Browse" button. By default: "".
   SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
   TextFont -- The font for the filename text widget. By default: "".
   UValue -- User value for any purpose.
   Write -- Set this keyword to open a file for writing. By default: 0.
   XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.

 OUTPUT KEYWORDS:

   ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
                With the object reference you can call object methods to easily change many properties of
                the compound widget.

 COMMON BLOCKS:

   None.

 RESTRICTIONS:

   Probably doesn't work correctly on VMS systems :-( If you can help, please
   contact me. I don't have a VMS system to test on.

 EVENT STRUCTURE:

   All events are handled internally unless either the Event_Pro or Event_Func
   keywords are used to assign an event handler to the compound widget. All events
   generated by the text widgets are passed to the assigned event handler.

   event = { CW_FILESELECT, $     ; The name of the event structure.
             ID: 0L, $            ; The ID of the compound widget's top-level base.
             TOP: 0L, $           ; The widget ID of the top-level base of the hierarchy.
             HANDLER: 0L, $       ; The event handler ID. Filled out by IDL.
             Basename: "", $      ; The base filename without directory specifiers.
             Filename: "", $      ; The fully qualified filename.
             Filter: ::, $        ; The currently active file filter.
             Directory: "", $     ; The name of the current file directory.
           }

 EXAMPLE:

   An example program is provided at the end of the FSC_FILESELECT code. To run it,
   type these commands:

      IDL> .Compile fsc_fileselect
      IDL> Example

   Or, if you want to obtain the object reference, type this:

      IDL> Example, theObject

   Now you can call the object's methods. For example:

      IDL theObject->SetProperty, XSize=150

 GETTING and SETTING VALUES:

   So as not to disrupt the accepted paradigm in using compound widgets, you
   can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
   get and set the "value" of the widget.

       Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'

   The program will automatically separate the file name portion of the value
   from the directory portion and put things in the correct text widgets.

   Similarly, you can get the "value" of the widget:

       Widget_Control, filenameID, Set_Value=theValue
       Print, theValue

           C:\RSI\IDL52\DATA\cyclone.dat

   The return value is the fully qualified file path to the file.

 USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES:

   If you obtain the object reference, you have a great deal more control
   over the properties of the compound widget. You obtain the object reference
   by calling the function like this:

      filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)

 OBJECT PROCEDURE METHODS:

   GetProperty -- This method allows various properties of the widget to be
       returned via output keywords. The keywords that are available are:

      DirectoryName -- The current directory.
      Event_Func -- The name of the event handler function for this compound widget.
      Event_Pro -- The name of the event handler procedure for this compound widget.
      Filename -- The current base filename.
      Filter -- The current file filter.
      LabelName -- The text on the label widget.
      LabelSize -- The X screen size of the label widget.
      MustExist -- A flag that indicates selected files must exist to be selected.
      Parent -- The parent widget of the compound widget.
      Read=read -- The file selection for reading flag.
      SelectTitle -- The title bar text on the file selection dialog.
      TLB -- The top-level base of the compound widget.
      UValue -- The user value of the compound widget.
      Write -- The file selection for writing flag.
      XSize -- The X size of the text widget holding the filename.

   LabelSize -- This method makes sure that the directory name and file name labels
      are the same size. Normally, this procedure is called internally. No parameters.

   MatchSize -- This method resizes the compound widget so that it is as long as the
      the longest widget in the parent base widget. This is done automatically upon
      realization unless the NOMAXSIZE keyword is set. The method aids in writing
      resizeable widget programs.

   SetProperty -- This method allows various properties of the widget to be
       set via input keywords. The keywords that are available are:

      DirectoryName -- The current directory.
      Event_Func -- The name of the event handler function for this compound widget.
      Event_Pro -- The name of the event handler procedure for this compound widget.
      Filename -- The current base filename.
      Filter -- The current file filter.
      LabelName -- The text on the label widget.
      LabelSize -- The X screen size of the label widget.
      MustExist -- A flag that indicates selected files must exist to be selected.
      Read -- The file selection for reading flag.
      SelectTitle -- The title bar text on the file selection dialog.
      UValue -- The user value of the compound widget.
      Write -- The file selection for writing flag.
      XSize -- The X size of the text widget holding the filename.

 OBJECT FUNCTION METHODS:

      GetFileName -- Returns the fully qualified filename. No parameters.

      GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.

      Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.

        directoryName -- The name of the directory from the directory text widget.
        textSelection -- The current text selection position.

        At the moment all this does is remove any blank characters from either
        end of the directory name and makes sure the last character of the directory
        name does not end in a subdirectory specifier (except for VMS).

     Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.

        filename -- The name of the file from the filename text widget.
        textSelection -- The current text selection position.

        At the moment all this does is remove any blank characters from either
        end of the file name

 MODIFICATION HISTORY:

   Written by: David Fanning, 21 NOV 1999.
   Fixed bug in File Name selection button. 18 MAR 2000. DWF.
   Fixed an error in which directory the Browse buttons should start
       searching. 29 SEP 2000. DWF.
   Previously returned events only for typing in text widgets. Now
       Browse button events are also returned. 29 SEP 2000. DWF.
   Fixed a bug in setting the file filter. 29 SEP 2000. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_fileselect.pro)

FSC_INPUTFIELD

[Previous Routine] [Next Routine] [List of Routines]

NAME:
FSC_INPUTFIELD

PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. What has
always bothered me about CW_FIELD is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
would be helpful. For example, you can now assign an event handler
to the compound widget. The program is written entirely as an object.
A companion program, COYOTE_FIELD, has much the same functionality,
but is written as a traditional compound widget. The point of writing
the same program in two different ways is to give you the opportunity
to compare and contrast the two methods. I personally think there
is no substitute for the power of object programs. :-)

AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/

CATEGORY:

General programming.

CALLING SEQUENCE:

objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue)

INPUT PARAMETERS:

parent -- The parent widget ID of the compound widget. Required.

INPUT KEYWORDS:

Column -- Set this keyword to have the Label Widget above the Text Widget.
CR_Only -- Set this keyword if you only want Carriage Return events. If
this keyword is not set, all events are returned. No events
are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Event_Func -- Set this keyword to the name of an Event Function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
Event_Pro -- Set this keyword to the name of an Event Procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FieldFont -- The font name for the text in the Text Widget.
FloatValue -- Set this keyword for FLOAT values.
Frame -- Set this keyword to put a frame around the compound widget.
IntegerValue -- Set this keyword for INTEGER values.
LabelFont -- The font name for the text in the Label Widget.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword if you want only positive numbers allowed.
Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
Scr_XSize -- The X screen size of the compound widget.
Scr_YSize -- The Y screen size of the compound widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.

COMMON BLOCKS:

None.

RESTRICTIONS:

None.

EVENT STRUCTURE:

event = { FSC_FIELD, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
ObjRef: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
Value: Ptr_New(), $ ; A pointer to the widget value.
Type:"" ; A string indicating the type of data in the VALUE field.
} ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".

GETTING and SETTING VALUES:

Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
But since traditional compound widgets have the ability to get and
set the value of the compound widget, this capability is implemented
as special methods.

To get the value of the field, do this: value = objectRef->Get_Value()
To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue

The proper keyword should be used to set the data type of the value. If a keyword
is not used, the data type is determined from the value itself.

OBJECT PROCEDURE METHODS:

GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:

CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Positive -- Indicates if the Positive number flag is set (1) or not (0).
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
Name -- A scalar string name of the object.

objectRef->Resize, screen_xsize_value

Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.

objectRef->Set_Value, 5

Keywords available are these to set the type of the data. If keywords
are not used, the data type is determined from the value.

DoubleValue -- Set this keyword if you want DOUBLE values returned.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LongValue -- Set this keyword for LONG values.
StringValue -- Set this keyword for STRING values. (The default.)

SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:

CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword to indicate only positive numbers are allowed.
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.

OBJECT FUNCTIONS METHODS:

Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:

IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()

GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.

GetLabelSize -- Returns the X screen size of the label widget. No parameters.

GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.

GetTextSize -- Returns the X screen size of the text widget. No parameters.

PRIVATE OBJECT METHODS:

MoveTab -- This method moves the cursor to end of the text in the widget identified
by the nexttab field. (This will be set with the SetTabNext method.)

Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.

ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.

EXAMPLE:

An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
type these commands:

IDL> .Compile FSC_InputField
IDL> Example

MODIFICATION HISTORY:

Written by: David Fanning, 23 NOV 1999.
Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
Changed the calling sequence to that of a function rather than an object
creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
Added GetID and Resize methods. 7 Jan 00. DWF.
Added the Positive keyword and functionality. 12 Jan 00. DWF
Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
If a number field is blank, the Get_Value method will now return an undefined variable.
Be sure you check this value before you use it for something! 17 Jan 00. DWF.
Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
MoveTab, and GetTextID methods. 31 July 2000. DWF.
Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
Added ObjRef field to the FSC_FIELD event structure and added field selection
for the TAB events added 31 July. 7 AUG 2000. DWF
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 30 Jan 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_inputfield.pro)

FSC_PLOTWINDOW

[Previous Routine] [Next Routine] [List of Routines]

NAME:
FSC_PLOTWINDOW

PURPOSE:
The purpose of this compound widget is to create a resizeable
"plot window" inside a larger "page window". I'm not sure it
has any value except as a utility routine for the PostScript
configuration object FSC_PSCONFIG__DEFINE, but it's a neat
program anyway. :-)

AUTHOR:

CATEGORY:

Utility routine for FSC_PSCONFIG__DEFINE.

CALLING SEQUENCE:

plotwindowObject = CW_PlotWindow(parent)

REQUIRED INPUT PARAMETERS:

parent - The parent base widget of this compound widget.

RETURN VALUE:

plotwindowObject - The object reference of the compound widget.

KEYWORDS:

COLOR - If set, display the window in "color". This is the default on 24-bit devices.
DEBUG - Set this keyword to turn traceback error handling on in the error handling code.
EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally.
LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode.
PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY".
UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "".
UVALUE - A user value for the caller of this program.
WINDOWCOLOR - A three-element array specifying the background window color (RGB).
WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1].

EVENT STRUCTURE:

The event structure that is returned from this compound widget is defined like this,
where the sizes and offsets locate the target "window" on the page in normalized units:

event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0}

MODIFICATIONS:

Written by David Fanning, 31 January 2000.
Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF.
Added a "DISPLAY" page size, so the program can be used to position
plots and other graphics in a display window. The "page area" will
have the same aspect ratio is the current graphics window. 17 March 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_plotwindow.pro)

FSC_PSCONFIG__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

NAME:
FSC_PSCONFIG__DEFINE

PURPOSE:
The purpose of this program is to implement an object that
can keep track of--and allow the user to change--the current
configuration of the PostScript device.

AUTHOR:

CATEGORY:

General programming.

DOCUMENTATION:

Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:

http://www.dfanning.com/programs/docs/fsc_psconfig.html

Or, if you would prefer, you can download a self-contained PDF file:

http://www.dfanning.com/programs/docs/fsc_psconfig.pdf

KEYWORDS:

Any keyword accepted by the FSC_PSCONFIG object can be used with
this program. Here are a few of the most popular keywords.

Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
Color - Set this keyword to select Color PostScript output. Turned on by default.
DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
create and add your own to the source code) are the following:

"System (Portrait)" - The normal "default" system set-up. Also, "System".
"System (Landscape)" - The normal "default" landscape system set-up.
"Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
"Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
"Square (Portrait)" - A square plot, centered on the page.
"Square (Landscape)" - A square plot, centered on the landscape page.
"Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
"Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
"Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
"Color (Landscape)" - A "centered" landscape plot, with color turned on.

Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
Encapsulate - Set this keyword to select Encapsulated PostScript output. Turned off by default.
European - Set this keyword to indicate "european" mode (i.e., A4 page and centimeter units). Turned off by default.
Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by European keyword by default.
Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
PageType - Set this keyword to the "type" of page. Possible values are:
"Letter" - 8.5 by 11 inches. (Default, unless the European keyword is set.)
"Legal" - 8.5 by 14 inches.
"Ledger" - 11 by 17 inches.
"A4" - 21.0 by 29.7 centimeters. (Default, if the European keyword is set.)
XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.

In addition, the following keywords can be used:

CANCEL -- An output keyword that will be set to 1 if the user
chooses the Cancel button on the form. It will be 0 otherwise.

FONTINFO -- Set this keyword is you wish to have font information
appear on the form. The default is to not include font information.

FONTTYPE -- Set this keyword to a named variable that will indicate
the user's preference for font type. Values will be -1 (Hershey fonts),
0 (hardware fonts), and 1 (true-type fonts). This keyword will always
return -1 unless the FONTINFO keyword has also been set.

GROUP_LEADER -- Set this keyword to a widget identifier of the widget
you wish to be a group leader for this program.

EXAMPLE:

A simple sequence of using the object would look something like this:

psObject = Obj_New("FSC_PSCONFIG")
psObject->GUI
psKeywords = psObject->GetKeywords()
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=psKeywords
TVImage, image
Device, /Close_File
Set_Plot, thisDevice
Obj_Destroy, psObject

Note that the object can also be called from the PS_CONFIG interface:

psKeywords = PSConfig()

OTHER PROGRAMS NEEDED:

The following programs are required to run this one:

fsc_droplist.pro
fsc_fileselect.pro
fsc_field.pro
fsc_plotwindow

MODIFICATIONS:

Written by David Fanning, 31 January 2000.
Added capability to call GUI methods when the current graphics device
doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF.
Changed the default value for the Color keyword to 1. 16 May 2000. DWF.
Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF.
Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF.
Added the ability to Get and Set the object's name via the SetProperty
and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF.
Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF.
Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF.
Fixed a bug when setting file and directory names with the SetProperty method. 18 Dec 2000. DWF.
Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF.
Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF.
Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF.
Increased the length of the file/directory name fields. 7 Jan 2001. DWF.
Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF.
Seems I only half fixed the previous problem. :-( 26 April 2001. DWF.
Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF.
Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF.
Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF.
Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF.

(See $IDL_LOCAL\mpi_plot\fsc_psconfig__define.pro)

MPI_AXIS__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

NAME:
MPI_AXIS__DEFINE

PURPOSE:
This is a compound widget program for interactively adjusting and keeping track
of keywords appropriate for configuing axis properties.

AUTHOR:

CATEGORY:

Graphics

CALLING SEQUENCE:

xAxisObjext = Obj_New("MPI_AXIS", /XAxis)
xAxisID = xAxisObject->GUI(baseWidgetID)

INPUT PARAMETERS:

None.

INPUT KEYWORDS (Sent to the INIT method. The same keywords can be set with the SETPROPERTY method of the object.):

AUTOKEYWORDS - An anonymous struture of keywords that are passed to the AutoRange function.

AUTORANGE - The name of a function that can return axis range information as 2-element array.

CHARSIZE - The character size used for the axis. By default, 1.0.

EXACT - Set to indicate exact axis range scaling. (Can also be set with the STYLE keyword.)

EXTEND - Set to indicate extended axis range. (Can also be set with the STYLE keyword.)

GRIDSTYLE - The style used for drawing grid lines.

HIDE - Set to indicate hidden axis style. (Can also be set with the STYLE keyword.)

LOG - Set to indicate logarithmic axis.

MARGIN - The axis margin. (Currently unimplemented.)

MINOR - The number of minor tick marks between the major tick marks on the axis.

NAME = A user-defined "name" for the object.

NOBOX - Set to inhibit box-style axis. (Can also be set with the STYLE keyword.)

NOZERO - Set to indicate NO_ZERO axis style. (Can also be set with the STYLE keyword.)

RANGE - The axis range as a two-element array, [minrange, maxrange].

STYLE - The axis style. A 32-bit value whose bits select certain properties. See the
on-line documentation for the !X.STYLE system variable for more information. These
style properties can be set in a more natural way with other keywords.

THICK - The thickness of the axis. By default, 1.0.

TICKFORMAT - The format to use with tick marks. May be name of procedure.

TICKINTERVAL - The interval to space tick marks for first-level axis. (Currently not implemented.)

TICKLAYOUT - The type of tick layout desired. (Currently not implemented.)

TICKLEN - The length of the ticks on the axis. By default, 0.0. (Note that changing this
value will cause the Plot TICKLEN value to be ignored for the axis.)

TICKNAME - The string names associated with each tick mark. (Currently not implemented.)

TICKS - The number of major tick intervals.

TICKUNITS - The units to use for tick labeling. (Currently not implemented.)

TICKV - A vector of tick values. (Currently not implemented.)

TITLE - The axis title.

XAXIS - Set to indicate an X axis object. This is the default.

YAXIS - Set to indicate a Y axis object.

ZAXIS - Set to indicate a Z axis.

METHOD PROCEDURES:

GUI - This procedure method displays a graphical user interface that allows the user
to change the axis configuration parameters.

PARAMETERS:

parent - The parent of the compound widget.

KEYWORDS:

EVENT_PRO - The specified event handler procedure.
EVENT_FUNC - The specified event handler function.
ONLY_STYLE - If set, display only style parameters in the GUI.
ONLY_TICK - If set, display only tick parameters in the GUI.
SHORT_FORM - Normally, all the axis properties are displayed in the GUI. Setting
this keyword places the Tick and Style properties behind buttons on the interface.
UVALUE - The user value of the compound widget.

SETPROPERTY - This procedure can be used to set the properties of the axis
configuration object without using the graphical user interface. The
keywords are identical to those used in the INIT method, above.

METHOD FUNCTIONS:

GETKEYWORDS - This function method contains no arguments or keywords. It returns a
structure, with fields equivalent to PLOT keywords for setting axis properties.
The idea is that these keywords can be passed directly to the PLOT command using
the keyword inheritance mechanism via the _EXTRA keyword to the plot command. ished with it.

PROGRAM NOTES:

Required Programs: The following programs are required to reside in your !PATH. They can be
obtained from the Coyote Library:

http://www.dfanning.com/programs/cw_spacer.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/fsc_droplist.pro
http://www.dfanning.com/programs/fsc_field.pro

EXAMPLE:

A heavily documented program, named MPI_PLOT, is supplied with this program.
This program not only explains how to use the MPI_PLOTCONFIG__DEFINE and the
MPI_AXIS__DEFINE programs, it can be used as a wrapper program for the PLOT command
that you can use with your own data. The program can be downloaded here:

http://www.dfanning.com/programs/mpi_plot.pro

MODIFICATION HISTORY:

Written by David Fanning, March 2001.

(See $IDL_LOCAL\mpi_plot\mpi_axis__define.pro)

MPI_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       MPI_PLOT

 PURPOSE:
       This program is a simple wrapper for the IDL PLOT command.
       The main purpose of the program is to demonstrate one way the
       MPI_PLOTCONFIG program can be used to update plot parameters.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics

 CALLING SEQUENCE:

       MPI_Plot, x, y
       MPI_Plot, xx, yy, /Overplot

 INPUT PARAMETERS:

       x - The independent data. If y is not present, x is taken to be the dependent data.

       y - The dependent data. The vectors x and y must be the same length.

       xs - The independent data to overplot. If yy is not present, xx is taken to be the dependent data.

       yy - The dependent data to overplot. The vectors xx and yy must be the same length.

 INPUT KEYWORDS:

       BACKGROUND - The name of a background color. (See below for a list of color names.)
         By default on 24-bit systems: 'IVORY'. Uses 'GRAY' on 8-bit systems.

       COLOR - The name of the plot color. (See below for a list of color names.)
         By default on 24-bit systems: 'SADDLE BROWN'. Uses 'GREEN' on 8-bit systems.
         When OVERPLOTing, use the COLOR keyword to specify the color of the overplot.

       DATACOLOR - The name of the data color. By default the same as the COLOR keyword.
         (See below for a list of color names.) When OVERPLOTing, use the COLOR keyword
         to specify the color of the overplot.

       PSYM - The plot symbol value. By default, 18. Possible values are:
         0 - Dot
         1 - Filled Circle
         2 - Filled Upward Triangle
         3 - Filled Downward Triangle
         4 - Filled Diamond
         5 - Filled Square
         6 - Open Circle
         7 - Open Upward Triangle
         8 - Open Downward Triangle
         9 - Open Diamond
        10 - Open Square
        11 - Plus Sign
        12 - X
        13 - Star
        14 - Filed Rightfacing Triangle
        15 - Filled Leftfacing Triangle
        16 - Open Rightfacing Triangle
        17 - Open Leftfacing Triangle
        18 - No Symbol (the default).

       TITLE - The title of the plot. By default, a null string.

       XTITLE - The title of the X axis of the plot. By default, a null string.

       YTITLE - The title of the Y axis of the plot. By default, a null string.

       In addition, any keyword appropriate for the MPI_PLOTCONFIG object program can be used.
       Among those keywords, are these most popular ones:

       CHARSIZE - The character size of the plot. By default, 1.0.

       CHARTHICK - The character thickness of the plot. By default, 1.0.

       FONT - The type of plot font: -1=Hershey, 0=Hardware, 1=True-Type. By default, !P.FONT.

       LINESTYLE - The plot linestyle. By default, 0. Possible values are:
         0 - Solid Line
         1 - Dotted
         2 - Dashed
         3 - Dash Dot
         4 - Dash Dot Dot
         5 - Long Dash
         6 - No Line

       POSITION - The position of the plot in the plot window in normalized coordinates. By default, [0.20, 0.15, 0.95, 0.95].

       SYMSIZE - The plot symbol size. By default, 1.0.

       THICK - The plot line thickness. By default, 1.0.

       TICKLEN - The plot tick length. By default, 0.02.

 COLOR NAMES:

        The following color names can be used for BACKGROUND, COLOR and DATACOLOR keywords:

           White, Snow, Ivory, Light Yellow, Cornsilk, Beige, Seashell, Linen, Antique White,
           Papaya, Almond, Bisque, Moccasin, Wheat, Burlywood, Tan, Light Gray, Lavender,
           Medium Gray, Gray, Slate Gray, Dark Gray , Charcoal, Black, Light Cyan, Powder Blue,
           Sky Blue, Steel Blue, Dodger Blue, Royal Blue, Blue, Navy, Honeydew, Pale Green,
           Aquamarine, Spring Green, Cyan, Turquoise, Sea Green, Forest Green, Green Yellow,
           Chartreuse, Lawn Green, Green, Lime Green, Olive Drab, Olive, Dark Green, Pale Goldenrod,
           Khaki, Dark Khaki, Yellow, Gold, Goldenrod, Dark Goldenrod, Saddle Brown, Rose,
           Pink, Rosy Brown, Sandy Brown, Peru, Indian Red, Chocolate, Sienna, Dark Salmon,
           Salmon, Light Salmon, Orange, Coral, Light Coral, Firebrick, Brown, Hot Pink,
           Deep Pink, Magenta, Tomato, Orange Red, Red, Violet Red, Maroon, Thistle, Plum,
           Violet, Orchid, Medium Orchid, Dark Orchid, Blue Violet, and Purple.

 REQUIRED PROGRAMS:

        The following programs are required to reside in your !PATH. They can be
        obtained from the Coyote Library:

                     http://www.dfanning.com/programs/adjustposition.pro
                     http://www.dfanning.com/programs/cw_drawcolor.pro
                     http://www.dfanning.com/programs/cw_spacer.pro
                     http://www.dfanning.com/programs/error_message.pro
                     http://www.dfanning.com/programs/fsc_color.pro
                     http://www.dfanning.com/programs/fsc_droplist.pro
                     http://www.dfanning.com/programs/fsc_field.pro
                     http://www.dfanning.com/programs/fsc_fileselect.pro
                     http://www.dfanning.com/programs/fsc_inputfield.pro
                     http://www.dfanning.com/programs/fsc_psconfig__define.pro
                     http://www.dfanning.com/programs/mpi_plotconfig__define.pro
                     http://www.dfanning.com/programs/mpi_axis.pro
                     http://www.dfanning.com/programs/mpi_axis__define.pro
                     http://www.dfanning.com/programs/pickcolorname.pro
                     http://www.dfanning.com/programs/psconfig.pro
                     http://www.dfanning.com/programs/pswindow.pro
                     http://www.dfanning.com/programs/tvread.pro

         All these programs can be obtained at once by downloading the MPI_PLOT zip file:

                     http://www.dfanning.com/programs/mpi_plot.zip


 RESTRICTIONS:

       The addition of the OVERPLOT keyword required a COMMON block. Thus, only
       one version of MPI_PLOT can be active at any particular time.

       Colors will be loaded in the color table.

 EXAMPLE:

       x = Findgen(11) & y = Findgen(11)
       MPI_PLOT, x, y
       MPT_PLOT, Reverse(x), y, /Overplot, Linestyle=2

 MODIFICATION HISTORY:

       Written by David Fanning, March 2001, and offered to the IDL user
       community by the Max-Plank Institute of Meteorology in  Hamburg, Germany.
       Added OVERPLOT keyword and made numerous general improvements. 21 November 2001. DWF

(See $IDL_LOCAL\mpi_plot\mpi_plot.pro)

MPI_PLOTCONFIG__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

NAME:
MPI_PLOTCONFIG__DEFINE

PURPOSE:

This is a program for interactively adjusting and keeping track
of keywords appropriate for configuring the PLOT command.

AUTHOR:

CATEGORY:

Graphics

CALLING SEQUENCE:

plotConfigObj = Obj_New("MPI_PLOTCONFIG")

INPUT PARAMETERS:

None.

INPUT KEYWORDS (Sent to the INIT method. The same keywords can be set with the SETPROPERTY method of the object.):

BACKGROUND - The name of the background color. By default on 24-bit systems: 'IVORY'. ON 8-bit systems 'GRAY'.

CHARSIZE - The character size of the plot. By default, 1.0.

CHARTHICK - The character thickness of the plot. By default, 1.0.

COLOR - The name of the plot color. (This will be the axis color if DATACOLOR is also used.)
By default on 24-bit systems: 'SADDLE BROWN'. Uses 'GREEN' on 8-bit systems.

DATACOLOR - The name of the data color. (Requires use of USEDATACOLOR to be active.) By default
on 24-bit systems: 'NAVY'. Uses 'YELLOW' on 8-bit systems.

_EXTRA - Extra keywords to be passed to MPI_AXIS objects used internally.

FONT - The type of plot font: -1=Hershey, 0=Hardware, 1=True-Type. By default, !P.FONT.;

LINESTYLE - The plot linestyle. By default, 0. Possible values are:
0 - Solid Line
1 - Dotted
2 - Dashed
3 - Dash Dot
4 - Dash Dot Dot
5 - Long Dash
6 - No Line

NOAXISINFO - Set this keyword to inhibit axis information on the GUI. By default, 0.

POSITION - The position of the plot in the plot window in normalized coordinates. By default, [0.20, 0.15, 0.95, 0.95].

PSYM - The plot symbol value. By default, 18. Possible values are:
0 - Dot
1 - Filled Circle
2 - Filled Upward Triangle
3 - Filled Downward Triangle
4 - Filled Diamond
5 - Filled Square
6 - Open Circle
7 - Open Upward Triangle
8 - Open Downward Triangle
9 - Open Diamond
10 - Open Square
11 - Plus Sign
12 - X
13 - Star
14 - Filed Rightfacing Triangle
15 - Filled Leftfacing Triangle
16 - Open Rightfacing Triangle
17 - Open Leftfacing Triangle
18 - No Symbol (the default).

SYMSIZE - The plot symbol size. By default, 1.0.

SUBTITLE - The plot subtitle. By default, "".

TITLE - The plot title. By default, "".

THICK - The plot line thickness. By default, 1.0.

TICKLEN - The plot tick length. By default, 0.02.

USEDATACOLOR - Set this keyword to return a DATACOLOR field in the keyword structure. By default, 0.

XAXIS - An MPI_AXIS object for the X axis. One is created by default, if not provided.

YAXIS - An MPI_AXIS object for the Y axis. One is created by default, if not provided.

METHOD PROCEDURES:

GUI - This procedure method displays a graphical user interface that allows the user
to change plot configuration parameters. The following keywords can be used:

ALL_EVENTS - Set this keyword to have an event sent any time something in the
GUI changes. The default is to send an event only when the user hits the ACCEPT button.
Note that the NOTIFYID keyword must be used to generate events.

BLOCK - Set this keyword if you want to block the command line. The default is to NOT block the command line.

DEFAULTFONT - The name of a font to use as the default font.

GROUP_LEADER - The group leader for this GUI. If this keyword is used, the program will be
distroyed when the group leader is destroyed.

LABELDEFAULTSIZE - The default screen size for a label. All labels are offsets from this size. 55 by default.
The purpose of this keyword is to allow the user to modify the look of the GUI if different
fonts are used.

LABELFONT - The name of a font to use for program labels.

NOTIFYID - A two-element array containing the widget identifier and top-level base ID of a widget
designated to receive an event from this program. The event structure will be defined and sent
like this:

Widget_Control, notifyid[0], Send_Event={ MPI_PLOTCONFIG_EVENT, $
ID: notifyid[0], $
TOP:notifyid[1], $
HANDLER: 0L, $
OBJECT: self }

Most event handlers will be written so that they will get the plot keywords
from the plot configuration object and draw the plot. A sample event handler might
look like this:

PRO MPI_Plot_Configuration_Events, event
Widget_Control, event.top, Get_UValue=info, /No_Copy
WSet, info.wid
plotkeywords = event.object->GetKeywords()
Plot, info.indep, info.dep, _Extra=plotkeywords
Widget_Control, event.top, Set_UValue=info, /No_Copy
END

XLONGFORM - By default, the X axis information is displayed in "short" form, with only the
most relevant information readily available. Other axis information is accessed via buttons.
Set this keyword to display the X axis information in a "long" form, in which all the axis
information is immediately visible.

YLONGFORM - By default, the Y axis information is displayed in "short" form, with only the
most relevant information readily available. Other axis information is accessed via buttons.
Set this keyword to display the Y axis information in a "long" form, in which all the axis
information is immediately visible.

SETPROPERTY - This procedure can be used to set the properties of the plot
configuration object without using the graphical user interface. The
keywords are identical to those used in the INIT method, above.

METHOD FUNCTIONS:

GETKEYWORDS - This function method contains no arguments or keywords. It returns a
structure, with fields equivalent to PLOT keywords. The idea is that these
keywords can be passed directly to the PLOT command using the keyword inheritance
mechanism via the _EXTRA keyword to the plot command. A possible sequence of commands
might look like this:

IDL> plotConfigObj = Obj_New("MPI_PLOTCONFIG") ; Create the plot configuration object.
IDL> plotConfigObj->GUI, /Block ; Allow the user to configure the plot parameters.
IDL> plotKeywords = plotConfigObj->GetKeywords() ; Get the plot keywords.
IDL> Plot, x, y, _Extra=plotKeywords ; Draw the plot in the way the user specified.
IDL> Obj_Destroy, plotConfigObj ; Destroy the object when finished with it.

PROGRAM NOTES:

Color Names: Color names are those used with FSC_Color and PickColorName. See the
documentation for those programs for instuctions on loading your own colors.
To see the default colors and names, type this:

IDL> color = PickColorName('yellow')

Working with DataColor: Many people like to have the data color in a line plot
different from the axis color. This requires two commands in IDL: a PLOT command
with the NODATA keyword set, to draw in the axis color, followed by the OPLOT command,
with the data drawn in the data color. Unfortunately, IDL only has a single COLOR keyword
to represent both colors. So, you must be a bit resourceful to use this feature.

The proper sequence of commands to use this feature of the plot configuration object
will looks like this. First, initialize the object with the USEDATACOLOR keyword:

plotConfigObj = Obj_New("MPI_PLOTCONFIG", /UseDataColor) ; Use the DataColor option.

When you are ready to draw the plot, the keyword structure will have a new field named
DataColor. Since this keyword is not recognized by the PLOT command, it will be ignored
in the first PLOT command to draw the axes:

plotKeywords = plotConfigObj->GetKeywords() ; Get the plot keywords.
Plot, x, y, _Extra=plotKeywords, /NoData ; Just draw the axes.

Next, change the color field to the datacolor field value, and overplot the
data onto the axes you just drew:

plotKeywords.color = PlotKeywords.datacolor
OPlot, x, y, _Extra=plotKeywords

You can see an example of how this is done in the heavily documented example program
MPI_PLOT, which you can use as a wrapper for the PLOT command with your own data, if you like.

Required Programs: The following programs are required to reside in your !PATH. They can be
obtained from the Coyote Library:

http://www.dfanning.com/programs/adjustposition.pro
http://www.dfanning.com/programs/cw_drawcolor.pro
http://www.dfanning.com/programs/cw_spacer.pro
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/fsc_color.pro
http://www.dfanning.com/programs/fsc_droplist.pro
http://www.dfanning.com/programs/fsc_field.pro
http://www.dfanning.com/programs/fsc_plotwindow.pro
http://www.dfanning.com/programs/mpi_axis__define.pro
http://www.dfanning.com/programs/pickcolorname.pro
http://www.dfanning.com/programs/pswindow.pro
http://www.dfanning.com/programs/tvread.pro

EXAMPLE:

A heavily documented program, named MPI_PLOT, is supplied with this program.
This program not only explains how to use the MPI_PLOTCONFIG__DEFINE program,
it can be used as a wrapper program for the PLOT command that you can use with
your own data. The program can be downloaded here:

http://www.dfanning.com/programs/mpi_plot.pro

MODIFICATION HISTORY:

Written by David Fanning, March 2001.

(See $IDL_LOCAL\mpi_plot\mpi_plotconfig__define.pro)

PICKCOLORNAME

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       PICKCOLORNAME

 PURPOSE:
       The purpose of this program is to provide a blocking
       or modal widget interface for selecting a color "name".
       The program uses colors familiar to the FSC_COLOR program,
       and is often used to select a color name for passing to FSC_COLOR.

 AUTHOR:

       FANNING SOFTWARE CONSULTING:
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics, Color Specification.

 CALLING SEQUENCE:

       colorName = PickColorName(startColorName)

 OPTIONAL INPUT PARAMETERS:
       startColorName: A string with the "name" of the color. Valid names
           depend on program variables, but typically include these colors:

              Black       Pink
              Magenta     Aqua
              Cyan        SkyBlue
              Yellow      Beige
              Green       Charcoal
              Red         Gray
              Blue        Orchid
              Navy        White

       The color WHITE is used if this parameter is absent.

 INPUT KEYWORD PARAMETERS:

       BOTTOM: The colors used in the program must be loaded somewhere
           in the color table. This keyword indicates where the colors
           start loading. By default BOTTOM is set equal to !D.Table_Size-NCOLORS-1.

       COLUMNS: Set this keyword to the number of columns the colors should
           be arranged in.

       FILENAME: The string name of an ASCII file that can be opened to read in
           color values and color names. There should be one color per row
           in the file. Please be sure there are no blank lines in the file.
           The format of each row should be:

              redValue  greenValue  blueValue  colorName

           Color values should be between 0 and 255. Any kind of white-space
           separation (blank characters, commas, or tabs) are allowed. The color
           name should be a string, but it should NOT be in quotes. A typical
           entry into the file would look like this:

               255   255   0   Yellow

       GROUP_LEADER: This identifies a group leader if the program is called
           from within a widget program. Note that this keyword MUST be provided
           if you want to guarantee modal widget functionality. (If you don't know
           what this means, believe me, you WANT to use this keyword, always.)

       INDEX: This keyword identifies a color table index where the selected color
           is to be loaded when the program exits. The default behavior is to restore
           the input color table and NOT load a color.

       TITLE: This keyword accepts a string value for the window title. The default
           is "Select a Color".

 OUTPUT KEYWORD PARAMETERS:

       CANCEL: On exit, this keyword value is set to 0 if the user selected
           the ACCEPT button. IF the user selected the CANCEL button, or
           closed the window in any other way, this keyword value is set to 1.

 COMMON BLOCKS:

       None.

 SIDE EFFECTS:

       Colors are loaded in the current color table. The input color table
       is restored when the program exits. This will only be noticable on
       8-bit displays. The startColorName is returned if the user cancels
       or destroys the widget before a selection is made. Users should
       check the CANCEL flag before using the returned color.

 EXAMPLE:

       To call the program from the IDL comamnd line:

         IDL> color = PickColorName("red") & Print, color

       To call the program from within a widget program:

         color = PickColorName("red", Group_Leader=event.top) & Print, color

 MODIFICATION HISTORY:

       Written by: David Fanning, 31 August 2000.
       Modified program to read colors from a file and to use more
         colors on 24-bit platforms. 16 October 2000. DWF.
       Added the COLUMNS keyword. 16 October 2000. DWF.
       Fixed a small problem with mapping a modal widget. 2 Jan 2001. DWF

(See $IDL_LOCAL\mpi_plot\pickcolorname.pro)

PSCONFIG

[Previous Routine] [Next Routine] [List of Routines]

NAME:
PSCONFIG

PURPOSE:
This program is simply a function wrapper for the FSC_PSCONFIG
object program (fsc_psconfig__define.pro). It was written so
that it could serve as a drop-in replacement for the PS_FORM
program it replaces. It calls the object program's graphical
user interface as a modal widget and returns the DEVICE keywords
collected from the form in a form that is appropriate for
configuring the PostScript device.

AUTHOR:

CALLING SEQUENCE:

psKeywords = PSConfig()

CATEGORY:

Configuring PostScript output.

DOCUMENTATION:

Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:

http://www.dfanning.com/programs/docs/fsc_psconfig.html

INPUT:

psConfigObject -- An optional FSC_PSCONFIG object reference can be
passed as an argument to the function. The object is not destroyed
if passed in as an argument.

psObject = Obj_New("FSC_PSCONFIG")
keywords = PSConfig(psObject)

Having the object means that you have an on-going and current record
of exactly how your PostScript device is configured. Be sure to destroy
the object when you are finished with it.

KEYWORDS:

Any keyword accepted by the FSC_PSCONFIG object can be used with
this program. Here are a few of the most popular keywords.

"System (Portrait)" - The normal "default" system set-up. Also, "System".
"System (Landcape)" - The normal "default" landscape system set-up.
"Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
"Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
"Square (Portrait)" - A square plot, centered on the page.
"Square (Landscape)" - A square plot, centered on the landscape page.
"Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
"Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
"Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
"Color (Landscape)" - A "centered" landscape plot, with color turned on.

In addition, the following keywords can be used:

CANCEL -- An output keyword that will be set to 1 if the user
chooses the Cancel button on the form. It will be 0 otherwise.

FONTINFO -- Set this keyword is you wish to have font information
appear on the form. The default is to not include font information.

GROUP_LEADER -- Set this keyword to a widget identifier of the widget
you wish to be a group leader for this program.

EXAMPLE:

To have the user specify PostScript configuration parameters, use
the program like this:

keywords = PSConfig(Cancel=cancelled)
IF cancelled THEN RETURN
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=keywords
Plot, findgen(11) ; Or whatever graphics commands you use.
Device, /Close_File
Set_Plot, thisDevice

OTHER PROGRAMS NEEDED:

The following programs are required to run this one:

fsc_droplist.pro
fsc_fileselect.pro
fsc_inputfield.pro
fsc_plotwindow
fsc_psconfig__define.pro

MODIFICATIONS:

Written by David Fanning, 31 January 2000.

(See $IDL_LOCAL\mpi_plot\psconfig.pro)

PSWINDOW

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
    PSWINDOW

 PURPOSE:
    This function is used to calculate the size of a PostScript window
    that has the same aspect ratio (ratio of height to
    width) as the current display graphics window. It creates
    the largest possible PostScript output window with the
    desired aspect ratio. This assures that graphics output
    looks similar, if not identical, to PostScript output.

 AUTHOR:

   FANNING SOFTWARE CONSULTING
   David Fanning, Ph.D.
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: davidf@dfanning.com
   Coyote's Guide to IDL Programming: http://www.dfanning.com/

 CATEGORY:

    Graphics.

 CALLING SEQUENCE:

    pageInfo = PSWINDOW()

 INPUTS:

    None.

 KEYWORD PARAMETERS:

    CM: Normally the structure value that is returned from this
    function reports its values in inches. Setting this keyword
    causes the return values to be in units of centimeters.

    FUDGE: A quick way to set symetrical XFUDGE and YFUDGE factors.
    If this keyword is set to a value, XFUDGE and YFUDGE keywords are
    set to the same value.

    LANDSCAPE: Normally this function assumes a PostScript window
    in Portrait mode. Setting this keyword assumes you want
    the graphic in Landscape mode.

    MARGIN:  The margin around the edges of the plot. The value must be
    a floating point value between 0.0 and 0.5. It is expressed in
    normalized coordinate units. The default margin is 0.15.

    PAGESIZE: Set this keyword to a string indicating the type
    of PostScript page size you want. Current values are "LETTER",
    "LEGAL", and "A4". Default is "LETTER".

    PRINTER: Set this keyword if the output will be used to
    configure the PRINTER device, rather than the PS device.
    (In the PRINTER device, offsets are always calculated from
    the lower-left corner of the page and do not rotate in
    Landscape mode, as they do with the PS device.) Note that
    the PRINTER device is only able to accept these keywords
    in IDL 5.1 and higher.

    XFUDGE: Printers calculate the offset point from the printable
    edge of the paper (sometimes), rather from the corner of the paper.
    For example, on my Lexmark printer, both X and Y offsets are
    calculated from a point 0.25 inches in from the edge. This keyword
    allows you to set a "fudge" factor that will be subtracted from
    the XOFFSET that is returned to the user. This allows you to create
    output that is centered on the page. The fudge factor should be in
    the same units as the returned size and offset values.

    YFUDGE: Printers calculate the offset point from the printable
    edge of the paper (sometimes), rather from the corner of the paper.
    For example, on my Lexmark printer, both X and Y offsets are
    calculated from a point 0.25 inches in from the edge. This keyword
    allows you to set a "fudge" factor that will be subtracted from
    the YOFFSET that is returned to the user. This allows you to create
    output that is centered on the page. The fudge factor should be in
    the same units as the returned size and offset values.

 OUTPUTS:

    pageInfo: The output value is a named structure defined like
    this:

      pageInfo = {PSWINDOW_STRUCT, XSIZE:0.0, YSIZE:0.0, $
         XOFSET:0.0, YOFFSET:0.0, INCHES:0, PORTRAIT:0, LANDSCAPE:0}

    The units of the four size fields are inches unless the CM
    keyword is set.

    The output can be used to immediately configure the PostScript
    or Printer device, like this:

       Set_Plot, 'PS' ; or 'PRINTER'
       Device, _Extra=pageInfo

 RESTRICTIONS:

    The aspect ratio of the current graphics window is calculated
    like this:

       aspectRatio = FLOAT(!D.Y_VSIZE) / !D.X_VSIZE

 EXAMPLE:

    To create a PostScript output window with the same aspect
    ratio as the curently active display window, type:

     pageInfo = PSWINDOW()
     SET_PLOT, 'PS'
     DEVICE, _Extra=pageInfo

     To configure the PRINTER device:

     pageInfo = PSWINDOW(/Printer, Fudge=0.25)
     SET_PLOT, 'PRINTER'
     DEVICE, _Extra=pageInfo

 MODIFICATION HISTORY:

    Written by: David Fanning, November 1996.
       Fixed a bug in which the YOFFSET was calculated incorrectly
          in Landscape mode. 12 Feb 97.
       Took out a line of code that wasn't being used. 14 Mar 97.
       Added correct units keyword to return structure. 29 JUN 98. DWF
       Fixed a bug in how landscape offsets were calculated. 19 JUL 99. DWF.
       Fixed a bug in the way margins were used to conform to my
          original conception of the program. 19 JUL 99. DWF.
       Added Landscape and Portrait fields to the return structure. 19 JUL 99. DWF.
       Added PageSize keyword, changed MARGIN keyword, and completely
          rewrote most of the intenal code. 9 FEB 2000. DWF.
       Fixed a bug in how I calculated the aspect ratio. 1 MAR 2000. DWF.
       Added PRINTER keyword to return proper offset values for the
          PRINTER device, where the offset location is not rotated. 1 MAR 2000. DWF.
       Added PRINTER fudge factors to take into account that printer offsets are
          calculated from the printable area of the paper, rather than the corner
          of the paper. 8 AUG 2000. DWF.

(See $IDL_LOCAL\mpi_plot\pswindow.pro)

TVREAD

[Previous Routine] [List of Routines]

 NAME:
       TVREAD

 PURPOSE:
       To get accurate screen dumps with the IDL command TVRD on 24-bit
       PC and Macintosh computers, you have to be sure to set color
       decomposition on. This program adds that capability automatically.
       In addition, the program will optionally write BMP, GIF, JPEG,
       PICT, PNG, and TIFF color image files of the screen dump.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: davidf@dfanning.com
       Coyote's Guide to IDL Programming: http://www.dfanning.com

 CATEGORY:

       Graphics

 CALLING SEQUENCE:

       image = TVREAD(xstart, ystart, ncols, nrows)

       The returned image will be a 2D image on 8-bit systems and
       a 24-bit pixel interleaved true-color image on 24-bit systems.
       A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.).

 OPTIONAL INPUTS:

       XSTART -- The starting column index.  By default, 0.

       YSTART -- The starting row index. By default, 0.

       NCOLS -- The number of columns to read. By default, !D.X_Size - XSTART

       NROWS -- The number of rows to read. By default, !D.Y_Size - YSTART.

 KEYWORD PARAMETERS:

       BMP -- Set this keyword to write the screen dump as a color BMP file.

       CANCEL -- An output keyword set to 1 if the user cancels out of a
          filename dialog. Set to 0 otherwise.

       COLORS -- If a 24-bit image has to be quantized, this will set the number
          of colors in the output image. Set to 256 by default. Applies to BMP,
          GIF, PICT, and PNG formats written from 24-bit displays.(See the
          COLOR_QUAN documentation for details.)

       CUBE -- If this keyword is set to a value between 2 and 6 the color
          quantization will use a cubic method of quantization. Applies to BMP,
          GIF, PICT, and PNG formats written from 24-bit displays.(See the
          COLOR_QUAN documentation for details.)

       DITHER -- If this keyword is set the quantized image will be dithered.
          Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.
          (See the COLOR_QUAN documentation for details.)

       FILENAME -- The base name of the output file. (No file extensions;
           they will be added automatically.) This name may be changed by the user.

              image = TVREAD(Filename='myfile', /JPEG)

           No file will be written unless a file output keyword is used
           (e.g., JPEG, TIFF, etc.) in the call. By default the FILENAME is
           set to "idl". The file extension will be set automatically to match
           the type of file created.

       GIF -- Set this keyword to write the screen dump as a color GIF file.

       JPEG -- Set this keyword to write the screen dump as a color JPEG file.

       NODIALOG -- Set this keyword if you wish to avoid the DIALOG_PICKFILE
           dialog that asks you to name the output file. This keyword should be
           set, for example, if you are processing screens in batch mode.

       PICT -- Set this keyword to write the screen dump as a color PICT file.

       PNG -- Set this keyword to write the screen dump as a color PNG file.

       TIFF -- Set this keyword to write the screen dump as a color TIFF file.

       QUALITY -- This keyword sets the amount of compression for JPEG images.
           It should be set to a value between 0 and 100. It is set to 75 by default.
           (See the WRITE_JPEG documentation for details.)

       WID -- The index number of the window to read from. The current graphics window
           (!D.Window) is selected by default. An error is issued if no windows are
           currently open on a device that supports windows.

       _EXTRA -- Any keywords that are appropriate for the WRITE_*** routines are
           also accepted via keyword inheritance.

 COMMON BLOCKS:

       None

 RESTRICTIONS:   Requires ERROR_MESSAGE from the Coyote Library:

                     http://www.dfanning.com/programs/error_message.pro

                 Requires IDL 5.2 and higher.

 MODIFICATION HISTORY:

       Written by David Fanning, 9 AUG 2000.
       Added changes to make the program more device independent. 16 SEP 2000. DWF.
       Removed GIF file support for IDL 5.4 and above. 18 JAN 2001. DWF.
       Added NODIALOG keyword. 28 MAR 2001. DWF.
       Added an output CANCEL keyword. 29 AUG 2001. DWF.

(See $IDL_LOCAL\mpi_plot\tvread.pro)

HOME|Index|Work in Progress