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 primi-
tive 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 re-
source at any time to determine the current selection state. The programmer
may also set this resource, and the selection state of the Chooser subwid-
gets will be changed to reflect the new value. Whenever the state of the
Chooser changes, it calls all the procedures registered on its XmtNval-
ueChangedCallback 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 ca-
pabilities of and resources of XmRowColumn to arrange its children. Al-
though the Chooser is a composite widget, it creates all of its own chil-
dren, 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 re-
source 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 be-
cause they have been made insensitive with a call to XmtChooserSet-
Sensitive() 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 but-
ton children created by the Chooser when the XmtNchooserType re-
source 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, Xmt-
Npixmaps and other array resources of the Chooser. If this resource
is left unspecified, then the XmtNstrings, XmtNpixmaps, XmtNselect-
Pixmaps 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 re-
source 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 XmtChooserRadi-
oList and XmtChooserCheckList types. This resource must be set when
the widget is created, and cannot be changed. Call XmtRegister-
PixmapListConverter() to allow this resource to be specified in a
resource file.

XmtNselectPixmaps
An array of Pixmap that contains XmtNnumItems elements. If that re-
source 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 se-
lected choices. This resource can be used to highlight selected
items by specifying pixmaps with a darker background color. This re-
source 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 selec-
tion 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 wid-
get 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 wid-
get. 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 be-
low.

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 spec-
ified 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 XmtNval-
ueStrings 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 au-
tomatically reset to NULL, however, when a value changes in your ar-
ray of strings, you can pass the array in another call to XtSetVal-
ues(). 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 XmR-
FontList. If the XmtNvalueStrings resource is specified, the strings
in that array will be converted to the type specified by this re-
source, 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 speci-
fies a value for each item in the Chooser widget. This value is of-
ten more useful to the application programmer than the value on the
XmtNstate resource. The contents of the XmtNvalues array are un-
typed, 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 {
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 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 in-
stead. 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 in-
stead. 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 XmCreateOption-
Menu(). 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 XmNnum-
Columns, XmNorientation, and other inherited XmRowColumn resources.
For the Option type, the Chooser widget creates a menu pane and cre-
ates 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 Xmt-
NvisibleItems 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 be-
havior (XmtChooserRadioBox, XmtChooserRadioPalette, XmtChooserRadioList or
XmtChooserOption), then the state is simply the index of the currently se-
lected 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, in-
cluding 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 sys-
tems 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 how-
ever, 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 them-
selves: 8, 10, 12, 14, and 18.

An application can easily maintain an array of values to map from item num-
ber 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 Xmt-
NvalueStrings 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 regis-
tered. (Values beginning with ``XtR'', ``XmR'', or ``XmtR'' are the sym-
bolic 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 XmtNval-
ueStrings is specified, each string in the array will be converted to the
specified type. The Chooser widget will allocate an array for the XmtNval-
ues 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, XmtNvalueChangedCall-
back. 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 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 par-
ticular 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 but-
ton 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 re-
source 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 option-
ally 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 suit-
able 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 Xmt-
Npixmaps, XmtNselectPixmaps and XmtNinsensitivePixmaps resources. Because
many applications will not use the Chooser widget with pixmaps, this con-
verter is not automatically registered by the widget. You can register it
explicitly by calling XmtRegisterPixmapListConverter(). This converter con-
verts a comma separated list of pixmap names within quotes, optionally fol-
lowed by a color table to specify symbolic color substitutions for those
pixmaps. See XmtRegisterPixmapListConverter(), XmtRegisterColorTableCon-
verter(), and XmtGetPixmap() for more information.

TRANSLATIONS and ACTIONS

The Chooser widget simply inherits the translations of the XmRowColumn wid-
get class, and does not set translations on any of its automatically cre-
ated 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 Xm-
List 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.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages