The CW_FIELD function creates a widget data entry field. The field consists of a label and a text widget. CW_FIELD can create string, integer, or floating-point fields. The default is an editable string field.

This routine is written in the IDL language. Its source code can be found in the file cw_field.pro in the lib subdirectory of the IDL distribution.

Examples

The code below creates a main base with a text field attached to it:

base = WIDGET_BASE()
field = CW_FIELD(base, TITLE = "Name:", /FRAME, /RETURN_EVENTS, /FOCUS_EVENTS)
WIDGET_CONTROL, base, /REALIZE

The field accepts string input, has the title “Name”, and has a frame around it. The field sends an event whenever the user hits the Return key or the text field loses focus.

Syntax

Result = CW_FIELD( Parent [, /ALL_EVENTS] [, /COLUMN] [, /DOUBLE] [, FIELDFONT=font] [, /FLOATING] [, /FOCUS_EVENTS] [, FONT=string] [, FRAME=pixels] [, IGNORE_ACCELERATORS=value] [, /INTEGER] [, /LONG] [, /NOEDIT] [, /RETURN_EVENTS] [, /ROW] [, /STRING][, TAB_MODE=value] [, TEXT_FRAME=pixels] [, TITLE=string] [, /ULONG] [, UNAME=string] [, UVALUE=value] [, VALUE=value] [, XSIZE=characters] [, YSIZE=lines] )

Return Value

This function returns the widget ID of the newly created field widget.

Arguments

Parent

The widget ID of the parent widget.

Keywords

ALL_EVENTS

If this keyword is set then CW_FIELD will issue an event whenever the contents of the text field have changed. By default the CW_FIELD widget does not send any events.

COLUMN

Set this keyword to center the label above the text field. The default is to position the label to the left of the text field.

DOUBLE

Set this keyword to have the field accept only double-precision floating-point values. Characters that are not part of a number (+-1234567890.eEdD) are rejected. Before the value is returned, IDL will convert the text field's value to a double-precision floating-point value.

FIELDFONT

Set this keyword to a string containing the name of the font to use for the TEXT part of the field.

FLOATING

Set this keyword to have the field accept only single-precision floating-point values. Characters that are not part of a number (+-1234567890.eEdD) are rejected. Before the value is returned, IDL will convert the text field's value to a single-precision floating-point value.

FOCUS_EVENTS

Set this keyword to make CW_FIELD return an event when the keyboard focus on the text field is lost. The widget loses the keyboard focus when the user clicks onto a different widget or application or uses the Tab key to move to a different widget (when TAB_MODE is enabled). By default the CW_FIELD widget does not send any events.

Tip: You can use the UPDATE field in the widget event structure to determine if the value has changed since the previous event.

FONT

Set this keyword to a string containing the name of the font to use for the TITLE of the field. 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.

FRAME

Set this keyword to the width, in pixels, of a frame to be drawn around the entire field cluster. The default is no frame.

IGNORE_ACCELERATORS

Set this keyword to specify what WIDGET_BUTTON accelerators are to be ignored when this widget has keyboard focus. Valid values are:

  • A string or string array containing any value that is legal for WIDGET_BUTTON’s ACCELERATOR keyword
  • The number 1, indicating all accelerators should be ignored

See Disabling Button Widget Accelerators for usage details and examples.

INTEGER

Set this keyword to have the field accept only integer values. Characters that are not part of a number (-1234567890) are rejected. Before the value is returned, IDL will convert the text field's value to a 16-bit signed integer.

Note: When using INTEGER, IDL does not do any check on the maximum value. If the absolute value of the number within the field is larger than the maximum integer (32767) then the value will wrap around when it is returned. If you expect your users to be able to enter larger values, use the LONG or ULONG keyword instead.

LONG

Set this keyword to have the field accept only long integer values. Characters that are not part of a number (-1234567890) are rejected. Before the value is returned, IDL will convert the text field's value to a 32-bit signed integer.

Note: If the absolute value of the number within the field is larger than the maximum LONG value (2147483647), then IDL will automatically convert the number to a 64-bit integer instead.

NOEDIT

Normally, the value in the text field can be edited. Set this keyword to make the field non-editable.

RETURN_EVENTS

Set this keyword to make CW_FIELD return an event when the Return key is pressed in a text field. By default the CW_FIELD widget does not send any events.

ROW

Set this keyword to position the label to the left of the text field. This is the default.

STRING

Set this keyword to have the field accept only string values. Numbers entered in the field are converted to their string equivalents. This is the default.

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.

TEXT_FRAME

Set this keyword to the width in pixels of a frame to be drawn around the text field. Note that this keyword is only a “hint” to the toolkit, and may be ignored in some instances. Under Microsoft Windows, text widgets always have a frame of width 1 pixel.

TITLE

A string containing the text to be used as the label for the field. The default is “Input Field”.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

ULONG

Set this keyword to have the field accept only unsigned long integer values. Characters that are not part of an unsigned number (1234567890) are rejected. Before the value is returned, IDL will convert the text field's value to a 32-bit unsigned integer.

Note: If the value within the field is larger than the maximum ULONG value (4294967295), then IDL will automatically convert the number to an unsigned 64-bit integer.

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

The “user value” to be assigned to the widget.

VALUE

The initial value in the text widget. This value is automatically converted to the type defined by the STRING, INTEGER, LONG, and FLOATING keywords.

XSIZE

An explicit horizontal size (in characters) for the text input area. The default is to let the window manager size the widget. Using the XSIZE keyword is not recommended.

YSIZE

An explicit vertical size (in lines) for the text input area. The default is 1.

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 field. If one of the FLOATING, INTEGER, LONG, or STRING keywords to CW_FIELD is set, values set with the SET_VALUE keyword to WIDGET_CONTROL will be forced to the appropriate type. Values returned by the GET_VALUE keyword to WIDGET_CONTROL will be of the type specified when the field widget is created. Note that if the field contains string information, returned values will be contained in a string array even if the field contains only a single string.

See Writing Compound Widgets for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO.

Widget Events Returned by the CW_FIELD Widget

This widget generates event structures with the following definition:

event = { ID:0L, TOP:0L, HANDLER: 0L, VALUE:'', TYPE:0 , UPDATE:0}

The VALUE field is the value of the field. TYPE specifies the type of data contained in the field and can be any of the following: 0=string, 1=floating-point, 2=integer, 3=long integer, 4=ulong integer, 5=double-precision (the value of TYPE is determined by setting one of the STRING, DOUBLE, FLOAT, INTEGER, LONG, or ULONG keywords). UPDATE contains a zero if the field has not been altered or a one if it has changed since the previous event.

Version History

Pre 4.0

Introduced

6.1

Added TAB_MODE keyword

8.3

Added DOUBLE, FOCUS_EVENTS, IGNORE_ACCELERATORS, ULONG keywords.

See Also

WIDGET_LABEL, WIDGET_TEXT