NAME

XmSelectionBox — the SelectionBox widget class. 

SYNOPSIS

#include <Xm/SelectioB.h>

DESCRIPTION

SelectionBox is a general dialog widget which allows the user to select one item out of a list of items.  A SelectionBox includes the following:

•A scrolling list of alternatives. 

•An editable text field for the selected alternative. 

•Labels for the list and text field. 

•Three buttons. 

The default button labels are OK, Cancel, and Help.  An Apply button is created unmanaged and may be explicitly managed as needed.  One additional WorkArea child may be added to the SelectionBox after creation. 

The user can select an item in two ways: by scrolling through the list of items and selecting the desired item or by entering the item name directly into the text edit area.  Selecting an item from the list will cause that item name to appear in the selection text edit area. 

The user may select a new item as many times as desired.  The item is not actually selected until the user presses the OK PushButton. 

Classes

SelectionBox inherits behavior and resources from Core, Composite, Constraint, XmManager and XmBulletinBoard Classes. 

The class pointer is xmSelectionBoxWidgetClass. 

The class name is XmSelectionBox. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNapplyCallback
Specifies the list of callbacks that is called when the user clicks on the Apply button.  The callback reason is XmCR_APPLY. 

XmNapplyLabelString
Specifies the string label for the Apply button. 

XmNcancelCallback
Specifies the list of callbacks that is called when the user clicks on the Cancel button.  The callback reason is XmCR_CANCEL. 

XmNcancelLabelString
Specifies the string label for the Cancel button. 

XmNdialogType
Determines the set of SelectionBox children widgets which are created and managed at initialization.  The following are possible values:

•XmDIALOG_PROMPT — the list and list label are not created, and the Apply button is unmanaged. 

•XmDIALOG_SELECTION — all standard children are created and managed except the Apply button. 

•XmDIALOG_WORK_AREA — all standard children are created and managed. 

If the parent of the SelectionBox is a DialogShell, the default is XmDIALOG_SELECTION; otherwise, the default is XmDIALOG_WORK_AREA.  XmCreatePromptDialog and XmCreateSelectionDialog set and append this resource to the creation arglist supplied by the application.  This resource cannot be modified after creation. 

XmNhelpLabelString
Specifies the string label for the Help button. 

XmNlistItems
Specifies the items in the SelectionBox list.

XmNlistItemCount
Specifies the number of items in the SelectionBox list.

XmNlistLabelString
Specifies the string label to appear above the SelectionBox list containing the selection items.

XmNlistVisibleItemCount
Specifies the number of items displayed in the SelectionBox list.

XmNminimizeButtons
Sets the buttons to the width of the widest button and height of the tallest button if False.  If True, button width and height are not modified.

XmNmustMatch
Specifies whether or not the selection widget should check if the user’s selection in the text edit field has an exact match in the SelectionBox list.  If the selection does not have an exact match, and XmNmustMatch is True, the XmNnoMatchCallback is activated.  If the selection does have an exact match, then either XmNapplyCallback or XmNokCallback is activated. 

XmNnoMatchCallback
Specifies the list of callbacks that is called when the user makes a selection from the text edit field that does not have an exact match with any of the items in the list box. The callback reason is XmCR_NO_MATCH.  Callbacks in this list are called only if XmNmustMatch is true. 

XmNokCallback
Specifies the list of callbacks that is called when the user clicks the OK button.  The callback reason is XmCR_OK. 

XmNokLabelString
Specifies the string label for the OK button. 

XmNselectionLabelString
Specifies the string label for the selection text edit field.

XmNtextAccelerators
Specifies translations added to the Text widget child of the SelectionBox.  The default includes bindings for the up and down keys for auto selection of list items; it also includes the normal accelerator translations defined by BulletinBoard for dialog components.

XmNtextColumns
Specifies the number of columns in the Text widget.

XmNtextString
Specifies the text in the text edit selection field.

Inherited Resources

SelectionBox inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

The following structure is returned with each callback:

typedef struct
{
intreason;
XEvent∗ event;
XmStringvalue;
intlength;
} XmSelectionBoxCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

valueIndicates the XmString value selected by the user from the SelectionBox list or entered into the SelectionBox text field. 

lengthIndicates the size in bytes of the XmString value. 

Behavior

The following is a summary of the behavior of SelectionBox. 

<OK Button Activated>:
When the OK button is activated, the callback XmNokCallback is called.  The reason is XmCR_OK.  When an invalid selection is made and it does not match any items in the list, the callback for XmNnoMatchCallback is called if XmNmustMatch is also True.  The callback reason is XmCR_NO_MATCH. 

<Apply Button Activated>:
When the Apply button is activated, the callback XmNapplyCallback is called.  The callback reason is XmCR_APPLY.  When an invalid selection is made and it does not match any items in the list, the callback for XmNnoMatchCallback is called, if XmNmustMatch is also True.  The callback reason is XmCR_NO_MATCH. 

<Cancel Button Activated>:
When the Cancel button is activated, the callback XmNcancelCallback is called.  The callback reason is XmCR_CANCEL. 

<Help Button Activated> or <Key>F1:
When the Help button or Function key 1 is pressed, the callbacks for XmNhelpCallback are called. 

<Default Button Activated> or <Key>Return:
When the default button or return key is pressed, the corresponding callback is called (XmNokCallback, XmNapplyCallback, XmNcancelCallback, or XmNhelpCallback). 

<Key>Up or <Key>Down:
When the up or down key is pressed within the Text subwidget of the SelectionBox, the text value is replaced with the previous or next item in the List subwidget.

<FocusIn>:
When a FocusIn event is generated on the widget window, the callbacks for XmNfocusCallback are called. 

<MapWindow>:
When a SelectionBox that is the child of a DialogShell is mapped, the callbacks for XmNmapCallback are invoked.  When a SelectionBox that is not the child of a DialogShell is mapped, the callbacks are not invoked. 

<UnmapWindow>:
When a SelectionBox that is the child of a DialogShell is unmapped, the callbacks for XmNunmapCallback are invoked.  When a SelectionBox that is not the child of a DialogShell is unmapped, the callbacks are not invoked. 

Default Translations

The following are the default translations defined for SelectionBox widgets:

<EnterWindow>: Enter()
<FocusIn>:FocusIn()
<Btn1Down>:Arm()
<Btn1Up>:Activate()
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Default Accelerators

The following are the default accelerator translations added to the descendants of a SelectionBox:

#override
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Default Text Accelerators

The following are the default accelerators added to the Text child of the SelectionBox:

#override
<Key>Up:UpOrDown(0)
<Key>Down:UpOrDown(1)
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Keyboard Traversal

For information on keyboard traversal, see the man page for XmManager(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Composite(3Xm), Constraint(3Xm), Core(3Xm), XmBulletinBoard(3Xm), XmCreateSelectionBox(3Xm), XmCreateSelectionDialog(3Xm), XmCreatePromptDialog(3Xm), XmManager(3Xm), and XmSelectionBoxGetChild(3Xm). 

7th Edition