NAME
XmDropDown2 — The DropDown widget class
SYNOPSIS
#include <Xm/DropDown.h>
DESCRIPTION
The DropDown widget allows the user to select elements from a list of
choices, and enter their own values in a text widget. To conserve
screen space, the list of choices is shown only when the user selects
the down arrow button. The choices may then be selected from this list.
If the list widget is in Browse Select mode (the default) or Single
Select mode, then the list will automatically be removed when the user
selects an item in the list. When the list is in other modes, multiple
items may be selected and the list may be popped down by either another
click on the arrow button, a click outside the list or double-clicking
an item. When using keyboard traversal, the list may be popped down by
selecting the arrow button or Alt - down arrow, and popped back up by
typing either the osfActivate key, a carriage return, or Alt - up
arrow. In any case, when the list is removed the item or items that
were selected will be placed in the text widget separated by commas.
Typing the escape key when the list is up, cancels the list popup,
restoring the DropDown widget to the state it was in before the list
was popped up. If the text field area is non-editable, clicking
anywhere in the text field the list will also pop down.
Resources are available to change the margin sizes, the location of the
left edge of the popup list, whether or not the label is shown, whether
the text field widget may be edited, and whether or not the text in the
list is verified against the choices available in the list. By setting
resources that occur in the children of the DropDown widget, the
contents of the list, the number of items visible in the list, the
initial value of the text field, and the value of the label may be set
or changed dynamically.
If a developer wishes the popup list’s shell to be resizable, they
should set the allowShellResize to True at creation time.
Classes
XmDropDown inherits behavior, resources, and traits from Core,
Composite, and XmManager classes.
The class pointer is xmDropDownWidgetClass.
The class name is XmDropDown.
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 at creation time (C), set
by using XtSetValues (S), retrieved by using XtGetValues (G), or is not
applicable (N/A).
+---------------------------------------------------------------------------------------+
| | XmDropDown Resource|Set | | |
|Name | Class | Type | Default | Access |
+----------------------------+---------------------+----------------+----------+--------+
|XmNcustomizedCombinationBox | XmCBoolean | Boolean | False | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNeditable | XmCBoolean | Boolean | True | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNhorizontalMargin | XmCMargin | Dimension | 2 | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNitemCount | list | int | 0 | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNitems | list | XmStringTable | NULL | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNlabelString | label | XmString | "label" | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNpopupCursor | XmCCursor | Cursor | left_ptr | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNpopupOffset | MxCPopupOffset | int | 15 | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNpopupShellWidget | XmCWidget | Widget | NULL | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNshowLabel | XmCBoolean | Boolean | True | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNupdateShellCallback | XmCCallback | XtCallbackList | NULL | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNupdateTextCallback | XmCCallback | XtCallbackList | NULL | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNuseTextField | XmCUseTextField | Boolean | True | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNvalue | text | String | "" | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNverify | XmCVerify | Boolean | True | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNverifyTextCallback | XmCCallback | XtCallbackList | NULL | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNverticalMargin | XmCMargin | Dimension | 2 | CSG |
+----------------------------+---------------------+----------------+----------+--------+
|XmNvisibleItemCount | XmCVisibleItemCount | int | 0 | CSG |
+----------------------------+---------------------+----------------+----------+--------+
+----------------------------+---------------------+----------------+----------+--------+
XmNcustomizedCombinationBox
If this resource is True then the widget will not
automatically create a popup shell and list widget. This
resource can be used, as the name implies, to create a custom
combination box that has something other than a list in it.
If this resource is true then a shell must be provided to the
DropDown widget via the popupShellWidget resource. Just
before the shell is popped up the updateShellCallback is
called. Just after the shell is popped down the
updateTextCallback is called. If verify is true then the
verifyTextCallback is called when the combo box needs to
verify the contents of the text widget against the allowable
values in the custom shell.
XmNeditable
This boolean value determines whether the user is allowed to
type into TextField widget of the DropDown widget. If this
value is False, selecting the text field will popup the combo
box list
XmNhorizontalMargin
Specifies the horizontal spacing between the child widgets
and the boundary of the DropDown widget.
XmNverticalMargin
Specifies the vertical spacing between the child widgets and
the boundary of the DropDown widget.
XmNitemCount
The number of items in the popup list.
XmNitems The list of all choice that will be displayed in the popup
list.
XmNlabelString
The string displayed as the label of the DropDown widget.
XmNpopupCursor
The cursor to display to the user when the DropDown’s list is
popped up. See X Window System, Robert Scheiffler et al.,
Appendix B, for choices.
XmNpopupOffset
The amount of space in pixels between the left edge of the
Text widget and the left edge of the list when the list is
displayed. Positive values mean the text’s left edge is
farther to the left, negative values mean the list’s edge is
farther to the left. If this is a non-custom DropDown widget
the right edge of the text and the right edge of the arrow
button will always line up.
XmNpopupShellWidget
The widget identifier for the shell that is popped up when
the arrow is clicked. If customizedCombinationBox is False
then this widget is automatically created by the DropDown
widget.
XmNshowLabel
A boolean value that specifies whether or not to display the
DropDown Label widget.
XmNupdateShellCallback
XmNupdateTextCallback
The callback routine to call when either the shell widget
contents or the Text widget need to be updated to correspond
with the other. The shell is updated just before it is popped
up. The text is updated just after the shell is popped down.
If customizedComboBox is False then the updates are done
automatically by the combo box. These routines are called to
inform the application that an action has been taken, in case
it would like to do any further processing.
XmNuseTextField
A boolean value that specifies if an XmTextField or an XmText
widget should be used for the text entry portion of the
DropDown widget.
XmNvalue The string displayed in the Text widget.
XmNverify If this resource is true the DropDown widget will verify its
value against the list whenever it loses focus or the user
types <Carriage Return>. If the verification fails, an
XtWarning is generated with a name of XmNtextVerifyFailed. To
trap this message register an XtWarningMsgHandler.
XmNverifyTextCallback
This routine is called whenever the Text widget’s contents
may need to be verified against the popup shell’s contents.
If the customizedComboBox resource is False then the DropDown
widget has already performed the verification when this
routine is called.
XmNvisibleItemCount
The number of items visible in the popup list at one time.
Children
The DropDown is composed of many sub-widgets. Most of the information
displayed to the user is set through these sub widgets. Most values
passed to this widget through the argument list at creation time or via
set values are passed to each of this widget’s children. Get values
requests must be made on a child by child basis. The children of the
DropDown are listed below. The OSF/Motifdocumentation should be
consulted for an exhaustive set of resources for each child. A partial
list of the most common resources are listed here for convenience.
XmDropDown comboBox
XmLabel label
XmTextField text
XmArrowButton arrow
OverrideShell popupShell
XmScrolledWindow listSW
XmScrollBar ListvScrollBar
XmScrollBar ListhScrollBar
XmList list
The popup shell and its children are only created when
customizedCombinationBox is False.
Inherited Resources
XmDropDown inherits behavior and resources from the superclasses
described in the following tables. For a complete description of each
resource, refer to the reference page for that superclass.
+----------------------------------------------------------------------------------------------------+
| | 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 | NULL | CSG |
+------------------------+-----------------------+-------------------+----------------------+--------+
|XmNlayoutDirection | XmCLayoutDirection | XmDirection | dynamic | CG |
+------------------------+-----------------------+-------------------+----------------------+--------+
|XmNnavigationType | XmCNavigationType | XmNavigationType | XmTAB_GROUP | CSG |
+------------------------+-----------------------+-------------------+----------------------+--------+
|XmNpopupHandlerCallback | XmCCallback | XtCallbackList | NULL | C |
+------------------------+-----------------------+-------------------+----------------------+--------+
|XmNshadowThickness | XmCShadowThickness | Dimension | 0 | 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 | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|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 |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|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
None of the DropDown’s callback procedures have any call data currently
defined for them. The widget passed to each of these functions is the
DropDown widget.
void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)
cbw This is the widget identifier of the DropDown widget.
client_data The client data passed to this widget by the application
programmer.
unused This value is undefined.
Geometry Management
The DropDown widget lays out its children (the label, text and arrow)
in a row. The amount of space they are each allocated when the
DropDown is not allowed to be the exact size it desires is determined
using the following rules:
1. The arrow is always given its requested size.
2. If the combo box is bigger than it wants to be all extra space is
given to the text widget.
3. If the combo box is smaller that is wants to be then the text and
label widgets are each sized smaller than they desire in exactly
the same ratio.
For example:
If the amount of space for the label and text is 100 pixels and
the label wants to be 50 pixels wide and the text would like to be
100 pixels wide then the label will get 34 pixels and the text 66.
The popup shell widget is sized such that the width of the
scrolled list widget equals the width of the text widget minus the
value of the "popupOffset" resource. If the popup shell resides in
a customized combination box, however, it is allowed to be
whatever size the child of the popup shell would like to be.
RELATED
Composite(3), Core(3), XmCreateDropDown(3), XmDropDownGetArrow(3),
XmDropDownGetLabel(3), XmDropDownGetList(3), XmDropDownGetText(3),
XmDropDownGetValue(3), XmList(3), XmManager(3) and XmTextField(3).
COPYRIGHT
Copyright (c) 1992 by Integrated Computer Solutions, Inc.
XmDropDown(library call)