XmSelectionBox(3Xm)

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).

XmSelectionBox Resource Set
Name | Class | Type | Default | Access
XmNapplyCallback | XmCCallback | XtCallbackList | NULL | C
XmNapplyLabelString | XmCApplyLabelString | XmString | "Apply" | CSG
XmNcancelCallback | XmCCallback | XtCallbackList | NULL | CSG
XmNcancelLabelString | XmCXmString | XmString | "Cancel" | CSG
XmNdialogType | XmCDialogType | unsigned char | dynamic | CG
XmNhelpLabelString | XmCXmString | XmString | "Help" | CSG
XmNlistItemCount | XmCItemCount | int | 0 | CSG
XmNlistItems | XmCItems | XmStringList | NULL | CSG
XmNlistLabelString | XmCXmString | XmString | NULL | CSG
XmNlistVisibleItemCount | XmCVisibleItemCount | int | 8 | CSG
XmNminimizeButtons | XmCMinimizeButtons | Boolean | False | CSG
XmNmustMatch | XmCMustMatch | Boolean | False | CSG
XmNnoMatchCallback | XmCCallback | XtCallbackList | NULL | C
XmNokCallback | XmCCallback | XtCallbackList | NULL | C
XmNokLabelString | XmCXmString | XmString | "OK" | CSG
XmNselectionLabelString | XmCXmString | XmString | "Selection" | CSG
XmNtextAccelerators | XmCTextAccelerators | XtTranslations | see below | C
XmNtextColumns | XmCTextColumns | int | 20 | CSG
XmNtextString | XmCTextString | XmString | NULL | CSG

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.

XmBulletinBoard Resource Set
Name | Class | Type | Default | Access
XmNallowOverlap | XmCAllowOverlap | Boolean | True | CSG
XmNautoUnmanage | XmCAutoUnmanage | Boolean | True | CSG
XmNbuttonFontList | XmCButtonFontList | XmFontList | NULL | CSG
XmNcancelButton | XmCWidget | Widget | Cancel button | SG
XmNdefaultButton | XmCWidget | Widget | OK button | SG
XmNdefaultPosition | XmCDefaultPosition | Boolean | True | CSG
XmNdialogStyle | XmCDialogStyle | unsigned char | dynamic | CSG
XmNdialogTitle | XmCXmString | XmString | NULL | CSG
XmNfocusCallback | XmCCallback | XtCallbackList | NULL | C
XmNlabelFontList | XmCLabelFontList | XmFontList | NULL | CSG
XmNmapCallback | XmCCallback | XtCallbackList | NULL | C
XmNmarginHeight | XmCMarginHeight | short | 10 | CSG
XmNmarginWidth | XmCMarginWidth | short | 10 | CSG
XmNnoResize | XmCNoResize | Boolean | False | CSG
XmNresizePolicy | XmCResizePolicy | unsigned char | XmRESIZE_ANY | CSG
XmNshadowType | XmCShadowType | unsigned char | XmSHADOW_OUT | CSG
XmNstringDirection | XmCStringDirection | XmStringDirection | XmSTRING_DIRECTION_L_TO_R | CSG
XmNtextFontList | XmCTextFontList | XmFontList | NULL | CSG
XmNtextTranslations | XmCTranslations | XtTranslations | NULL | C
XmNunmapCallback | XmCCallback | XtCallbackList | NULL | C

XmManager Resource Set
Name | Class | Type | Default | Access
XmNbottomShadowColor | XmCForeground | Pixel | dynamic | CSG
XmNbottomShadowPixmap | XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNforeground | XmCForeground | Pixel | dynamic | CSG
XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C
XmNhighlightColor | XmCForeground | Pixel | Black | CSG
XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG
XmNshadowThickness | XmCShadowThickness | short | dynamic | CSG
XmNtopShadowColor | XmCBackground | Pixel | dynamic | CSG
XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNunitType | XmCUnitType | unsigned char | XmPIXELS | CSG
XmNuserData | XmCUserData | caddr_t | NULL | CSG

Composite Resource Set
Name | Class | Type | Default | Access
XmNinsertPosition | XmCInsertPosition | XmRFunction | NULL | CSG

Core Resource Set
Name | Class | Type | Default | Access
XmNaccelerators | XmCAccelerators | XtTranslations | NULL | CSG
XmNancestorSensitive | XmCSensitive | Boolean | True | G
XmNbackground | XmCBackground | Pixel | dynamic | CSG
XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderColor | XmCBorderColor | Pixel | Black | CSG
XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG
XmNcolormap | XmCColormap | Colormap | XtCopyFromParent | CG
XmNdepth | XmCDepth | int | XtCopyFromParent | CG
XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C
XmNheight | XmCHeight | Dimension | 0 | CSG
XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG
XmNscreen | XmCScreen | Pointer | XtCopyScreen | CG
XmNsensitive | XmCSensitive | Boolean | True | CSG
XmNtranslations | XmCTranslations | XtTranslations | NULL | CSG
XmNwidth | XmCWidth | Dimension | 0 | CSG
XmNx | XmCPosition | Position | 0 | CSG
XmNy | XmCPosition | Position | 0 | CSG

  Callback Information
The following structure is returned with each callback:

typedef struct
{
	int	reason;
	XEvent	* event;
	XmString	value;
	int	length;
} XmSelectionBoxCallbackStruct;

reason
    Indicates why the callback was invoked.

event
    Points to the XEvent that triggered the callback.

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

length
    Indicates 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).