NAME

XmtChooser - a widget that presents a choice to the user.

SYNOPSIS

Include File:

#include <Xmt/Chooser.h>

Constructor:

XmtCreateChooser()

Class Name:

XmtChooser

Class Pointer:

xmtChooserWidgetClass

Class Hierarchy:

Core → Composite → Constraint → XmManager → XmRowColumn → XmtChooser

DESCRIPTION

An XmtChooser is a composite widget which creates and controls the primitive widgets necessary to present a list of selectable items to the user. Depending on the XmtNchooserType resource, a Chooser widget will create an XmList widget, an XmOptionMenu, or a number of button children configured to be used as a radio box, a check box, a button box, or a palette. See the section ``Chooser Types'' below for more information.

The choices to be displayed to the user may be specified in a single array on the XmtNstrings or the XmtNpixmaps resource. When pixmaps are being used, the XmtNselectPixmaps and XmtNinsensitivePixmaps resources specify alternate pixmaps to be displayed when an item is selected or insensitive and un-selectable.

The Chooser widget keeps track of the choices made by the user in the XmtNstate resource. For Chooser types that have radio-style behavior, (i.e. types for which only one item can be selected at a time) the value of this resource is the index of the selected item. For types that allow multiple selected items, this state value is a bit-mask which indicates which items are selected. If the nth bit is set in this resource, then the nth item displayed by the Chooser is selected. The programmer may query this resource at any time to determine the current selection state. The programmer may also set this resource, and the selection state of the Chooser subwidgets will be changed to reflect the new value. Whenever the state of the Chooser changes, it calls all the procedures registered on its XmtNvalueChangedCallback list. See the section ``Chooser State'' below for more information.

The XmtNvalues or XmtNvalueStrings resources specify an array of values to be associated with the items displayed by the Chooser widget. The Chooser widget does not interpret or use these values in any way, but the value of an item is often more convenient to the programmer than that item's index in the Chooser. See the section ``Chooser Values'' for more information on specifying values for a Chooser.

The Chooser widget is a subclass of XmRowColumn, and it uses the layout capabilities of and resources of XmRowColumn to arrange its children. Although the Chooser is a composite widget, it creates all of its own children, and should not have additional children added to it.

RESOURCES

Chooser inherits the resources of the XmRowColumn class, and defines the following new resources. In addition, it overrides the default value for two XmRowColumn resources: it sets the default value of XmNadjustLast to False and of XmNpacking to XmPACK_COLUMN.

XmtNchooserType

The type of the widgets to be created and controlled by the Chooser widget. This is one of the enumerated values of type XmtChooserType. The XmtNchooserType resource may only be set when the Chooser is created, and may never be changed. There is a type converter for this resource; see the ``Converters'' section below. See the section ``Chooser Types'' for an explanation of each of the supported types.

XmtNfontList

The XmFontList to use to display any strings specified on the XmtNstrings resource in the button or list widgets created by the Chooser. If this resource is left unspecified, then the default value is obtained from the XmNbuttonFontList resource of the nearest XmBulletinBoard ancestor, or the XmNdefaultFontList resource of the nearest VendorShell or XmMenuShell ancestor.

XmtNinsensitivePixmaps

An array of Pixmap containing XmtNnumItems elements. If that resource is unspecified this resource must be NULL-terminated. If these pixmaps are specified, and if XmtNlabelType is XmPIXMAP, then they are used to display choices that are currently unselectable because they have been made insensitive with a call to XmtChooserSetSensitive() This resource must be set when the widget is created, and cannot be changed.

XmtNitemWidgets

A read-only resource that can be queried to obtain the array of button children created by the Chooser when the XmtNchooserType resource is set to anything other than XmtChooserRadioList or XmtChooserCheckList. The index of a choice in the Chooser is the same as the index of that choice's widget in this array.

XmtNlabelType

Specifies whether the Chooser should display choices using strings or pixmaps. If it is set to the value XmSTRING, then the Chooser will display choices using the strings in the XmtNstrings array. If set to XmPIXMAP, then the Chooser will display choices using the pixmaps in the XmtNpixmaps array, and will also use the pixmaps in the XmtNselectPixmaps and XmtNinsensitivePixmaps arrays to display selected and insensitive choices.

XmtNnumItems

