NAME

XmDropDown — 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.

Composite(3), Core(3), XmCreateDropDown(3), XmDropDownGetArrow(3), XmDropDownGetLabel(3), XmDropDownGetList(3), XmDropDownGetText(3), XmDropDownGetValue(3), XmList(3), XmManager(3), XmTextField(3), XmVaCreateDropDown(3), and XmVaCreateManagedDropDown(3).