1XmDropDown(library call)                              XmDropDown(library call)
2
3
4

NAME

6       XmDropDown — The DropDown widget class
7

SYNOPSIS

9       #include <Xm/DropDown.h>
10

DESCRIPTION

12       The  DropDown  widget allows the user to select elements from a list of
13       choices, and enter their own values  in  a  text  widget.  To  conserve
14       screen  space,  the list of choices is shown only when the user selects
15       the down arrow button. The choices may then be selected from this list.
16       If  the  list  widget  is in Browse Select mode (the default) or Single
17       Select mode, then the list will automatically be removed when the  user
18       selects  an item in the list. When the list is in other modes, multiple
19       items may be selected and the list may be popped down by either another
20       click  on the arrow button, a click outside the list or double-clicking
21       an item. When using keyboard traversal, the list may be popped down  by
22       selecting  the  arrow button or Alt - down arrow, and popped back up by
23       typing either the osfActivate key, a  carriage  return,  or  Alt  -  up
24       arrow.  In  any  case,  when the list is removed the item or items that
25       were selected will be placed in the text widget  separated  by  commas.
26       Typing  the  escape  key  when  the list is up, cancels the list popup,
27       restoring the DropDown widget to the state it was in  before  the  list
28       was  popped  up.  If the text field area is non-editable, clicking any‐
29       where in the text field the list will also pop down.
30
31       Resources are available to change the margin sizes, the location of the
32       left edge of the popup list, whether or not the label is shown, whether
33       the text field widget may be edited, and whether or not the text in the
34       list  is verified against the choices available in the list. By setting
35       resources that occur in the children of the DropDown widget,  the  con‐
36       tents of the list, the number of items visible in the list, the initial
37       value of the text field, and the value of  the  label  may  be  set  or
38       changed dynamically.
39
40       If  a  developer  wishes  the  popup list's shell to be resizable, they
41       should set the allowShellResize to True at creation time.
42
43   Classes
44       XmDropDown inherits behavior, resources, and traits from Core,  Compos‐
45       ite, and XmManager classes.
46
47       The class pointer is xmDropDownWidgetClass.
48
49       The class name is XmDropDown.
50
51   New Resources
52       The  following table defines a set of widget resources used by the pro‐
53       grammer to specify data. The programmer can also set the resource  val‐
54       ues  for  the  inherited  classes to set attributes for this widget. To
55       reference a resource by name or by class in a .Xdefaults  file,  remove
56       the  XmN or XmC prefix and use the remaining letters. To specify one of
57       the defined values for a resource in a .Xdefaults file, remove  the  Xm
58       prefix and use the remaining letters (in either lowercase or uppercase,
59       but include any underscores between words). The  codes  in  the  access
60       column  indicate if the given resource can be at creation time (C), set
61       by using XtSetValues (S), retrieved by using XtGetValues (G), or is not
62       applicable (N/A).
63
64       ┌───────────────────────────────────────────────────────────────────────────────────────┐
65       │                            │  XmDropDown ResourceSet             │          │        │
66Name                        Class               Type           Default  Access 
67       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
68       │XmNcustomizedCombinationBox │ XmCBoolean          │ Boolean        │ False    │ CSG    │
69       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
70       │XmNeditable                 │ XmCBoolean          │ Boolean        │ True     │ CSG    │
71       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
72       │XmNhorizontalMargin         │ XmCMargin           │ Dimension      │ 2        │ CSG    │
73       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
74       │XmNitemCount                │ list                │ int            │ 0        │ CSG    │
75       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
76       │XmNitems                    │ list                │ XmStringTable  │ NULL     │ CSG    │
77       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
78       │XmNlabelString              │ label               │ XmString       │ "label"  │ CSG    │
79       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
80       │XmNpopupCursor              │ XmCCursor           │ Cursor         │ left_ptr │ CSG    │
81       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
82       │XmNpopupOffset              │ MxCPopupOffset      │ int            │ 15       │ CSG    │
83       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
84       │XmNpopupShellWidget         │ XmCWidget           │ Widget         │ NULL     │ CSG    │
85       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
86       │XmNshowLabel                │ XmCBoolean          │ Boolean        │ True     │ CSG    │
87       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
88       │XmNupdateShellCallback      │ XmCCallback         │ XtCallbackList │ NULL     │ CSG    │
89       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
90       │XmNupdateTextCallback       │ XmCCallback         │ XtCallbackList │ NULL     │ CSG    │
91       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
92       │XmNuseTextField             │ XmCUseTextField     │ Boolean        │ True     │ CSG    │
93       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
94       │XmNvalue                    │ text                │ String         │ ""       │ CSG    │
95       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
96       │XmNverify                   │ XmCVerify           │ Boolean        │ True     │ CSG    │
97       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
98       │XmNverifyTextCallback       │ XmCCallback         │ XtCallbackList │ NULL     │ CSG    │
99       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
100       │XmNverticalMargin           │ XmCMargin           │ Dimension      │ 2        │ CSG    │
101       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
102       │XmNvisibleItemCount         │ XmCVisibleItemCount │ int            │ 0        │ CSG    │
103       ├────────────────────────────┼─────────────────────┼────────────────┼──────────┼────────┤
104       └────────────────────────────┴─────────────────────┴────────────────┴──────────┴────────┘
105       XmNcustomizedCombinationBox
106                 If  this  resource is True then the widget will not automati‐
107                 cally create a popup shell and list widget. This resource can
108                 be  used, as the name implies, to create a custom combination
109                 box that has something other than  a  list  in  it.  If  this
110                 resource  is  true then a shell must be provided to the Drop‐
111                 Down widget via the popupShellWidget  resource.  Just  before
112                 the  shell  is  popped  up the updateShellCallback is called.
113                 Just after the shell is popped down the updateTextCallback is
114                 called.  If  verify  is  true  then the verifyTextCallback is
115                 called when the combo box needs to verify the contents of the
116                 text widget against the allowable values in the custom shell.
117
118       XmNeditable
119                 This  boolean value determines whether the user is allowed to
120                 type into TextField widget of the DropDown  widget.  If  this
121                 value is False, selecting the text field will popup the combo
122                 box list
123
124       XmNhorizontalMargin
125                 Specifies the horizontal spacing between  the  child  widgets
126                 and the boundary of the DropDown widget.
127
128       XmNverticalMargin
129                 Specifies  the vertical spacing between the child widgets and
130                 the boundary of the DropDown widget.
131
132       XmNitemCount
133                 The number of items in the popup list.
134
135       XmNitems  The list of all choice that will be displayed  in  the  popup
136                 list.
137
138       XmNlabelString
139                 The string displayed as the label of the DropDown widget.
140
141       XmNpopupCursor
142                 The cursor to display to the user when the DropDown's list is
143                 popped up.  See X Window System, Robert  Scheiffler  et  al.,
144                 Appendix B, for choices.
145
146       XmNpopupOffset
147                 The  amount  of  space in pixels between the left edge of the
148                 Text widget and the left edge of the list when  the  list  is
149                 displayed.  Positive values mean the text's left edge is far‐
150                 ther to the left, negative values mean  the  list's  edge  is
151                 farther  to the left. If this is a non-custom DropDown widget
152                 the right edge of the text and the right edge  of  the  arrow
153                 button will always line up.
154
155       XmNpopupShellWidget
156                 The  widget  identifier  for the shell that is popped up when
157                 the arrow is clicked. If  customizedCombinationBox  is  False
158                 then  this  widget  is  automatically created by the DropDown
159                 widget.
160
161       XmNshowLabel
162                 A boolean value that specifies whether or not to display  the
163                 DropDown Label widget.
164
165       XmNupdateShellCallback
166
167       XmNupdateTextCallback
168                 The  callback  routine  to  call when either the shell widget
169                 contents or the Text widget need to be updated to  correspond
170                 with the other. The shell is updated just before it is popped
171                 up. The text is updated just after the shell is popped  down.
172                 If  customizedComboBox  is  False  then  the updates are done
173                 automatically by the combo box. These routines are called  to
174                 inform the application that an action has been taken, in case
175                 it would like to do any further processing.
176
177       XmNuseTextField
178                 A boolean value that specifies if an XmTextField or an XmText
179                 widget should be used for the text entry portion of the Drop‐
180                 Down widget.
181
182       XmNvalue  The string displayed in the Text widget.
183
184       XmNverify If this resource is true the DropDown widget will verify  its
185                 value  against  the  list whenever it loses focus or the user
186                 types  <Carriage  Return>.  If  the  verification  fails,  an
187                 XtWarning is generated with a name of XmNtextVerifyFailed. To
188                 trap this message register an XtWarningMsgHandler.
189
190       XmNverifyTextCallback
191                 This routine is called whenever the  Text  widget's  contents
192                 may  need  to be verified against the popup shell's contents.
193                 If the customizedComboBox resource is False then the DropDown
194                 widget  has already performed the verification when this rou‐
195                 tine is called.
196
197       XmNvisibleItemCount
198                 The number of items visible in the popup list at one time.
199
200   Children
201       The DropDown is composed of many sub-widgets. Most of  the  information
202       displayed  to  the  user  is set through these sub widgets. Most values
203       passed to this widget through the argument list at creation time or via
204       set  values  are  passed  to each of this widget's children. Get values
205       requests must be made on a child by child basis. The  children  of  the
206       DropDown  are  listed  below. The OSF/Motifdocumentation should be con‐
207       sulted for an exhaustive set of resources for each  child.   A  partial
208       list of the most common resources are listed here for convenience.
209
210       XmDropDown        comboBox
211
212                         XmLabel          label
213
214                         XmTextField      text
215
216                         XmArrowButton    arrow
217
218                         OverrideShell    popupShell
219
220                         XmScrolledWindow listSW
221
222                                          XmScrollBar    ListvScrollBar
223
224                                          XmScrollBar    ListhScrollBar
225
226                                          XmList         list
227
228       The popup shell and its children are only created when customizedCombi‐
229       nationBox is False.
230
231   Inherited Resources
232       XmDropDown  inherits  behavior  and  resources  from  the  superclasses
233       described  in the following tables.  For a complete description of each
234       resource, refer to the reference page for that superclass.
235
236       ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
237       │                        │             XmManager │Resource Set        │                      │        │
238Name                    Class                 Type              Default              Access 
239       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
240       │XmNbottomShadowColor    │ XmCBottomShadowColor  │ Pixel             │ dynamic              │ CSG    │
241       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
242       │XmNbottomShadowPixmap   │ XmCBottomShadowPixmap │ Pixmap            │ XmUNSPECIFIED_PIXMAP │ CSG    │
243       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
244       │XmNforeground           │ XmCForeground         │ Pixel             │ dynamic              │ CSG    │
245       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
246       │XmNhelpCallback         │ XmCCallback           │ XtCallbackList    │ NULL                 │ C      │
247       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
248       │XmNhighlightColor       │ XmCHighlightColor     │ Pixel             │ dynamic              │ CSG    │
249       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
250       │XmNhighlightPixmap      │ XmCHighlightPixmap    │ Pixmap            │ dynamic              │ CSG    │
251       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
252       │XmNinitialFocus         │ XmCInitialFocus       │ Widget            │ NULL                 │ CSG    │
253       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
254       │XmNlayoutDirection      │ XmCLayoutDirection    │ XmDirection       │ dynamic              │ CG     │
255       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
256       │XmNnavigationType       │ XmCNavigationType     │ XmNavigationType  │ XmTAB_GROUP          │ CSG    │
257       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
258       │XmNpopupHandlerCallback │ XmCCallback           │ XtCallbackList    │ NULL                 │ C      │
259       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
260       │XmNshadowThickness      │ XmCShadowThickness    │ Dimension         │ 0                    │ CSG    │
261       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
262       │XmNstringDirection      │ XmCStringDirection    │ XmStringDirection │ dynamic              │ CG     │
263       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
264       │XmNtopShadowColor       │ XmCTopShadowColor     │ Pixel             │ dynamic              │ CSG    │
265       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
266       │XmNtopShadowPixmap      │ XmCTopShadowPixmap    │ Pixmap            │ dynamic              │ CSG    │
267       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
268       │XmNtraversalOn          │ XmCTraversalOn        │ Boolean           │ True                 │ CSG    │
269       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
270       │XmNunitType             │ XmCUnitType           │ unsigned char     │ dynamic              │ CSG    │
271       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
272       │XmNuserData             │ XmCUserData           │ XtPointer         │ NULL                 │ CSG    │
273       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
274       └────────────────────────┴───────────────────────┴───────────────────┴──────────────────────┴────────┘
275       ┌───────────────────────────────────────────────────────────────────────┐
276       │                  │     Composite Reso│urce Set      │         │        │
277Name              Class             Type        Default Access 
278       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
279       │XmNchildren       │ XmCReadOnly       │ WidgetList  │ NULL    │ G      │
280       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
281       │XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL    │ CSG    │
282       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
283       │XmNnumChildren    │ XmCReadOnly       │ Cardinal    │ 0       │ G      │
284       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
285       └──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
286       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
287       │                              │               Core Resource Se│t                │                      │        │
288Name                          Class                         Type           Default              Access 
289       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
290       │XmNaccelerators               │ XmCAccelerators               │ XtAccelerators │ dynamic              │ CSG    │
291       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
292       │XmNancestorSensitive          │ XmCSensitive                  │ Boolean        │ dynamic              │ G      │
293       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
294       │XmNbackground                 │ XmCBackground                 │ Pixel          │ dynamic              │ CSG    │
295       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
296       │XmNbackgroundPixmap           │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
297       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
298       │XmNborderColor                │ XmCBorderColor                │ Pixel          │ XtDefaultForeground  │ CSG    │
299       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
300       │XmNborderPixmap               │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
301       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
302       │XmNborderWidth                │ XmCBorderWidth                │ Dimension      │ 0                    │ CSG    │
303       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
304       │XmNcolormap                   │ XmCColormap                   │ Colormap       │ dynamic              │ CG     │
305       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
306       │XmNdepth                      │ XmCDepth                      │ int            │ dynamic              │ CG     │
307       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
308       │XmNdestroyCallback            │ XmCCallback                   │ XtCallbackList │ NULL                 │ C      │
309       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
310       │XmNheight                     │ XmCHeight                     │ Dimension      │ dynamic              │ CSG    │
311       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
312       │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean        │ True                 │ C      │
313       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
314       │XmNmappedWhenManaged          │ XmCMappedWhenManaged          │ Boolean        │ True                 │ CSG    │
315       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
316       │XmNscreen                     │ XmCScreen                     │ Screen *       │ dynamic              │ CG     │
317       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
318       │XmNsensitive                  │ XmCSensitive                  │ Boolean        │ True                 │ CSG    │
319       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
320       │XmNtranslations               │ XmCTranslations               │ XtTranslations │ dynamic              │ CSG    │
321       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
322       │XmNwidth                      │ XmCWidth                      │ Dimension      │ dynamic              │ CSG    │
323       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
324       │XmNx                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
325       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
326       │XmNy                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
327       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
328       └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
329   Callback Information
330       None of the DropDown's callback procedures have any call data currently
331       defined  for  them. The widget passed to each of these functions is the
332       DropDown widget.
333
334       void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)
335
336       cbw            This is the widget identifier of the DropDown widget.
337
338       client_data    The client data passed to this widget by the application
339                      programmer.
340
341       unused         This value is undefined.
342
343   Geometry Management
344       The  DropDown  widget lays out its children (the label, text and arrow)
345       in a row.  The amount of space they are each allocated when  the  Drop‐
346       Down is not allowed to be the exact size it desires is determined using
347       the following rules:
348
349       1.   The arrow is always given its requested size.
350
351       2.   If the combo box is bigger than it wants to be all extra space  is
352            given to the text widget.
353
354       3.   If  the combo box is smaller that is wants to be then the text and
355            label widgets are each sized smaller than they desire  in  exactly
356            the same ratio.
357
358            For example:
359
360            If  the  amount  of space for the label and text is 100 pixels and
361            the label wants to be 50 pixels wide and the text would like to be
362            100 pixels wide then the label will get 34 pixels and the text 66.
363
364            The  popup  shell  widget  is  sized  such  that  the width of the
365            scrolled list widget equals the width of the text widget minus the
366            value of the "popupOffset" resource. If the popup shell resides in
367            a customized combination box, however, it is allowed to  be  what‐
368            ever size the child of the popup shell would like to be.
369
371       Composite(3),   Core(3),   XmCreateDropDown(3),  XmDropDownGetArrow(3),
372       XmDropDownGetLabel(3),   XmDropDownGetList(3),    XmDropDownGetText(3),
373       XmDropDownGetValue(3),    XmList(3),    XmManager(3),   XmTextField(3),
374       XmVaCreateDropDown(3), and XmVaCreateManagedDropDown(3).
375
377       Copyright (c) 1992 by Integrated Computer Solutions, Inc.
378
379
380
381                                                      XmDropDown(library call)
Impressum