XmSelectionBox(3Xm) XmSelectionBox(3Xm)
NAME
XmSelectionBox - the SelectionBox widget class.
AES SUPPORT LEVEL
full-use
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
- 1 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
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.
- 2 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
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
- 3 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
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
- 4 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
__________________________________________________________________________________
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
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
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
- 5 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
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.
- 6 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
<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
- 7 -
XmSelectionBox(3Xm) XmSelectionBox(3Xm)
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(3X) and its sections on behavior and
default translations.
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmBulletinBoard(3X), XmCreateSelectionBox(3X),
XmCreateSelectionDialog(3X), XmCreatePromptDialog(3X),
XmManager(3X), and XmSelectionBoxGetChild(3X).
- 8 -