XmSelectionBox(Xm) UNIX System V
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 XmCRAPPLY.
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 XmCRCANCEL.
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:
⊕ XmDIALOGPROMPT - the list and list label are not
created, and the Apply button is unmanaged.
⊕ XmDIALOGSELECTION - all standard children are created
and managed except the Apply button.
⊕ XmDIALOGWORKAREA - all standard children are created
and 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.
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 XmCRNOMATCH. 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
XmCROK.
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 XmCROK. 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 XmCRNOMATCH.
<Apply Button Activated>:
When the Apply button is activated, the callback
XmNapplyCallback is called. The callback reason is
XmCRAPPLY. 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 XmCRNOMATCH.
<Cancel Button Activated>:
When the Cancel button is activated, the callback
XmNcancelCallback is called. The callback reason is
XmCRCANCEL.
<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>KPEnter: 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>KPEnter: 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>KPEnter: Return()
Keyboard Traversal
For information on keyboard traversal, see the man page for
XmManager(Xm) and its sections on behavior and default
translations.
RELATED INFORMATION
Composite(Xm), Constraint(Xm), Core(Xm),
XmBulletinBoard(Xm), XmCreateSelectionBox(Xm),
XmCreateSelectionDialog(Xm), XmCreatePromptDialog(Xm),
XmManager(Xm), and XmSelectionBoxGetChild(Xm).
(printed 2/14/90) XmSelectionBox(Xm)