 |
| |
The CW_FORM function is a compound widget that simplifies creating small forms which contain text, numeric fields, buttons, lists, and droplists. Event handling is also simplified.
If the argument Parent is present, the returned value of this function is the widget ID of the newly-created form widget. If Parent is omitted, the form realizes itself as a modal, top-level widget and CW_FORM returns a structure containing the value of each field in the form when the user finishes.
This routine is written in the IDL language. Its source code can be found in the file
cw_form.pro
in the
lib
subdirectory of the IDL distribution.
The form has a value that is a structure with a tag/value pair for each field in the form. Use the command
WIDGET_CONTROL, id, GET_VALUE=v
to read the current value of the form. To set the value of one or more tags, use the command
WIDGET_CONTROL, id, SET_VALUE={ Tag : value , ..., Tag : value }
A string array describing the form. Each element of the string array contains two or more comma-delimited fields. Each string has the following format:
' Depth , Item , Initial value , Keywords '
Use the backslash character ("\") to escape commas that appear within fields. To include the backslash character, escape it with another backslash.
A digit defining the level at which the element will be placed on the form. Nesting is used primarily for layout, with row or column bases.
This field must contain the digit 0, 1, or 2, with the following effects:
A label defining the type of element to be placed in the form. Item must be one of the following: BASE, BUTTON, DROPLIST, FLOAT, INTEGER, LABEL, LIST, or TEXT.
BASEs and LABELs do not return a value in the widget value structure. The other items return the following value types:
The initial value of the field. The Initial value field is left empty for BASEs.
For BUTTON, DROPLIST, and LIST items, the value field contains one or more item names, separated by the | character. Strings do not need to be enclosed in quotes. For example, the following line defines an exclusive button group with buttons labeled "one," "two," and "three."
'0, BUTTON, one|two|three, EXCLUSIVE'
For FLOAT, INTEGER, LABEL, and TEXT items, the value field contains the initial value of the field.
The Keyword field contains one of the following keywords or keyword= value pairs. Keywords are used to specify optional attributes or options. Any number of Keyword fields may be included in the description string.
Note that preceding keywords with a "/" character has no effect. Simply including a keyword in the Keyword field enables that option.
Set this keyword to make the orientation of the form vertical. If COLUMN is not set, the form is laid out in a horizontal row.
Set this keyword equal to a named variable into which the widget id of each widget corresponding to an element in the Desc array is stored.
The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets.
In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the form. The form has a value that is a structure with a tag/value pair for each field in the form. Use the command
WIDGET_CONTROL, id, GET_VALUE=v
to read the current value of the form. To set the value of one or more tags, use the command
WIDGET_CONTROL, id, SET_VALUE={ Tag : value , ..., Tag : value }
See Compound Widgets for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO .
This widget generates event structures each time the value of the form is changed. The event structure has the following definition:
Event = { ID:0L, TOP:0L, HANDLER:0L, TAG:'', VALUE:0, QUIT:0}
The ID field is the widget ID of the CW_FORM widget. The TOP field is the widget ID of the top-level widget. The TAG field contains the tag name of the field that changed. The VALUE field contains the new value of the changed field. The QUIT field contains a zero if the quit flag is not set, or one if it is set.
Define a form with a label, two groups of vertical buttons (one non-exclusive and the other exclusive), a text field, an integer field, and "OK" and "Done" buttons. If either the "OK" or "Done" buttons are pressed, the form exits.
Begin by defining a string array describing the form:
'0, LABEL, Centered Label, CENTER', $
'0, BUTTON, B1|B2|B3, LABEL_TOP=Nonexclusive:,' $
'2, BUTTON, E1|E2|E2, EXCLUSIVE,LABEL_TOP=Exclusive:,' $
'0, TEXT, , LABEL_LEFT=Enter File name:, WIDTH=12,' $
'0, INTEGER, 0, LABEL_LEFT=File size:, WIDTH=6, TAG=fsize', $
To use the form as a modal widget:
When the form is exited, (when the user presses the OK or Cancel buttons), a structure is returned as the function's value. We can examine the structure by entering:
BG1 INT Array[3] ; Set buttons = 1, unset = 0.
BG2 INT 1 ; Second button of exclusive button group was set.
FNAME STRING 'test.dat' ; Value of the text field.
FSIZE LONG 120 ; Value of the integer field.
OK LONG 1 ; This button was pressed.
TAG8 LONG 0 ; This button wasn't pressed.
Note that if the "Cancel" button is pressed, the "OK" field is set to 0.
To use CW_FORM inside another widget:
a = WIDGET_BASE(TITLE='Testing')
The event handling procedure (in this example, called TEST_EVENT), may use the TAG field of the event structure to determine which field changed and perform any data validation or special actions required. It can also get and set the value of the widget by calling WIDGET_CONTROL.