Specifies the number of choices to appear in the Chooser. This is the number of elements that must appear in the XmtNstrings, XmtNpixmaps and other array resources of the Chooser. If this resource is left unspecified, then the XmtNstrings, XmtNpixmaps, XmtNselectPixmaps and XmtNinsensitivePixmaps arrays must be NULL-terminated. Note that any of these resources specified in a resource file will be automatically NULL-terminated by the resource converter.

XmtNpixmaps

An array of Pixmap that contains XmtNnumItems elements. If that resource is unspecified this array must be NULL-terminated. When XmtNlabelType is XmPIXMAP, the Chooser uses these pixmaps to display the choices. Note that pixmaps cannot be used with XmtChooserRadioList and XmtChooserCheckList types. This resource must be set when the widget is created, and cannot be changed. Call XmtRegisterPixmapListConverter() to allow this resource to be specified in a resource file.

XmtNselectPixmaps

An array of Pixmap that contains XmtNnumItems elements. If that resource is unspecified, this array must contain the same number of elements as the XmtNpixmaps array and must be NULL-terminated. When XmtNlabelType is XmPIXMAP, these pixmaps are used to display selected choices. This resource can be used to highlight selected items by specifying pixmaps with a darker background color. This resource must be set when the widget is created, and cannot be changed.

XmtNstate

The selection state of the Chooser widget-the item or items that are selected. This resource may be queried to obtain the current selection state of the widget, or it may be set, and the Chooser will change its displayed selection state to match the newly specified value. See the section ``Chooser State'' for an explanation of how this state variable is interpreted.

XmtNstrings

An array of strings to be displayed as choices to the user. Note that the strings are of type String, not XmString. This resource must be set when the Chooser widget is created, and once set, it cannot be changed. If the XmtNnumItems resource is set, then this array must have that many elements. If XmtNnumItems is not set, then this array must be NULL-terminated. There is a String-to-StringList type converter registered for this resource by the Chooser widget class; see the ``Converters'' section below.

XmtNsymbolName

The name of a registered symbol on which the Chooser is to store its state. If a symbol is specified, its initial value is used as the initial value for the Chooser, and any changes made to the symbol value with XmtSymbolSetValue() will be reflected in the Chooser widget state. Symbols can be useful for applications that use the state of the Chooser, but do not need to be notified of changes in the state; those applications can register the address of a variable as a symbol, specify the name of that symbol on this resource, and then simply read the state from this variable, without querying the widget. See XmtRegisterSymbol() for more information on symbols.

XmtNvalueChangedCallback

A list of callback procedures which will be called when the state of the Chooser changes. Each procedure will be called with a call_data argument of type XmtChooser CallbackStruct * which is documented below.

XmtNvalueSize

The size, in bytes, of each element in the array of values specified on the XmtNvalues resource, or the size, in bytes, of the type specified by the XmtNvalue Type resource.

XmtNvalueStrings

An array of strings, one for each item in the Chooser, which will be converted to the type specified by the XmtNvalueType resource and stored in the XmtNvalues array. If you specify this resource, you must also specify XmtNvalueType and XmtNvalueSize. Once the XmtNvalueStrings strings have been converted to the XmtNvalues values, the Chooser widget resets the XmtNvalueStrings resource to NULL, so it never makes sense to query this resource. Since the resource is automatically reset to NULL, however, when a value changes in your array of strings, you can pass the array in another call to XtSetValues(). If the resource value had not been reset to NULL, the widget would not notice any change (the array contents have changed, but not the array pointer) and the new values would not be converted.

XmtNvalueType

A representation type string, such as the constants XtRInt and XmRFontList. If the XmtNvalueStrings resource is specified, the strings in that array will be converted to the type specified by this resource, and the converted values stored in the XmtNvalues array.

XmtNvalues

An untyped array containing one element for each item in the Chooser, each element XmtNvalueSize bytes in length. For Chooser types that allow only one selected item at a time, this array specifies a value for each item in the Chooser widget. This value is often more useful to the application programmer than the value on the XmtNstate resource. The contents of the XmtNvalues array are untyped, and are not used in any way by the Chooser widget, but this resource provides a convenient way for an application to associate the values it cares about with each of the elements in the Chooser. If you set this resource, you must also set XmtNvalueSize.

XmtNvisibleItems

If the XmtNchooserType resource is XmtChooserRadioList or XmtChooserCheckList, then this resource sets the XmNvisibleItemCount resource of the list widget, and controls the number of items that are visible at any time. If there are more items in XmtNlabels than XmtNvisibleItems, then the XmList widget will be scrolled.

