 |
Index for
Section 3X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
XmSelectionBox(3X)
OSF/Motif
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 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
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).
XmSelectionBox Resource Set
XmNapplyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNapplyLabelString
Class: XmCApplyLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNcancelCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNcancelLabelString
Class: XmCCancelLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNchildPlacement
Class: XmCChildPlacement
Default: XmPLACE_ABOVE_SELECTION
Type: unsigned char
Access: CSG
XmNdialogType
Class: XmCDialogType
Default: dynamic
Type: unsigned char
Access: CG
XmNhelpLabelString
Class: XmCHelpLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNlistItemCount
Class: XmCItemCount
Default: 0
Type: int
Access: CSG
XmNlistItems
Class: XmCItems
Default: NULL
Type: XmStringTable
Access: CSG
XmNlistLabelString
Class: XmCListLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNlistVisibleItemCount
Class: XmCVisibleItemCount
Default: dynamic
Type: int
Access: CSG
XmNminimizeButtons
Class: XmCMinimizeButtons
Default: False
Type: Boolean
Access: CSG
XmNmustMatch
Class: XmCMustMatch
Default: False
Type: Boolean
Access: CSG
XmNnoMatchCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNokCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNokLabelString
Class: XmCOkLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNselectionLabelString
Class: XmCSelectionLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNtextAccelerators
Class: XmCTextAccelerators
Default: default
Type: XtAccelerators
Access: C
XmNtextColumns
Class: XmCColumns
Default: dynamic
Type: short
Access: CSG
XmNtextString
Class: XmCTextString
Default: ""
Type: XmString
Access: CSG
XmNapplyCallback
Specifies the list of callbacks called when the user activates the
Apply button. The callback reason is XmCR_APPLY.
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 XmCR_CANCEL.
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:
· 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
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. 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.
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 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 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 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. The 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
XmNallowOverlap
Class: XmCAllowOverlap
Default: True
Type: Boolean
Access: CSG
XmNautoUnmanage
Class: XmCAutoUnmanage
Default: True
Type: Boolean
Access: CG
XmNbuttonFontList
Class: XmCButtonFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNcancelButton
Class: XmCWidget
Default: dynamic
Type: Widget
Access: SG
XmNdefaultButton
Class: XmCWidget
Default: dynamic
Type: Widget
Access: SG
XmNdefaultPosition
Class: XmCDefaultPosition
Default: True
Type: Boolean
Access: CSG
XmNdialogStyle
Class: XmCDialogStyle
Default: dynamic
Type: unsigned char
Access: CSG
XmNdialogTitle
Class: XmCDialogTitle
Default: NULL
Type: XmString
Access: CSG
XmNfocusCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNlabelFontList
Class: XmCLabelFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNmapCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNmarginHeight
Class: XmCMarginHeight
Default: 10
Type: Dimension
Access: CSG
XmNmarginWidth
Class: XmCMarginWidth
Default: 10
Type: Dimension
Access: CSG
XmNnoResize
Class: XmCNoResize
Default: False
Type: Boolean
Access: CSG
XmNresizePolicy
Class: XmCResizePolicy
Default: XmRESIZE_ANY
Type: unsigned char
Access: CSG
XmNshadowType
Class: XmCShadowType
Default: XmSHADOW_OUT
Type: unsigned char
Access: CSG
XmNtextFontList
Class: XmCTextFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNtextTranslations
Class: XmCTranslations
Default: NULL
Type: XtTranslations
Access: C
XmNunmapCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmManager Resource Set
XmNbottomShadowColor
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNbottomShadowPixmap
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNforeground
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
XmNhelpCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhighlightColor
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
XmNhighlightPixmap
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNinitialFocus
Class: XmCInitialFocus
Default: dynamic
Type: Widget
Access: CSG
XmNnavigationType
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
XmNshadowThickness
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
XmNstringDirection
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
XmNtopShadowColor
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNtopShadowPixmap
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNtraversalOn
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
XmNunitType
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
XmNuserData
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set
XmNchildren
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
XmNinsertPosition
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
XmNnumChildren
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set
XmNaccelerators
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: N/A
XmNancestorSensitive
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
XmNbackground
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
XmNbackgroundPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderColor
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
XmNborderPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderWidth
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
XmNcolormap
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
XmNdepth
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
XmNdestroyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNheight
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
XmNinitialResourcesPersistent
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
XmNmappedWhenManaged
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
XmNscreen
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
XmNsensitive
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
XmNtranslations
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
XmNwidth
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
XmNx
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
XmNy
Class: XmCPosition
Default: 0
Type: Position
Access: 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):
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 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).
SEE ALSO
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X),
XmCreateSelectionBox(3X), XmCreateSelectionDialog(3X),
XmCreatePromptDialog(3X), XmManager(3X), XmSelectionBoxGetChild(3X)
|
Index for
Section 3X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|