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


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 }

Calling Sequence

Result = CW_FORM( [Parent,] Desc )



The widget ID of the parent widget. Omit this argument to created a modal, top-level widget.


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.

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:


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:

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.


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.


If set, button release events will not be returned.


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.


Set this keyword equal to the user value associated with the form widget.


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


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 .

Widget Events Returned by the CW_FORM Widget

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:

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:


IDL displays the following:

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')

b = CW_FORM(a, desc, /COLUMN)


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.