Chooser Types

The way the Chooser widget presents its choices to the user is specified by the XmtNchooserType resource. This resource is of type XmtChooserType, which has the following enumerated values:

typedef enum {

} XmtChooserType;

The enumerated values for this type have the following meanings:

XmtChooserRadioBox

Items are displayed with XmToggleButtons with dia mond-shaped (``one-of-many'') indicators. Only one item in the list is allowed to be selected at any time.

XmtChooserCheckBox

Items are displayed with XmToggleButtons with square (``n-of-many'') indicators. Any number of the items may be selected.

XmtChooserRadioPalette

Items are displayed with XmToggleButtons. The toggle buttons have no indicators, but use shadows to display their selection state instead. Only one item may be selected at a time.

XmtChooserCheckPalette

Items are displayed with XmToggleButtons. The toggle buttons have no indicators, but use shadows to display their selection state instead. Any number of items may be selected.

XmtChooserRadioList

Items are displayed in an XmList widget in browse select mode. Only one item may be selected at a time.

XmtChooserCheckList

Items are displayed in an XmList widget in multiple-select mode. Any number of items may be selected.

XmtChooserOption

Items are displayed in an option menu as created by XmCreateOptionMenu(). Only one item may be selected at a time.

XmtChooserButtonBox

Items are displayed with XmPushButtons. Since these buttons do not remain selected after they are ``pushed'', the XmtNstate resource is unused in Choosers of this type.

For RadioBox, CheckBox, RadioPalette, CheckPalette and ButtonBox types, the Chooser automatically creates the appropriate button children. The layout of these children is controlled by XmNnumColumns, XmNorientation, and other inherited XmRowColumn resources. For the Option type, the Chooser widget creates a menu pane and creates the buttons as children of that widget.

For the RadioList and CheckList types, the Chooser auto matically creates a scrolled XmList widget to display the choices. The XmtNvisibleItems resource controls the number of choices visible at one time in these modes.

Chooser State

The XmtNstate resource maintains the selection state of all the items in the Chooser widget. If XmtNchooserType is one of the types with radio behavior (XmtChooserRadioBox, XmtChooserRadioPalette, XmtChooserRadioList or XmtChooserOption), then the state is simply the index of the currently selected item. Items are numbered beginning at zero, so if this resource is 0, it means that the first item is selected. For these Chooser types with radio-box behavior, there is exactly one item selected at all times, including a default item when the Chooser is created.

If XmtNchooserType is a type without radio behavior (XmtChooserCheckBox, XmtChooserCheckPalette, or XmtChooserCheckList), then the state is a bit-mask with one bit indicating the state of each item. In this case, the state of item n can be determined with the following C code:

(state & (1 << n))

Note that there cannot be more items in a Chooser of this type than there are bits in a variable of type int. This is at least 32 bits on most systems and should be plenty for most practical applications. Finally, note that if XmtNchooserType is XmtChooserButtonBox (which uses XmPushButtons rather than XmToggleButtons), then the XmtNstate resource is ignored.

Chooser Values

From the XmtNstate resource of a Chooser, you can determine the index of the selected item or items within the list of displayed items. Often however, the application is not interested in the index of the selected item, but instead in some semantic value associated with the item. For a Chooser that lets the user select a font size from a list of 5 values, for example, the states 0, 1, 2, 3, and 4 are not as interesting as the sizes themselves: 8, 10, 12, 14, and 18.

An application can easily maintain an array of values to map from item number to item value, but as a convenience, the Chooser widget will maintain this array for the application. The XmtNvalues resource is an untyped array that contains one element for each item in the Chooser. The length of each element, in bytes, is specified by the XmtNvalueSize resource. The Chooser widget never uses or interprets these values, but will pass pointers to them to the application when it invokes the XmtNvalueChangedCallback, or when the application calls XmtChooserGetValue().

