.DT
.TH "XmDropDown" "library call"
.SH NAME
\fBXmDropDown\fP \(em The DropDown widget class
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/DropDown\&.h>
.fi
.SH DESCRIPTION
.PP
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.
.PP
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.
.PP
If a developer wishes the popup list's shell to be resizable, they should set the
allowShellResize to True at creation time.
.SS "Classes"
.PP
\fBXmDropDown\fP inherits behavior, resources, and traits from \fBCore\fP,
\fBComposite\fP, and \fBXmManager\fP classes\&.
.PP
The class pointer is \fBxmDropDownWidgetClass\fP\&.
.PP
The class name is \fBXmDropDown\fP\&.
.PP
.SS "New Resources"
.PP
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 \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or \fBXmC\fP prefix and
use the
remaining letters\&. To specify one of the defined values for a
resource in a \fB\&.Xdefaults\fP file, remove the \fBXm\fP 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 \fBXtSetValues\fP (S), retrieved by
using \fBXtGetValues\fP (G), or is not applicable (N/A)\&.
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBXmDropDown Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNcustomizedCombinationBoxXmCBooleanBooleanFalseCSG
_____
XmNeditableXmCBooleanBooleanTrueCSG
_____
XmNhorizontalMarginXmCMarginDimension2CSG
_____
XmNitemCountlistint0CSG
_____
XmNitemslistXmStringTableNULLCSG
_____
XmNlabelStringlabelXmString"label"CSG
_____
XmNpopupCursorXmCCursorCursorleft_ptrCSG
_____
XmNpopupOffsetMxCPopupOffsetint15CSG
_____
XmNpopupShellWidgetXmCWidgetWidgetNULLCSG
_____
XmNshowLabelXmCBooleanBooleanTrueCSG
_____
XmNupdateShellCallbackXmCCallbackXtCallbackListNULLCSG
_____
XmNupdateTextCallbackXmCCallbackXtCallbackListNULLCSG
_____
XmNuseTextFieldXmCUseTextFieldBooleanTrueCSG
_____
XmNvaluetextString""CSG
_____
XmNverifyXmCVerifyBooleanTrueCSG
_____
XmNverifyTextCallbackXmCCallbackXtCallbackListNULLCSG
_____
XmNverticalMarginXmCMarginDimension2CSG
_____
XmNvisibleItemCountXmCVisibleItemCountint0CSG
_____
.TE
.IP "\fBXmNcustomizedCombinationBox\fP" 10
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. 
.IP "\fBXmNeditable\fP" 10
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
.IP "\fBXmNhorizontalMargin\fP" 10
Specifies the horizontal spacing between the child widgets and the boundary
of the DropDown widget\&.
.IP "\fBXmNverticalMargin\fP" 10
Specifies the vertical spacing between the child widgets and the boundary
of the DropDown widget\&.
.IP "\fBXmNitemCount\fP" 10
The number of items in the popup list.
.IP "\fBXmNitems\fP" 10
The list of all choice that will be displayed in the popup list.
.IP "\fBXmNlabelString\fP" 10
The string displayed as the label of the DropDown widget.
.IP "\fBXmNpopupCursor\fP" 10
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.
.IP "\fBXmNpopupOffset\fP" 10
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.
.IP "\fBXmNpopupShellWidget\fP" 10
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.
.IP "\fBXmNshowLabel\fP" 10
A boolean value that specifies whether or not to display the DropDown 
Label widget.
.IP "\fBXmNupdateShellCallback\fP" 10
.IP "\fBXmNupdateTextCallback\fP" 10
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.
.IP "\fBXmNuseTextField\fP" 10
A boolean value that specifies if an XmTextField or an XmText widget
should be used for the text entry portion of the DropDown widget.
.IP "\fBXmNvalue\fP" 10
The string displayed in the Text widget.
.IP "\fBXmNverify\fP" 10
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.
.IP "\fBXmNverifyTextCallback\fP" 10
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.
.IP "\fBXmNvisibleItemCount\fP" 10
The number of items visible in the popup list at one time.
.RE
.SS Children
.PP
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.
.PP
.ta 18n 35n 40n 50n
.df


XmDropDown	comboBox

	XmLabel	label

	XmTextField	text

	XmArrowButton	arrow

	OverrideShell	popupShell

	XmScrolledWindow	listSW

		XmScrollBar	ListvScrollBar

		XmScrollBar	ListhScrollBar

		XmList	list
.fi

The popup shell and its children are only created when 
customizedCombinationBox is False.
.PP
.SS "Inherited Resources"
.PP
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\&.
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBXmManager Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNbottomShadowColorXmCBottomShadowColorPixeldynamicCSG
_____
XmNbottomShadowPixmapXmCBottomShadowPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNforegroundXmCForegroundPixeldynamicCSG
_____
XmNhelpCallbackXmCCallbackXtCallbackListNULLC
_____
XmNhighlightColorXmCHighlightColorPixeldynamicCSG
_____
XmNhighlightPixmapXmCHighlightPixmapPixmapdynamicCSG
_____
XmNinitialFocusXmCInitialFocusWidgetNULLCSG
_____
XmNlayoutDirectionXmCLayoutDirectionXmDirectiondynamicCG
_____
XmNnavigationTypeXmCNavigationTypeXmNavigationTypeXmTAB_GROUPCSG
_____
XmNpopupHandlerCallbackXmCCallbackXtCallbackListNULLC
_____
XmNshadowThicknessXmCShadowThicknessDimension0CSG
_____
XmNstringDirectionXmCStringDirectionXmStringDirectiondynamicCG
_____
XmNtopShadowColorXmCTopShadowColorPixeldynamicCSG
_____
XmNtopShadowPixmapXmCTopShadowPixmapPixmapdynamicCSG
_____
XmNtraversalOnXmCTraversalOnBooleanTrueCSG
_____
XmNunitTypeXmCUnitTypeunsigned chardynamicCSG
_____
XmNuserDataXmCUserDataXtPointerNULLCSG
_____
.TE
.PP
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBComposite Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNchildrenXmCReadOnlyWidgetListNULLG
_____
XmNinsertPositionXmCInsertPositionXtOrderProcNULLCSG
_____
XmNnumChildrenXmCReadOnlyCardinal0G
_____
.TE
.TS
tab() box;
c s s s s
l| l| l| l| l.
\fBCore Resource Set\fP
\fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP
_____
XmNacceleratorsXmCAcceleratorsXtAcceleratorsdynamicCSG
_____
XmNancestorSensitiveXmCSensitiveBooleandynamicG
_____
XmNbackgroundXmCBackgroundPixeldynamicCSG
_____
XmNbackgroundPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNborderColorXmCBorderColorPixelXtDefaultForegroundCSG
_____
XmNborderPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
_____
XmNborderWidthXmCBorderWidthDimension0CSG
_____
XmNcolormapXmCColormapColormapdynamicCG
_____
XmNdepthXmCDepthintdynamicCG
_____
XmNdestroyCallbackXmCCallbackXtCallbackListNULLC
_____
XmNheightXmCHeightDimensiondynamicCSG
_____
XmNinitialResourcesPersistentXmCInitialResourcesPersistentBooleanTrueC
_____
XmNmappedWhenManagedXmCMappedWhenManagedBooleanTrueCSG
_____
XmNscreenXmCScreenScreen *dynamicCG
_____
XmNsensitiveXmCSensitiveBooleanTrueCSG
_____
XmNtranslationsXmCTranslationsXtTranslationsdynamicCSG
_____
XmNwidthXmCWidthDimensiondynamicCSG
_____
XmNxXmCPositionPosition0CSG
_____
XmNyXmCPositionPosition0CSG
_____
.TE
.SS "Callback Information"
.PP
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.
.HP 20
void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)
.ta 15
.HP 15
cbw		This is the widget identifier of the DropDown widget.
.PP
.HP 15
client_data		The client data passed to this widget by the application programmer.
.HP 15
unused		This value is undefined.
.PP
.SS "Geometry Management"
.PP
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:
.ta 5
.HP 5
1.	The arrow is always given its requested size.
.HP 5
2.	If the combo box is bigger than it wants to be all extra space is given to the text 
widget.
.HP 5
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.
.PP
.SH RELATED
.PP
\fBComposite\fP(3),
\fBCore\fP(3),
\fBXmCreateDropDown\fP(3),
\fBXmDropDownGetArrow\fP(3),
\fBXmDropDownGetLabel\fP(3),
\fBXmDropDownGetList\fP(3),
\fBXmDropDownGetText\fP(3),
\fBXmDropDownGetValue\fP(3),
\fBXmList\fP(3),
\fBXmManager\fP(3),
\fBXmTextField\fP(3),
\fBXmVaCreateDropDown\fP(3), and
\fBXmVaCreateManagedDropDown\fP(3)\&.
.PP
.SH COPYRIGHT
.PP
Copyright (c) 1992 by Integrated Computer Solutions, Inc.