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. Additional children may be added
to the SelectionBox after creation. The first child is used
as a work area. The value of XmNchildPlacement determines
if the work area is placed above or below the Text area, or
above or below the List area. Additional children are laid
out in the following manner:
⊕ Menubar-The first menu bar child is placed at the top
of the window.
⊕ Buttons-All XmPushButton widgets or gadgets, and their
subclasses are placed after the OK button in the order
of their creation.
⊕ The layout of additional children which are not in the
above categories is undefined.
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
1 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
OK PushButton.
The default value for the XmBulletinBoard resource
XmNcancelButton is the Cancel button unless XmNdialogType is
XmDIALOGCOMMAND, when the default is NULL. The default
value for the XmBulletinBoard resource XmNdefaultButton is
the OK button unless XmNdialogType is XmDIALOGCOMMAND, when
the default is NULL.
For SelectionBox and its subclasses, the default value for
XmNinitialFocus is the text edit area.
The user can specify resources in a resource file for the
automatically created widgets and gadgets of SelectionBox.
The following list identifies the names of these widgets (or
gadgets) and the associated SelectionBox areas.
⊕ List Items Label-"Items"
⊕ List Items-"ItemsList"
⊕ Selection Label-"Selection"
⊕ Selection Text-"Text"
⊕ Selection Separator-"Separator"
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
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).
2 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
XmSelectionBox Resource Set
Name Class Type Default Access
_____________________________________________________________________________________________________
XmNapplyCallback XmCCallback XtCallbackList NULL C
XmNapplyLabelString XmCApplyLabelString XmString dynamic CSG
XmNcancelCallback XmCCallback XtCallbackList NULL C
XmNcancelLabelString XmCCancelLabelString XmString dynamic CSG
XmNchildPlacement XmCChildPlacement unsigned char XmPLACE_ABOVE_SELECTION CSG
XmNdialogType XmCDialogType unsigned char dynamic CG
XmNhelpLabelString XmCHelpLabelString XmString dynamic 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 dynamic CSG
XmNselectionLabelString XmCSelectionLabelString XmString dynamic CSG
XmNtextAccelerators XmCTextAccelerators XtAccelerators default C
XmNtextColumns XmCColumns short dynamic CSG
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.
The default for this resource depends on the
locale. In the C locale the default is "Apply".
XmNcancelCallback
Specifies the list of callbacks called when the
user activates the Cancel button. The callback
reason is XmCRCANCEL.
XmNcancelLabelString
Specifies the string label for the Cancel button.
The default for this resource depends on the
locale. In the C locale the default is "Cancel".
XmNchildPlacement
Specifies the placement of the work area child.
The possible values are:
⊕ XmPLACEABOVESELECTION-places the work area
child above the Text area
3 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
⊕ XmPLACEBELOWSELECTION-places the work area
child below the Text area
⊕ XmPLACETOP-places the work area child above
the List area, and below a menubar, if one is
present
XmNdialogType
Determines the set of SelectionBox children
widgets that are created and managed at
initialization. The following are possible
values:
⊕ XmDIALOGPROMPT-all standard children except
the list and list label are created, and all
except the Apply button are managed
⊕ XmDIALOGCOMMAND-only the list, the selection
label, and the text field are created and
managed
⊕ XmDIALOGSELECTION-all standard children are
created and managed
⊕ XmDIALOGFILESELECTION-all standard children
are created and managed
⊕ XmDIALOGWORKAREA-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 XmDIALOGSELECTION;
otherwise, the default is XmDIALOGWORKAREA.
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.
The default for this resource depends on the
locale. In the C locale the default is "Help".
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.
4 (printed 6/8/92)
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 for this resource depends on the
locale. In the C locale the default is "Items"
unless XmNdialogType is XmDIALOGPROMPT; 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 XmDIALOGPROMPT; 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 OK 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
XmCRNOMATCH. 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 XmCROK. 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. The
5 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
default for this resource depends on the locale.
In the C locale the default is "OK".
XmNselectionLabelString
Specifies the string label for the selection text
edit field. The default for this resource depends
on the locale. In the C locale the default is
"Selection".
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 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
6 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG
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
XmNinitialFocus XmCInitialFocus Widget dynamic CSG
XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNstringDirection XmCStringDirection XmStringDirection dynamic CG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean True CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer NULL CSG
Composite Resource Set
Name Class Type Default Access
______________________________________________________________________
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG
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
7 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
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
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):
8 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
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.
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. If no cancel button exists
and the parent of the SelectionBox is a manager,
passes the event to the parent.
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.
If no button has the focus, no default button
exists, and the parent of the SelectionBox is a
manager, passes the event to the parent.
<OK Button Activated>:
If XmNmustMatch is True and the text does not
9 (printed 6/8/92)
XmSelectionBox(3X) UNIX System V XmSelectionBox(3X)
match an item in the file list, calls the
XmNnoMatchCallback callbacks with reason
XmCRNOMATCH. Otherwise, calls the XmNokCallback
callbacks with reason XmCROK.
<Apply Button Activated>:
Calls the XmNapplyCallback callbacks with reason
XmCRAPPLY.
<Cancel Button Activated>:
Calls the XmNcancelCallback callbacks with reason
XmCRCANCEL.
<Help Button Activated>:
Calls the XmNhelpCallback callbacks with reason
XmCRHELP.
<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).
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmBulletinBoard(3X), XmCreateSelectionBox(3X),
XmCreateSelectionDialog(3X), XmCreatePromptDialog(3X),
XmManager(3X), and XmSelectionBoxGetChild(3X).
10 (printed 6/8/92)