CW_FORM

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:

Depth

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

Item

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.

Initial value

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. For more information, see Using Language Catalogs (Application Programming).

Settings

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. Simply 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 About 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:

Table 5-21: TAB_MODE Keyword Options
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 (User Interface Programming).
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. For more information, see Using Language Catalogs (Application Programming).

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 (User Interface Programming) 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

Table 5-22: Output from HELP, /STRUCTURE
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