XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
NAME
XmSelectionBox - the SelectionBox widget class.
SYNOPSIS
#include <Xm/SelectioB.h>
DESCRIPTION
SelectionBox is a general dialog widget that allows the user to select
one item from a list. By default 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 or four buttons
The default button labels are OK, Cancel, and Help. By default an Apply
button is also created; if the parent of the SelectionBox is a
DialogShell it is managed, and otherwise it is unmanaged. 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
and selecting the desired item or by entering the item name directly into
the text edit area. Selecting an item from the list causes 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.
The default value for the XmBulletinBoard resource XmNcancelButton is the
Cancel button unless XmNdialogType is XmDIALOG_COMMAND, when the default
is NULL. The default value for the XmBulletinBoard resource
XmNdefaultButton is the OK button unless XmNdialogType is
XmDIALOG_COMMAND, when the default is NULL.
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
10/89 Page 1
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
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 lowercase or uppercase, 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 C
___________________________________________________________________________________________
XmNcancelLabelString XmCCancelLabelString XmString "Cancel" CSG
___________________________________________________________________________________________
XmNdialogType XmCDialogType unsigned char dynamic CG
___________________________________________________________________________________________
XmNhelpLabelString XmCHelpLabelString XmString "Help" CSG
___________________________________________________________________________________________
XmNlistItemCount XmCItemCount int 0 CSG
___________________________________________________________________________________________
XmNlistItems XmCItems XmStringTable NULL CSG
___________________________________________________________________________________________
XmNlistLabelString XmCListLabelString XmString dynamic CSG
___________________________________________________________________________________________
XmNlistVisibleItemCount XmCVisibleItemCount int dynamic CSG
___________________________________________________________________________________________
XmNminimizeButtons XmCMinimizeButtons Boolean False CSG
___________________________________________________________________________________________
XmNmustMatch XmCMustMatch Boolean False CSG
___________________________________________________________________________________________
XmNnoMatchCallback XmCCallback XtCallbackList NULL C
___________________________________________________________________________________________
XmNokCallback XmCCallback XtCallbackList NULL C
___________________________________________________________________________________________
XmNokLabelString XmCOkLabelString XmString "OK" CSG
___________________________________________________________________________________________
XmNselectionLabelString XmCSelectionLabelString XmString "Selection" CSG
___________________________________________________________________________________________
XmNtextAccelerators XmCTextAccelerators XtAccelerators default C
___________________________________________________________________________________________
XmNtextColumns XmCColumns short dynamic CSG
___________________________________________________________________________________________
Page 2 10/89
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
|XmNtextString | XmCTextString | XmString | "" | CSG |
|_______________________|_________________________|________________|_____________|________|
XmNapplyCallback
Specifies the list of callbacks called when the user activates the
Apply button. The callback reason is XmCRAPPLY.
XmNapplyLabelString
Specifies the string label for the Apply button.
XmNcancelCallback
Specifies the list of callbacks called when the user activates 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 that are
created and managed at initialization. The following are possible
values:
⊕ XmDIALOG_PROMPT - all standard children except the list and list
label are created, and all except the Apply button are managed
⊕ XmDIALOG_COMMAND - only the list, the selection label, and the
text field are created and managed
⊕ XmDIALOG_SELECTION - all standard children are created and
managed
⊕ XmDIALOG_FILE_SELECTION - all standard children are created and
managed
⊕ XmDIALOG_WORK_AREA - all standard children are created, and all
except the Apply button are 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. XtGetValues for this
resource returns the list items themselves, not a copy of the list
items. The application must not free the returned items.
10/89 Page 3
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
XmNlistItemCount
Specifies the number of items in the SelectionBox list. The value
must not be negative.
XmNlistLabelString
Specifies the string label to appear above the SelectionBox list
containing the selection items. The default is "Items" unless
XmNdialogType is XmDIALOG_PROMPT; in that case the default is NULL.
XmNlistVisibleItemCount
Specifies the number of items displayed in the SelectionBox list.
The value must be greater than 0 unless XmNdialogType is
XmDIALOG_PROMPT; in that case the value is always 0. The default
is dynamic based on the height of the 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 the selection widget should check if the user's
selection in the text edit field has an exact match in the
SelectionBox list when the BOK button is activated. If the
selection does not have an exact match, and XmNmustMatch is True,
the XmNnoMatchCallback callbacks are called. If the selection does
have an exact match or if XmNmustMatch is False, XmNokCallback
callbacks are called.
XmNnoMatchCallback
Specifies the list of callbacks 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 called when the user activates the
OK button. The callback reason is XmCR_OK. If the selection text
does not match a list item, and XmNmustMatch is True, the
XmNnoMatchCallback callbacks are called instead.
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. This resource is ignored if
Page 4 10/89
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
XmNaccelerators is initialized to a nondefault value.
XmNtextColumns
Specifies the number of columns in the Text widget. The value must
be greater than 0.
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 each resource, 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 CG
___________________________________________________________________________________
XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG
___________________________________________________________________________________
XmNcancelButton XmCWidget Widget dynamic SG
___________________________________________________________________________________
XmNdefaultButton XmCWidget Widget dynamic SG
___________________________________________________________________________________
XmNdefaultPosition XmCDefaultPosition Boolean True CSG
___________________________________________________________________________________
XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG
___________________________________________________________________________________
XmNdialogTitle XmCDialogTitle XmString NULL CSG
___________________________________________________________________________________
XmNfocusCallback XmCCallback XtCallbackList NULL C
___________________________________________________________________________________
XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG
___________________________________________________________________________________
XmNmapCallback XmCCallback XtCallbackList NULL C
___________________________________________________________________________________
XmNmarginHeight XmCMarginHeight Dimension 10 CSG
___________________________________________________________________________________
XmNmarginWidth XmCMarginWidth Dimension 10 CSG
___________________________________________________________________________________
XmNnoResize XmCNoResize Boolean False CSG
___________________________________________________________________________________
XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG
___________________________________________________________________________________
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG
10/89 Page 5
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
|____________________|____________________|________________|______________|________|
| XmNtextFontList | XmCTextFontList | XmFontList | dynamic | CSG |
|____________________|____________________|________________|______________|________|
| XmNtextTranslations| XmCTranslations | XtTranslations| NULL | C |
|____________________|____________________|________________|______________|________|
| XmNunmapCallback | XmCCallback | XtCallbackList| NULL | C |
|____________________|____________________|________________|______________|________|
_________________________________________________________________________________________________________
| XmManager Resource Set |
|_____________________|_____________________________|___________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________|_____________________________|___________________|______________________|________|
|_____________________|_____________________________|___________________|______________________|________|
|XmNbottomShadowColor | XmCBottomShadowColor | Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNbottomShadowPixmap| XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNforeground | XmCForeground | Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
|_____________________|_____________________________|___________________|______________________|________|
|XmNhighlightColor | XmCHighlightColor | Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNstringDirection | XmCStringDirection | XmStringDirection| dynamic | CG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowColor | XmCBackgroundTopShadowColor| Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_____________________________|___________________|______________________|________|
_______________________________________________________________________
Composite Resource Set
_______________________________________________________________________
Name Class Type Default Access
_______________________________________________________________________
_______________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
_______________________________________________________________________
XmNinsertPosition XmCInsertPosition (*)() NULL CSG
Page 6 10/89
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
|__________________|___________________|____________|_________|________|
| XmNnumChildren | XmCReadOnly | Cardinal | 0 | G |
|__________________|___________________|____________|_________|________|
________________________________________________________________________________________________________________
| Core Resource Set |
|_____________________________|_______________________________|________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________________|_______________________________|________________|______________________|________|
|_____________________________|_______________________________|________________|______________________|________|
|XmNaccelerators | XmCAccelerators | XtAccelerators| dynamic | N/A |
|_____________________________|_______________________________|________________|______________________|________|
|XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackground | XmCBackground | Pixel | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNcolormap | XmCColormap | Colormap | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdepth | XmCDepth | int | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdestroyCallback | XmCCallback | XtCallbackList| NULL | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNheight | XmCHeight | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNinitialResourcesPersistent| XmCInitialResourcesPersistent| Boolean | True | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNscreen | XmCScreen | Screen * | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNsensitive | XmCSensitive | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNtranslations | XmCTranslations | XtTranslations| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNwidth | XmCWidth | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNx | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNy | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
10/89 Page 7
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
Callback Information
A pointer to the following structure is passed to 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
Translations
XmSelectionBox inherits translations from XmBulletinBoard.
Accelerators
The XmNtextAccelerators are added to the Text descendant of
XmSelectionBox. The default accelerators are listed below. These
accelerators may not directly correspond to a translation table.
KUp: SelectionBoxUpOrDown(0)
KDown: SelectionBoxUpOrDown(1)
KBeginData: SelectionBoxUpOrDown(2)
KEndData: SelectionBoxUpOrDown(3)
KRestore: SelectionBoxRestore()
Action Routines
The XmSelectionBox action routines are described below:
SelectionBoxUpOrDown(0|1|2|3):
When called with a 0 argument, selects the previous item in the
list and replaces the text with that item.
When called with a 1 argument, selects the next item in the list
and replaces the text with that item.
When called with a 2 argument, selects the first item in the list
and replaces the text with that item.
Page 8 10/89
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
When called with a 3 argument, selects the last item in the list
and replaces the text with that item.
SelectionBoxRestore():
Replaces the text value with the list selection. If no item in the
list is selected, clears the text.
Additional Behavior
The SelectionBox widget has the additional behavior described below:
MAny KCancel:
Calls the activate callbacks for the cancel button if it is
sensitive.
KActivate:
Calls the activate callbacks for the button with the keyboard
focus. If no button has the keyboard focus, calls the activate
callbacks for the default button if it is sensitive. In a List
widget or single-line Text widget, the List or Text action
associated with KActivate is called before the SelectionBox actions
associated with KActivate. In a multi-line Text widget, any
KActivate event except KEnter calls the Text action associated with
KActivate, then the SelectionBox actions associated with KActivate.
<OK Button Activated>:
If XmNmustMatch is True and the text does not match an item in the
file list, calls the XmNnoMatchCallback callbacks with reason
XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with
reason XmCR_OK.
<Apply Button Activated>:
Calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
<Cancel Button Activated>:
Calls the XmNcancelCallback callbacks with reason XmCR_CANCEL.
<Help Button Activated>:
Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
<MapWindow>:
Calls the callbacks for XmNmapCallback if the SelectionBox is a
child of a Dialog shell.
<UnmapWindow>:
Calls the callbacks for XmNunmapCallback if the SelectionBox is the
child of a DialogShell.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).
10/89 Page 9
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X),
XmCreateSelectionBox(3X), XmCreateSelectionDialog(3X),
XmCreatePromptDialog(3X), XmManager(3X), and XmSelectionBoxGetChild(3X).
Page 10 10/89