1XmComboBox(library call) XmComboBox(library call)
2
6 XmComboBox — The ComboBox widget class
7
9 #include <Xm/ComboBox.h>
10
12 XmComboBox combines the capabilities of a single-line TextField widget
13 and a List widget. It allows users to perform opoerations like typing
14 and pasting information, and it also provides a list of possible
15 choices that the user can select from to complete the TextField entry
16 field. The list can either be displayed at all times or can be dropped
17 down by the user. When the list portion of the ComboBox is hidden,
18 users are given a visual cue (a downward-pointing arrow) next to the
19 TextField field. The position of the arrow relative to the TextField
20 field depends on the XmNlayoutDirection resource of the widget. This
21 version of the ComboBox is called the "drop-down" ComboBox. Drop-down
22 ComboBoxes are useful when screen space is limited, or when users will
23 complete the text entry field more often by typing text than by select‐
24 ing the entry field text from the list. The user can access the drop-
25 down ComboBox in either one of two ways:
26 · By clicking and releasing <Btn1> on the downward-pointing arrow,
28 which pops the list up, and the list stays up. A later selection
29 of an item in the list will cause the item to appear in the text
30 entry field, and the list will unpost itself.
31 · By pressing <Btn1> on the downward-pointing arrow, dragging it to
33 a list item, and then releasing it there, which selects that
34 item. The list disappears, and the selected item appears in the
35 text entry field.
36 The application provides an array of strings that fill the list. At
38 creation time, string items can be passed to the ComboBox via an
39 arglist. Each string becomes an item in the list, with the first
40 string becoming the item in position 1, the second string becoming the
41 item in position 2, and so on. The size of the list is set by specify‐
42 ing the number of items that are visible in the list (XmNvisibleItem‐
43 Count). If the number of items in the list exceeds the number of items
44 that are visible, a vertical scroll bar will automatically appear that
45 allows the user to scroll through a large number of items.
46 ComboBox creates two child widgets: a TextField widget for entering
48 text and a ScrolledWindow containing a List for the list of items. The
49 name of the items list itself is List, and the name of the TextField is
50 Text. The application or user can specify resource values for these
51 widgets in a resource file, and the application can use XtNameToWidget
52 (specifying "*List" for the items list or "*Text" for the TextField
53 widget) to obtain the widget IDs of the descendant widgets. At cre‐
54 ation time, ComboBox passes appropriate resource values in the creation
55 arglist, including XmNitems, to the items list. Note that the result
56 of providing the XmNdestroyCallback resource in the creation arglist is
57 unspecified. The application should use the XtAddCallback function to
58 add callbacks to the appropriate widget (TextField or List) after cre‐
59 ating it.
60 ComboBox forces the following resource values on its List child:
62 · If XmNcomboBoxType is XmCOMBO_BOX, XmNtraversalOn is forced to
64 False.
65 · XmNhighlightThickness is forced to 2 in a drop-down ComboBox and
67 to 0 in other types of ComboBoxes.
68 · XmNborderWidth is forced to 0.
70 · XmNnavigationType is forced to XmNONE.
72 · XmNselectionPolicy is forced to XmBROWSE_SELECT.
74 · XmNlistSizePolicy is forced to XmVARIABLE.
76 · XmNspacing is forced to 0.
78 · XmNvisualPolicy is forced to XmVARIABLE.
80 · XmNselectedPositions is forced to NULL.
82 · XmNselectedPositionsCount is forced to 0.
84 When XmNcomboBoxType is XmDROP_DOWN_LIST, ComboBox forces the following
86 resource values on its TextField child:
87 · XmNeditable is forced to False.
89 · XmNcursorPositionVisible is forced to False.
91 · XmNshadowThickness is forced to 0.
93 By contrast, when XmNcomboBoxType is XmCOMBO_BOX or
95 XmDROP_DOWN_COMBO_BOX, ComboBox forces the following resource values on
96 its TextField child:
97 · XmNeditable is forced to True.
99 · XmNcursorPositionVisible is forced to True.
101 · XmNeditMode is forced to XmSINGLE_LINE_EDIT.
103 ComboBox always forces the values of the following resources on the
105 TextField:
106 · XmNnavigationType is forced to XmNONE.
108 · XmNhighlightThickness is forced to 0.
110 · XmNborderWidth is forced to 0.
112 ComboBox allows a single item to be selected in two ways: by selecting
114 the desired item from the List or by entering text into the TextField.
115 ComboBox does not automatically select a list item if the user types
116 that string into the TextField. It selects the item when the user
117 presses KActivate or moves the focus. ComboBox supports the Browse
118 Select selection model of List (see the XmList reference page for a
119 description of this model), so selections are mutually exclusive.
120 Selecting an item from the list causes that item to be displayed in the
121 TextField portion of the ComboBox. If an application sets the XmNvalue
122 resource of TextField, that string is shown in the TextField. If the
123 application has not provided any list items, or if there is no current
124 selection, the TextField is empty.
125 The TextField in the ComboBox widget can be either editable or noned‐
127 itable, depending on the value of the XmNcomboBoxType resource.
128 If the TextField is editable, the user can type into it. When the user
130 presses the Return key, the ComboBox will compare the typed entry to
131 the items in the List. If there is an exact match, then the matched
132 List item is selected. If the application wishes to validate the
133 entered text (for example, to ensure that the typed selection is a
134 valid one), it can do so by setting XmNmodifyVerifyCallback on the
135 TextField widget.
136 If the TextField is noneditable, typing text may invoke a matching
138 algorithm that will attempt to match the entered text with items in the
139 list. The specific matching algorithm applied, which may be none, is
140 determined by the value of the XmNmatchBehavior resource in ComboBox,
141 which can be either XmNONE or XmQUICK_NAVIGATE. A value of XmNONE indi‐
142 cates that no matching algorithm will occur. A value of XmQUICK_NAVI‐
143 GATE indicates that when the List widget has focus, one-character navi‐
144 gation is supported. In this algorithm, if the typed character is the
145 initial character of some item in the List, this algorithm causes that
146 item to be navigated to and selected, and the item is displayed in the
147 TextField. Subsequently typing the same character will cycle among the
148 items with the same first character.
149 Regardless of the selection mechanism used (either selected directly
151 from the List or typed into the TextField), when an item in the List is
152 selected, that item is highlighted in the List. In addition, the
153 selected item is displayed in the TextField of the ComboBox. If the
154 user performs an action that would move focus away from ComboBox, or
155 selects a List item, the XmNselectionCallback callbacks are invoked to
156 notify the application of the current contents of the TextField (or
157 choice). The application then takes whatever action is required based
158 on those contents (or choice).
159 ComboBox uses the XmQTspecifyRenderTable trait and holds the XmQTac‐
161 cessTextual trait.
162 Classes
164 XmComboBox inherits behavior, resources, and traits from Core, Compos‐
165 ite, and XmManager classes.
166 The class pointer is xmComboBoxWidgetClass.
168 The class name is XmComboBox.
170 New Resources
172 The following table defines a set of widget resources used by the pro‐
173 grammer to specify data. The programmer can also set the resource val‐
174 ues for the inherited classes to set attributes for this widget. To
175 reference a resource by name or by class in a .Xdefaults file, remove
176 the XmN or XmC prefix and use the remaining letters. To specify one of
177 the defined values for a resource in a .Xdefaults file, remove the Xm
178 prefix and use the remaining letters (in either lowercase or uppercase,
179 but include any underscores between words). The codes in the access
180 column indicate if the given resource can be at creation time (C), set
181 by using XtSetValues (S), retrieved by using XtGetValues (G), or is not
182 applicable (N/A).
183 ┌───────────────────────────────────────────────────────────────────────────────────────┐
185 │ │ XmComboBox Reso│urce Set │ │ │
186 │Name │ Class │ Type │ Default │ Access │
187 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
188 │XmNarrowSize │ XmCArrowSize │ Dimension │ dynamic │ CSG │
189 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
190 │XmNarrowSpacing │ XmCArrowSpacing │ Dimension │ dynamic │ CSG │
191 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
192 │XmNcolumns │ XmCColumn │ short │ dynamic │ CSG │
193 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
194 │XmNcomboBoxType │ XmCComboBoxType │ unsigned char │ XmCOMBO_BOX │ CG │
195 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
196 │XmNfontList │ XmCFontList │ XmFontList │ NULL │ CSG │
197 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
198 │XmNhighlightThickness │ XmCHighlightThickness │ Dimension │ 2 │ CSG │
199 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
200 │XmNitemCount │ XmCItemCount │ int │ dynamic │ CSG │
201 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
202 │XmNitems │ XmCItems │ XmStringTable │ dynamic │ CSG │
203 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
204 │XmNlist │ XmCList │ Widget │ dynamic │ G │
205 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
206 │XmNmarginHeight │ XmCMarginHeight │ Dimension │ 2 │ CSG │
207 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
208 │XmNmarginWidth │ XmCMarginWidth │ Dimension │ 2 │ CSG │
209 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
210 │XmNmatchBehavior │ XmCMatchBehavior │ unsigned char │ dynamic │ CSG │
211 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
212 │XmNpositionMode │ XmCPositionMode │ XtEnum │ XmZERO_BASED │ CG │
213 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
214 │XmNrenderTable │ XmCRenderTable │ XmRenderTable │ dynamic │ CSG │
215 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
216 │XmNselectedItem │ XmCSelectedItem │ XmString │ NULL │ CSG │
217 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
218 │XmNselectedPosition │ XmCSelectedPosition │ int │ dynamic │ CSG │
219 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
220 │XmNselectionCallback │ XmCCallback │ XmCallbackList │ NULL │ C │
221 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
222 │XmtextField │ XmCTextField │ Widget │ dynamic │ G │
223 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
224 │XmNvisibleItemCount │ XmCVisibleItemCount │ int │ 10 │ CSG │
225 ├──────────────────────┼───────────────────────┼────────────────┼──────────────┼────────┤
226 └──────────────────────┴───────────────────────┴────────────────┴──────────────┴────────┘
227 XmNarrowSize
228 Specifies the width of the arrow. The default size depends on
229 the size of the text, as well as the size of the ComboBox.
230 XmNarrowSpacing
232 Specifies the space between the text and arrow visual in pix‐
233 els. The default value is obtained from the XmNmarginWidth
234 resource.
235 XmNcolumns
237 Specifies the number of columns in the text field. If unset,
238 the text field's value is used. Refer to the XmTextField man
239 page for more detailed information.
240 XmNcomboBoxType
242 Specifies the type of ComboBox to be created. This can be one
243 of the following:
244 XmCOMBO_BOX
246 Generates a ComboBox where the list is always dis‐
247 played, and the text entry field is editable.
248 XmDROP_DOWN_COMBO_BOX
250 Generates a ComboBox where the list is hidden
251 unless specifically requested, and the text entry
252 field is editable.
253 XmDROP_DOWN_LIST
255 Generates a ComboBox where the list is hidden
256 unless specifically requested, and the text entry
257 field is noneditable.
258 XmNfontList
260 Specifies the fontlist associated with XmComboBox. The
261 fontlist is an obsolete construct, and has been superseded by
262 the render table. It is included for compatibility with ear‐
263 lier versions of Motif, and for applications that do not eas‐
264 ily support render tables. The default fontlist is derived
265 from the default render table, and if both a fontlist and a
266 render table are specified, the render table takes prece‐
267 dence.
268 XmNhighlightThickness
270 Specifies the thickness of the highlighting rectangle.
271 XmNitemCount
273 Specifies the number of items in the list. If unset, the
274 lists's value is used. Refer to the XmList man page for more
275 detailed information.
276 XmNitems Specifies the items in the list. If unset, the lists's value
278 is used. Refer to the XmList man page for more detailed
279 information.
280 XmNlist The list widget.
282 XmNmarginWidth
284 Specifies the horizontal spacing between the child widgets
285 and the boundary of the ComboBox.
286 XmNmarginHeight
288 Specifies the vertical spacing between the child widgets and
289 the boundary of the ComboBox.
290 XmNmatchBehavior
292 Defines the matching algorithm applied to match the text
293 typed by the user in the TextField field with items in the
294 list. The current values are XmNONE and XmQUICK_NAVIGATE, as
295 follows:
296 XmNONE Indicates that there is no assigned matching algo‐
298 rithm.
299 XmQUICK_NAVIGATE
301 Is only valid for noneditable ComboBoxes (XmNcom‐
302 boBoxType resource value XmDROP_DOWN_LIST). This
303 algorithm supports 1-character navigation when the
304 List widget has focus. If the typed character is
305 the initial character of some item in the List,
306 this algorithm causes that item to be navigated to
307 and selected. Subsequently typing the same charac‐
308 ter will cycle among the items with the same first
309 character.
310 XmNpositionMode
312 Specifies how the value of the XmNselectedPosition resource
313 and the item_position field of the callback structure are to
314 be interpreted. Note that the convenience functions XmCom‐
315 boBoxDeletePos and XmComboBoxAddItem are not affected by this
316 resource, and (like XmList) always use 1-based positions.
317 Valid values for this resource are:
318 XmZERO_BASED
320 (DtComboBox compatibility mode: default) XmNselect‐
321 edPosition is in [0,itemcount-1]. The item_posi‐
322 tion in the XmComboBoxCallbackStruct is 0 if the
323 first element in the list was selected. Note that 0
324 is also returned if no element in the list was
325 selected (that is, a new item was entered in the
326 text field).
327 XmONE_BASED
329 (Motif mode) Both the resource value and the call‐
330 back fields are 1-based. This is consistent with
331 other Motif widgets.
332 XmNrenderTable
334 Specifies the render table associated with ComboBox. This
335 render table is used in both the TextField field and the List
336 in the ComboBox. This is used in conjunction with the XmNvis‐
337 ibleItemCount resource of the List to determine the height of
338 the ComboBox widget.
339 If this value is NULL at initialization, and if the widget
341 parent is XmBulletinBoard or its subclasses, VendorShell or
342 its subclasses, or XmMenuShell, then the widget parent pro‐
343 vides the default render table associated with the widget.
344 If both a render table and a fontlist are specified, the ren‐
345 der table will take precedence.
346 XmNselectedItem
348 Specifies a compound string that represents the current
349 selection of the ComboBox. The selected item is the content
350 of the ComboBox text entry field.
351 XmNselectedPosition
353 If the selection in the ComboBox is an item in the list, this
354 is the index of the selected item in the list. If no item in
355 the list is selected, this is 0.
356 XmNselectionCallback
358 Specifies the list of callbacks called when an item is
359 selected. The reason field in the XmComboBoxCallbackStruct
360 is XmCR_SELECT.
361 XmNtextField
363 The text field widget.
364 XmNvisibleItemCount
366 Specifies the number of visible items in the list. This will
367 override any value specified for the list. Refer to the
368 XmList man page for more detailed information.
369 Inherited Resources
371 ComboBox inherits behavior and resources from superclasses described in
372 the following tables. For a complete description of each resource,
373 refer to the reference page for that superclass.
374 ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
376 │ │ XmManager │Resource Set │ │ │
377 │Name │ Class │ Type │ Default │ Access │
378 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
379 │XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
380 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
381 │XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
382 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
383 │XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
384 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
385 │XmNhelpCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
386 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
387 │XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
388 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
389 │XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
390 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
391 │XmNinitialFocus │ XmCInitialFocus │ Widget │ NULL │ CSG │
392 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
393 │XmNlayoutDirection │ XmCLayoutDirection │ XmDirection │ dynamic │ CG │
394 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
395 │XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmSTICKY_TAG_GROUP │ CSG │
396 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
397 │XmNpopupHandlerCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
398 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
399 │XmNshadowThickness │ XmCShadowThickness │ Dimension │ 2 │ CSG │
400 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
401 │XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CG │
402 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
403 │XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
404 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
405 │XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
406 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
407 │XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
408 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
409 │XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
410 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
411 │XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
412 ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
413 └────────────────────────┴───────────────────────┴───────────────────┴──────────────────────┴────────┘
414 ┌───────────────────────────────────────────────────────────────────────┐
415 │ │ Composite Reso│urce Set │ │ │
416 │Name │ Class │ Type │ Default │ Access │
417 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
418 │XmNchildren │ XmCReadOnly │ WidgetList │ NULL │ G │
419 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
420 │XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL │ CSG │
421 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
422 │XmNnumChildren │ XmCReadOnly │ Cardinal │ 0 │ G │
423 ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
424 └──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
425 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
426 │ │ Core Resource Se│t │ │ │
427 │Name │ Class │ Type │ Default │ Access │
428 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
429 │XmNaccelerators │ XmCAccelerators │ XtAccelerators │ dynamic │ CSG │
430 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
431 │XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
432 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
433 │XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
434 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
435 │XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
436 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
437 │XmNborderColor │ XmCBorderColor │ Pixel │ XtDefaultForeground │ CSG │
438 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
439 │XmNborderPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
440 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
441 │XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ CSG │
442 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
443 │XmNcolormap │ XmCColormap │ Colormap │ dynamic │ CG │
444 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
445 │XmNdepth │ XmCDepth │ int │ dynamic │ CG │
446 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
447 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
448 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
449 │XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
450 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
451 │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean │ True │ C │
452 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
453 │XmNmappedWhenManaged │ XmCMappedWhenManaged │ Boolean │ True │ CSG │
454 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
455 │XmNscreen │ XmCScreen │ Screen * │ dynamic │ CG │
456 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
457 │XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
458 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
459 │XmNtranslations │ XmCTranslations │ XtTranslations │ dynamic │ CSG │
460 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
461 │XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
462 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
463 │XmNx │ XmCPosition │ Position │ 0 │ CSG │
464 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
465 │XmNy │ XmCPosition │ Position │ 0 │ CSG │
466 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
467 └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
468 Callback Information
469 A pointer to the following structure is passed to each callback. The
470 callback structure is defined as follows:
471 typedef struct
473 {
474 int reason;
475 XEvent *event;
476 XmString item_or_text;
477 int item_position;
478 } XmComboBoxCallbackStruct;
479 reason Indicates why the callback was invoked.
481 event Points to the XEvent that triggered the callback. It can be
483 NULL.
484 item_or_text
486 The contents of the text field at the time the event caused
487 the callback. The item_or_text parameter points to a tempo‐
488 rary storage space that is reused after the callback is fin‐
489 ished. If an application needs to save the item, it should
490 copy item_or_text into its own data space.
491 item_position
493 The position of item in the list's XmNitems 1-based array. If
494 this is 0, it means that the item_or_text was not selected
495 from the List.
496 Translations
498 The ComboBox translations are listed below.
499 The following key names are listed in the X standard key event transla‐
501 tion table syntax. This format is the one used by Motif to specify the
502 widget actions corresponding to a given key. A brief overview of the
503 format is provided under VirtualBindings(3). For a complete descrip‐
504 tion of the format, please refer to the X Toolkit Instrinsics Documen‐
505 tation.
506 Note:
508 The KPageUp and KPageDown translations do not take effect unless
510 the List child widget is posted.
511 <Btn1Down>:
513 CBArmAndDropDownList()
514 <Btn1Up>: CBDisarm()
516 The following lists the List translations in the drop-down list. When
518 ComboBox XmNcomboBoxType is XmDROP_DOWN_LIST, <osfActivate>, <osfCan‐
519 cel>, and Return are overriden by ComboBox actions.
520 :c <Key><osfDown>:
522 CBDropDownList()
523 :c <Key><osfUp>:
525 CBDropDownList()
526 :<Key><osfCancel>:
528 CBCancel()
529 :<Key><osfActivate>:
531 CBActivate()
532 ∼s ∼m ∼a<Key>Return:
534 CBActivate()
535 Accelerators
537 The following accelerators are added to ComboBox and its children. The
538 accelerators may not directly correspond to a translation table. If
539 the translation is not listed below, it may depend on the context of
540 the event.
541 :c <Key><osfUp>:
543 CBDropDownList()
544 :<Key><osfUp>:
546 CBListAction(Up)
547 :c <Key><osfDown>:
549 CBDropDownList()
550 :<Key><osfDown>:
552 CBListAction(Down)
553 :c <Key><osfBeginLine>:
555 CBListAction(ListBeginData)
556 :c <Key><osfEndLine>:
558 CBListAction(ListEndData)
559 :<Key><osfPageUp>:
561 CBListAction(ListPrevPage)
562 :<Key><osfPageDown>:
564 CBListAction(ListNextPage)
565 A drop-down ComboBox also adds accelerators to its List child. Aside
567 from the accelerators that are already listed in this section, those
568 accelerators are the default TextField key translations.
569 Action Routines
571 The XmComboBox action routines are as follows:
572 CBActivate():
574 Calls the XmNselectionCallback callbacks. If the XmNcomboBox‐
575 Type is XmDROP_DOWN_COMBO_BOX or XmDROP_DOWN_LIST, it unposts
576 the list. If the parent is a manager, passes the event to the
577 parent.
578 CBArmAndDropDownList():
580 If the pointer is within the down arrow, draws the shadow of
581 the arrow in the selected state, and then posts the list.
582 CBCancel():
584 If the XmNcomboBoxType is XmDROP_DOWN_COMBO_BOX or
585 XmDROP_DOWN_LIST, pops down the list. If the parent is a man‐
586 ager, passes the event to the parent.
587 CBDisarm():
589 Redraws the arrow in an unselected state.
590 CBDropDownList():
592 If XmNcomboBoxType is XmDROP_DOWN or XmDROP_DOWN_LIST, and
593 list is not displayed, posts the list. If list is displayed,
594 it unposts the list.
595 CBListAction(ListBeginData):
597 Moves the location cursor to the first item in the list. In
598 Normal Mode, this also deselects any current selection,
599 selects the first item in the list, and calls the XmNbrowseS‐
600 electionCallback selection callback.
601 CBListAction(ListEndData):
603 Moves the location cursor to the last item in the list. In
604 Normal Mode, this also deselects any current selection,
605 selects the last item in the list, and calls the XmNbrowseSe‐
606 lectionCallback selection callback.
607 CBListAction(ListPrevPage):
609 Scrolls the list to the previous page, moving the location
610 cursor to a new item. This action also selects the new item,
611 deselects any current selection, and calls the XmNbrowseSe‐
612 lectionCallback callbacks. If the ComboBox is not a drop-
613 down type, then this action does nothing.
614 CBListAction(ListNextPage):
616 Scrolls the list to the next page, moving the location cursor
617 to a new item. This action also selects the new item, dese‐
618 lects any current selection, and calls the XmNbrowseSelec‐
619 tionCallback callbacks. If the ComboBox is not a drop-down
620 type, then this action does nothing.
621 CBListAction(Up):
623 Moves the location cursor to the previous item in the list.
624 This action also selects the previous item, deselects any
625 current selection, and calls the XmNbrowseSelectionCallback
626 callbacks. Note that, unlike the List ListPrevItem action,
627 this action wraps around.
628 CBListAction(Down):
630 Moves the location cursor to the next item in the list. This
631 action also selects the next item, deselects any current
632 selection, and calls the XmNbrowseSelectionCallback call‐
633 backs. Note that, unlike the List ListNextItem action, this
634 action wraps around.
635 Virtual Bindings
637 The bindings for virtual keys are vendor specific. For information
638 about bindings for virtual buttons and keys, see VirtualBindings(3).
639
641 The toolkit will display a warning if the application tries to set the
642 value of XmNlist or the XmNtextField resource, which are read-only
643 (marked G in the resource table).
644
646 Composite(3), Core(3), XmCreateComboBox(3), XmList(3), XmManager(3),
647 XmTextField(3), XmVaCreateComboBox(3), and XmVaCreateManagedCom‐
648 boBox(3).
649 XmComboBox(library call)