The Chooser allows values to be specified from resource files with the XmtNvalueStrings resource and the XmtNvalueType resource. XmtNvalueStrings is an array of strings, and XmtNvalueType is a string representation type, such as XtRInt or XtRPixel, for which a resource converter has been registered. (Values beginning with ``XtR'', ``XmR'', or ``XmtR'' are the symbolic names you would use from C. In a resource file, you'd use the strings these symbols stand for-``Int'' and ``Pixel'' in this case.) If XmtNvalueStrings is specified, each string in the array will be converted to the specified type. The Chooser widget will allocate an array for the XmtNvalues resource, with XmtNvalueSize bytes for each element, and will store the converted values into this array. Note that if you specify the XmtNvalues resource, you must also always specify the XmtNvalueSize resource. If you specify the XmtNvalueStrings resource, you must always specify both the XmtNvalueSize and XmtNvalueType resources.

CALLBACKS

The Chooser widget defines a single callback list, XmtNvalueChangedCallback. The procedures registered on this list are called when the selection state of the widget changes (ie. when the user chooses on of the displayed items). The call_data argument to this callback is a pointer to an XmtChooserCallbackStruct, which is defined as follows:

typedef struct {

} XmtChooserCallbackStruct;

The state field of this structure is the new value of the XmtNstate resource. The item field is the index of the item that was just selected. For Chooser types with radio behavior, this is the same as the state field. If the XmtNvalues array or the XmtNvalueStrings array is set, then the valuep field is the address of the element of that array that corresponds to item specified on the item field.

The XmtNvalueChangedCallback is generally called when the user changes the state of the Chooser widget. It is also called when XmtChooserSetState() is called with its notify argument set to True. In this case the item field is always set to -1, because although the state changed, there is not any particular item that the user just selected or deselected. For synthetic state changed like this, if the Chooser is in a radio-box mode, then the valuep field is set to point to the value that corresponds to the single selected item. For check-box modes, the valuep field is set to NULL on synthetic state changes.

For Chooser widgets of type XmtChooserButtonBox, the state field of this callback structure is always set to -1 because the XmPushButtons of a button box do not maintain any state. The item field will contain the index of the button just pressed, however, which can be useful to dispatch commands in a switch statement, for example.

Converters

The Chooser class registers converters to convert strings specified in resource files to the types XmtRXmtChooserType and XmtRStringList. The String-to-XmtChooserType converter recognizes strings spelled exactly as its enumerated type is, with the ``Xmt'' and ``Chooser'' prefixes optionally removed. Correct capitalization is required by this converter.

The String-to-StringList converter converts a comma separated list of strings within double quotes into a NULL-terminated array of strings suitable for use on the XmtNstrings and XmtNvalueStrings resources.

The Xmt library also provides a String-to-PixmapList converter that will convert a string to an array of pixmaps suitable for use on the XmtNpixmaps, XmtNselectPixmaps and XmtNinsensitivePixmaps resources. Because many applications will not use the Chooser widget with pixmaps, this converter is not automatically registered by the widget. You can register it explicitly by calling XmtRegisterPixmapListConverter(). This converter converts a comma separated list of pixmap names within quotes, optionally followed by a color table to specify symbolic color substitutions for those pixmaps. See XmtRegisterPixmapListConverter(), XmtRegisterColorTableConverter(), and XmtGetPixmap() for more information.

TRANSLATIONS and ACTIONS

The Chooser widget simply inherits the translations of the XmRowColumn widget class, and does not set translations on any of its automatically created children. It defines no new action procedures.

Sensitivity

Because the Chooser is often used with a caption provided by an XmtLayout parent widget, it takes special care to notice when its own sensitivity state changes, and updates the XmtNlayoutSensitive constraint resource as necessary so that any caption will appear ``greyed out'' when the Chooser is not sensitive.

The Chooser widget provides a convenience routine, XmtChooserSetSensitive() which sets the sensitivity of individual items within the Chooser. For Chooser types that use buttons, insensitive items are made insensitive with XtSetSensitive(), and will be displayed with ``greyed out'' textual labels, or with the pixmap, if any, specified in the XmtNinsensitivePixmaps array. An insensitive item is not selectable. For Chooser types that use the XmList widget, insensitive items are not displayed in any special way, but are made unselectable.

SEE ALSO

Chapter 27, Presenting Choices,
XmtChooserGetSensitivity(), XmtChooserGetState(), XmtChooserGetValue(), XmtChooserLookupItemByName(), XmtChooserLookupItemByValue(), XmtChooserLookupItemName(), XmtChooserLookupItemValue(), XmtChooserSetItemValue(), XmtChooserSetSensitive(), XmtChooserSetState(), XmtCreateChooser(), XmtRegisterChooser().