|
|
XmSelectionBox(3X)
Contents
|
XmSelectionBox - The SelectionBox widget class
#include <Xm/SelectioB.h>
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 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.
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 [Toc] [Back]
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 [Toc] [Back]
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).
XmSelectionBox Resource Set [Toc] [Back]
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCApplyLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCancelLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCChildPlacement
Default: XmPLACE_ABOVE_SELECTION
Type: unsigned char
Access: CSG
Class: XmCDialogType
Default: dynamic
Type: unsigned char
Access: CG
Class: XmCHelpLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCItemCount
Default: 0
Type: int
Access: CSG
Class: XmCItems
Default: NULL
Type: XmStringTable
Access: CSG
Class: XmCListLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCVisibleItemCount
Default: dynamic
Type: int
Access: CSG
Class: XmCMinimizeButtons
Default: False
Type: Boolean
Access: CSG
Class: XmCMustMatch
Default: False
Type: Boolean
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCOkLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCSelectionLabelString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCTextAccelerators
Default: default
Type: XtAccelerators
Access: C
Class: XmCColumns
Default: dynamic
Type: short
Access: CSG
Class: XmCTextString
Default: ""
Type: XmString
Access: CSG
Specifies the list of callbacks called when the
user activates the Apply button. The callback reason
is XmCR_APPLY. 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". Specifies the list of callbacks called
when the user activates the Cancel button. The
callback reason is XmCR_CANCEL. 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". Specifies the
placement of the work area child. The possible
values are: XmPLACE_ABOVE_SELECTION--places the
work area child above the Text area
XmPLACE_BELOW_SELECTION--places the work area child
below the Text area XmPLACE_TOP--places the work
area child above the List area, and below a
menubar, if one is present 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. 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".
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.
Specifies the number of items in the SelectionBox
list. The value must not be negative. 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 XmDIALOG_PROMPT; in that case the default is
NULL. 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. 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. 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. 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. 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. Specifies the string label for
the OK button. The default for this resource
depends on the locale. In the C locale the default
is "OK". 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". 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. Specifies the number
of columns in the Text widget. The value must be
greater than 0. Specifies the text in the text
edit selection field.
Inherited Resources [Toc] [Back]
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 [Toc] [Back]
Class: XmCAllowOverlap
Default: True
Type: Boolean
Access: CSG
Class: XmCAutoUnmanage
Default: True
Type: Boolean
Access: CG
Class: XmCButtonFontList
Default: dynamic
Type: XmFontList
Access: CSG
Class: XmCWidget
Default: dynamic
Type: Widget
Access: SG
Class: XmCWidget
Default: dynamic
Type: Widget
Access: SG
Class: XmCDefaultPosition
Default: True
Type: Boolean
Access: CSG
Class: XmCDialogStyle
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCDialogTitle
Default: NULL
Type: XmString
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCLabelFontList
Default: dynamic
Type: XmFontList
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCMarginHeight
Default: 10
Type: Dimension
Access: CSG
Class: XmCMarginWidth
Default: 10
Type: Dimension
Access: CSG
Class: XmCNoResize
Default: False
Type: Boolean
Access: CSG
Class: XmCResizePolicy
Default: XmRESIZE_ANY
Type: unsigned char
Access: CSG
Class: XmCShadowType
Default: XmSHADOW_OUT
Type: unsigned char
Access: CSG
Class: XmCTextFontList
Default: dynamic
Type: XmFontList
Access: CSG
Class: XmCTranslations
Default: NULL
Type: XtTranslations
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmManager Resource Set [Toc] [Back]
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCInitialFocus
Default: dynamic
Type: Widget
Access: CSG
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set [Toc] [Back]
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set [Toc] [Back]
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: N/A
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Callback Information [Toc] [Back]
A pointer to the following structure is passed to each
callback: typedef struct {
int reason;
XEvent * event;
XmString value;
int length; } XmSelectionBoxCallbackStruct;
Indicates why the callback was invoked Points to the
XEvent that triggered the callback Indicates the XmString
value selected by the user from the SelectionBox list or
entered into the SelectionBox text field Indicates the
size in bytes of the XmString value
Translations [Toc] [Back]
XmSelectionBox inherits translations from XmBulletinBoard.
Accelerators [Toc] [Back]
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 [Toc] [Back]
The XmSelectionBox action routines are described below:
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. Replaces the text value with the list selection.
If no item in the list is selected, clears
the text.
Additional Behavior [Toc] [Back]
The SelectionBox widget has the additional behavior
described below: 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. 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.
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. Calls the
XmNapplyCallback callbacks with reason XmCR_APPLY. Calls
the XmNcancelCallback callbacks with reason XmCR_CANCEL.
Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
Calls the callbacks for XmNmapCallback if the SelectionBox
is a child of a Dialog shell. Calls the callbacks for
XmNunmapCallback if the SelectionBox is the child of a
DialogShell.
Virtual Bindings [Toc] [Back]
The bindings for virtual keys are vendor specific. For
information about bindings for virtual buttons and keys,
see VirtualBindings(3X).
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateSelectionBox(3X), XmCreateSelectionDialog(3X), XmCreatePromptDialog(3X), XmManager(3X), XmSelectionBoxGetChild(3X)
XmSelectionBox(3X)
[ Back ] |
