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.
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.
Using CW_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}
Syntax
Result = CW_FORM( [Parent,] Desc [, /COLUMN] [, IDS=variable] [, TAB_MODE=value] [, TITLE=string] [, UNAME=string] [, UVALUE=value] )
Return Value
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.
Arguments
Parent
The widget ID of the parent widget. Omit this argument to created a modal, top-level widget.
Desc
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, Settings'
Use the backslash character (“\”) to escape commas that appear within fields. To include the backslash character, escape it with another backslash.
The fields are defined as follows:
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:
|
0 |
Continue the current nesting level
|
|
1 |
Begin a new level under the current level
|
|
2 |
Last element at the current level
|
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:
|
BUTTON |
An integer or integer array. For single buttons, the value is 1 if the button is set, or 0 if it is not set. For exclusive button groups, the value is the index of the currently set button. For non-exclusive button groups, the value is an array containing an element for each button. Array elements are set to 1 if the corresponding button is set, or 0 if it is not set.
|
|
DROPLIST |
An integer. The value set in the widget value structure is the zero-based index of the item is selected.
|
|
FLOAT |
A floating-point value. The value set in the widget value structure is the floating-point value of the field.
|
|
INTEGER |
An integer. The value set in the widget value structure is the integer value of the field.
|
|
LIST |
An integer. The value set in the widget value structure is the zero-based index of the item is selected.
|
|
TEXT |
A string. The value set in the widget value structure is the string value of the field.
|
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.
Note: You can use language catalogs to internationalize this value with strings in particular languages.
The Settings field contains one of the following keywords or keyword=value pairs. Keywords are used to specify optional attributes or options. Any number of keywords may be included in the description string.
Note that preceding keywords with a “/” character has no effect. Including a keyword in the Settings field enables that option.
|
CENTER |
Specifies alignment of LABEL items.
|
|
COLUMN |
If present, specifies column layout in BASES or for BUTTON groups.
|
|
EXCLUSIVE |
If present, makes an exclusive set of BUTTONs. The default is nonexclusive.
|
|
FONT=font name
|
If present, the font for the item is specified. The font specified is a “device font” (an X Windows font on Motif systems; a TrueType or PostScript font on Windows systems). See Using Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.
|
|
EVENT=function
|
Specifies the name of a user-written event function that is called whenever the element is changed. The event function is called with the widget event structure as a parameter. It may return an event structure or zero to indicate that no further event processing is desired.
|
|
FRAME |
If present, a frame is drawn around the item. Valid only for BASEs.
|
|
LABEL_LEFT=label
|
Place a label to the left of the item. This keyword is valid with BUTTON, DROPLIST, FLOAT, INTEGER and TEXT items.
|
|
LABEL_TOP=label
|
Place a label above the item. This keyword is valid with BUTTON, DROPLIST, FLOAT, INTEGER and TEXT items.
|
|
LEFT |
Specifies alignment of LABEL items.
|
|
NO_RELEASE |
If present, exclusive and non-exclusive buttons generate only select events. This keyword has no effect on regular buttons.
|
|
QUIT |
If the form widget is created as a top-level, modal widget, when the user activates an item defined with this keyword, the form is destroyed and its widget value returned in the widget value structure of CW_FORM. For non-modal form widgets, events generated by changing this item have their QUIT field set to 1.
|
|
RIGHT |
Specifies alignment of LABEL items.
|
|
ROW |
If present, specifies row layout in BASES or for BUTTON groups.
|
|
SET_VALUE=value
|
Sets the initial value of BUTTON groups or DROPLISTs. For droplists and exclusive button groups, value should be the zero-based index of the item selected.
|
|
TAG=name |
The tag name of this element in the widget’s value structure. If not specified, the tag name is TAGnnn, where nnn is the zero-based index of the item in the Desc array.
|
|
WIDTH=n |
Specifies the width, in characters, of a TEXT, INTEGER, or FLOAT item.
|
Keywords
COLUMN
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.
IDS
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.
TAB_MODE
Set this keyword to one of the values shown in the table below to determine how the widget hierarchy can be navigated using the Tab key. The TAB_MODE setting is inherited by lower-level bases and child widgets unless it is explicitly set on an individual widget.
Note: It is not possible to tab to disabled (SENSITIVE=0) or hidden (MAP=0) widgets.
Valid settings are:
|
Value |
Description |
|
0 |
Disable navigation onto or off of the widget. This is the default. Child widgets automatically inherit the tab mode of the parent base as described in Inheriting the TAB_MODE Value.
|
|
1 |
Enable navigation onto and off of the widget.
|
|
2 |
Navigate only onto the widget.
|
|
3 |
Navigate only off of the widget.
|
Note: In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems.
TITLE
Set this keyword equal to a scalar string containing the title of the top level base. TITLE is not used if the form widget has a parent widget.
Note: You can use language catalogs to internationalize this value with strings in particular languages.
UNAME
Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
UVALUE
Set this keyword equal to the user value associated with the form widget.
Keywords to WIDGET_CONTROL and WIDGET_INFO
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 Creating a Compound Widget for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.
Widget Events Returned by the CW_FORM Widget
CW_FORM generates an event that specifies the which field within the form changed and the new value. 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.
Examples
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:
desc = [ $
'0, LABEL, Centered Label, CENTER', $
'1, BASE,, ROW, FRAME', $
'0, BUTTON, B1|B2|B3, LABEL_TOP=Nonexclusive:,' $
+ 'COLUMN, TAG=bg1', $
'2, BUTTON, E1|E2|E2, EXCLUSIVE,LABEL_TOP=Exclusive:,' $
+ 'COLUMN,TAG=bg2', $
'0, TEXT, , LABEL_LEFT=Enter File name:, WIDTH=12,' $
+ 'TAG=fname', $
'0, INTEGER, 0, LABEL_LEFT=File size:, WIDTH=6, TAG=fsize', $
'1, BASE,, ROW', $
'0, BUTTON, OK, QUIT,' $
+ 'TAG=OK', $
'2, BUTTON, Cancel, QUIT']
To use the form as a modal widget:
a = CW_FORM(desc, /COLUMN)
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:
HELP, /STRUCTURE, a
|
IDL Output |
Meaning |
|
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: 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')
b = CW_FORM(a, desc, /COLUMN)
WIDGET_CONTROL, a, /REALIZE
XMANAGER, 'Test', a
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.
Version History
|
Pre 4.0 |
Introduced |
|
6.1 |
Added TAB_MODE keyword
|