FreeBSD Manual Pages

home | help

XmtChooser(3) Library Functions Manual XmtChooser(3)

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 in-
formation.

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 se-
lection 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 Xm-
NadjustLast 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'' sec-
tion 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 de-
fault 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 cur-
rently 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 XmtNin-
sensitivePixmaps 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 re-
source 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-termi-
nated. 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 expla-
nation 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 noti-
fied 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 XmtRegisterSym-
bol() 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 spec-
ified 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 re-
source 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 XmtNval-
ueStrings 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 Xmt-
Nvalues 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 XmNvisibleItem-
Count 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 speci-
fied by the XmtNchooserType resource. This resource is of type
XmtChooserType, which has the following enumerated values:

typedef enum {
XmtChooserRadioBox, /* one-of-many toggle buttons */
XmtChooserCheckBox, /* n-of-many toggle buttons */
XmtChooserRadioPalette, /* toggle buttons w/o indicators */
XmtChooserCheckPalette, /* toggle buttons w/o indicators */
XmtChooserRadioList, /* XmList widget in single select mode */
XmtChooserCheckList, /* XmList widget in multi-select mode */
XmtChooserOption, /* option menu */
XmtChooserButtonBox, /* Push buttons in a box */
} 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 al-
lowed 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 XmCreateOp-
tionMenu(). 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 re-
source 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 XmNnum-
Columns, XmNorientation, and other inherited XmRowColumn re-
sources. 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 mati-
cally 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 ra-
dio behavior (XmtChooserRadioBox, XmtChooserRadioPalette, XmtChooserRa-
dioList 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 se-
lected at all times, including a default item when the Chooser is cre-
ated.

If XmtNchooserType is a type without radio behavior (XmtChooserCheck-
Box, 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. Fi-
nally, 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 val-
ues, 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 Xmt-
NvalueChangedCallback, or when the application calls XmtChooserGet-
Value().

The Chooser allows values to be specified from resource files with the
XmtNvalueStrings resource and the XmtNvalueType resource. XmtNval-
ueStrings is an array of strings, and XmtNvalueType is a string repre-
sentation type, such as XtRInt or XtRPixel, for which a resource con-
verter 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 wid-
get will allocate an array for the XmtNvalues resource, with XmtNvalue-
Size 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 Xmt-
NvalueStrings resource, you must always specify both the XmtNvalueSize
and XmtNvalueType resources.

CALLBACKS

The Chooser widget defines a single callback list, XmtNvalueChanged-
Callback. 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 {
int state; /* selected item or bitwise OR of items */
int item; /* whichever item just was clicked */
XtPointer valuep; /* address of value from XmtNvalues array */
} XmtChooserCallbackStruct;

The state field of this structure is the new value of the XmtNstate re-
source. 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 XmtChooserSet-
State() 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 dese-
lected. 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 val-
uep 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 con-
verter.

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 informa-
tion.

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 XmtLay-
out parent widget, it takes special care to notice when its own sensi-
tivity 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, XmtChooserSetSensi-
tive() 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 Xmt-
NinsensitivePixmaps 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().

Xmt Motif Tools XmtChooser(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtChooser&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages