Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmDropDown(3)		   Library Functions Manual		 XmDropDown(3)

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 Se-
       lect 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  ar-
       row.  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  con-
       tents 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,  Compos-
       ite, 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 pro-
       grammer to specify data.	The programmer can also	set the	resource  val-
       ues  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 automati-
		 cally 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  re-
		 source	 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 far-
		 ther 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 au-
		 tomatically 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 Drop-
		 Down 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 rou-
		 tine 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 re-
       quests must be made on a	child by child	basis.	The  children  of  the
       DropDown	 are  listed  below. The OSF/Motifdocumentation	should be con-
       sulted 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 customizedCombi-
       nationBox is False.

   Inherited Resources
       XmDropDown inherits behavior and	resources from	the  superclasses  de-
       scribed	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 SetName			      |	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	 Drop-
       Down 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	 what-
	    ever size the child	of the popup shell would like to be.

RELATED
       Composite(3),  Core(3), XmCreateDropDown(3), XmDropDownGetArrow(3), Xm-
       DropDownGetLabel(3),  XmDropDownGetList(3),  XmDropDownGetText(3),  Xm-
       DropDownGetValue(3),  XmList(3),	XmManager(3), XmTextField(3), XmVaCre-
       ateDropDown(3), and XmVaCreateManagedDropDown(3).

COPYRIGHT
       Copyright (c) 1992 by Integrated	Computer Solutions, Inc.

								 XmDropDown(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmDropDown&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help