1XmDropDown(library call) XmDropDown(library call)
2
6 XmDropDown — The DropDown widget class
7
9 #include <Xm/DropDown.h>
10
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 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 If a developer wishes the popup list's shell to be resizable, they
41 should set the allowShellResize to True at creation time.
42 Classes
44 XmDropDown inherits behavior, resources, and traits from Core, Compos‐
45 ite, and XmManager classes.
46 The class pointer is xmDropDownWidgetClass.
48 The class name is XmDropDown.
50 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 ┌───────────────────────────────────────────────────────────────────────────────────────┐
65 │ │ XmDropDown Resource│Set │ │ │
66 │Name │ 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 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 XmNhorizontalMargin
125 Specifies the horizontal spacing between the child widgets
126 and the boundary of the DropDown widget.
127 XmNverticalMargin
129 Specifies the vertical spacing between the child widgets and
130 the boundary of the DropDown widget.
131 XmNitemCount
133 The number of items in the popup list.
134 XmNitems The list of all choice that will be displayed in the popup
136 list.
137 XmNlabelString
139 The string displayed as the label of the DropDown widget.
140 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 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 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 XmNshowLabel
162 A boolean value that specifies whether or not to display the
163 DropDown Label widget.
164 XmNupdateShellCallback
166 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 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 XmNvalue The string displayed in the Text widget.
183 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 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 XmNvisibleItemCount
198 The number of items visible in the popup list at one time.
199 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 XmDropDown comboBox
211 XmLabel label
213 XmTextField text
215 XmArrowButton arrow
217 OverrideShell popupShell
219 XmScrolledWindow listSW
221 XmScrollBar ListvScrollBar
223 XmScrollBar ListhScrollBar
225 XmList list
227 The popup shell and its children are only created when customizedCombi‐
229 nationBox is False.
230 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 ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
237 │ │ XmManager │Resource Set │ │ │
238 │Name │ 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 │ │ │
277 │Name │ 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 │ │ │
288 │Name │ 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 void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)
335 cbw This is the widget identifier of the DropDown widget.
337 client_data The client data passed to this widget by the application
339 programmer.
340 unused This value is undefined.
342 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 1. The arrow is always given its requested size.
350 2. If the combo box is bigger than it wants to be all extra space is
352 given to the text widget.
353 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 For example:
359 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 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 XmDropDown(library call)