1XmList(library call) XmList(library call)
2
6 XmList — The List widget class
7
9 #include <Xm/List.h>
10
12 List allows a user to select one or more items from a group of choices.
13 Items are selected from the list in a variety of ways, using both the
14 pointer and the keyboard. List operates on an array of compound
15 strings that are defined by the application. Each compound string
16 becomes an item in the List, with the first compound string becoming
17 the item in position 1, the second becoming the item in position 2, and
18 so on.
19 Specifying the number of items that are visible sets the size of the
21 List. If the number of visible items is not specified, the height of
22 the list controls the number of visible items. Each item assumes the
23 height of the tallest element in the list. To create a list that
24 allows the user to scroll easily through a large number of items, use
25 the XmCreateScrolledList convenience function.
26 To select items, move the pointer or cursor to the desired item and
28 press the <Btn1> mouse button or the key defined as <osfSelect>. There
29 are several styles of selection behavior, and they all highlight the
30 selected item or items by displaying them in inverse colors. An appro‐
31 priate callback is invoked to notify the application of the user's
32 choice. The application then takes whatever action is required for the
33 specified selection. When a List is insensitive, all of the list items
34 are displayed in a stippled fill pattern.
35 List uses the XmQTspecifyRenderTable, XmQTscrollFrame, and XmQTnaviga‐
37 tor traits, and holds the XmQTtransfer trait.
38 Selection
40 Each list has one of four selection models:
41 · Single Select
43 · Browse Select
45 · Multiple Select
47 · Extended Select
49 In Single Select and Browse Select, at most one item is selected at a
51 time. In Single Select, pressing <Btn1> on an item toggles its selec‐
52 tion state and deselects any other selected item. In Browse Select,
53 pressing <Btn1> on an item selects it and deselects any other selected
54 item; dragging <Btn1> moves the selection as the pointer is moved.
55 Releasing <Btn1> on an item moves the location cursor to that item.
56 In Multiple Select, any number of items can be selected at a time.
58 Pressing <Btn1> on an item toggles its selection state but does not
59 deselect any other selected items.
60 In Extended Select, any number of items can be selected at a time, and
62 the user can easily select ranges of items. Pressing <Btn1> on an item
63 selects it and deselects any other selected item. Dragging <Btn1> or
64 pressing or dragging <Shift><Btn1> following a <Btn1> action selects
65 all items between the item under the pointer and the item on which
66 <Btn1> was pressed. This action also deselects any other selected
67 items outside that range.
68 Extended Select also allows the user to select and deselect discontigu‐
70 ous ranges of items. Pressing <Ctrl><Btn1> on an item toggles its
71 selection state but does not deselect any other selected items. Drag‐
72 ging <Ctrl><Btn1> or pressing or dragging <Shift><Btn1> following a
73 <Ctrl><Btn1> action sets the selection state of all items between the
74 item under the pointer and the item on which <Ctrl><Btn1> was pressed
75 to the state of the item on which <Ctrl><Btn1> was pressed. This
76 action does not deselect any other selected items outside that range.
77 All selection operations available from the mouse are also available
79 from the keyboard. List has two keyboard selection modes, Normal Mode
80 and Add Mode. In Normal Mode, navigation operations and <osfSelect>
81 select the item at the location cursor and deselect any other selected
82 items. In Add Mode, navigation operations have no effect on selection,
83 and <osfSelect> toggles the selection state of the item at the location
84 cursor without deselecting any other selected items, except in Single
85 Select.
86 Single and Multiple Select use Add Mode, and Browse Select uses Normal
88 Mode.
89 Extended Select can use either mode; the user changes modes by pressing
91 <osfAddMode>. In Extended Select Normal Mode, pressing <osfSelect> has
92 the same effect as pressing <Btn1>; <osfExtend> and shifted navigation
93 have the same effect as pressing <Shift><Btn1> following a <Btn1>
94 action. In Extended Select Add Mode, pressing <osfSelect> has the same
95 effect as pressing <Ctrl><Btn1>; <osfExtend> and shifted navigation
96 have the same effect as pressing <Shift><Btn1> following a <Ctrl><Btn1>
97 action.
98 Normal Mode is indicated by a solid location cursor, and Add Mode is
100 indicated by a dashed location cursor.
101 Data Transfer Behavior
103 List supports dragging of items from the List and transfer of items to
104 the clipboard. When the user presses BTransfer on a selected item, the
105 widget transfers all selected items. When the user presses BTransfer
106 on an unselected item, the widget transfers only that item. Depending
107 on the value of XmNprimaryOwnership, List can also support primary
108 selection.
109 When the XmNconvertCallback procedures are called, the location_data
111 member of the XmConvertCallbackStruct member is NULL if the selected
112 items are being transferred. If the selected items are not being
113 transferred, this member has the following value: If a single item is
114 being transferred, the value is an integer representing the position of
115 the item in the List. A value of 1 transfers the first item in the
116 List; a value of 2 transfers the second item; and so on. If the entire
117 contents of the List are being transferred, the value is -1.
118 As a source of data, List supports the following targets and associated
120 conversions of data to these targets:
121 locale If the locale target matches the widget's locale, the widget
123 transfers the selected list items in the encoding of the
124 locale. Each item transferred except the last includes a
125 trailing separator.
126 COMPOUND_TEXT
128 The widget transfers the selected list items as type COM‐
129 POUND_TEXT. Each item transferred except the last includes a
130 trailing separator.
131 UTF8_STRING
133 The widget transfers the selected list items as type
134 UTF8_STRING. Each item transferred except the last includes
135 a trailing separator.
136 STRING The widget transfers the selected list items as type STRING.
138 Each item transferred except the last includes a trailing
139 separator.
140 TEXT If the selected list items are fully convertible to the
142 encoding of the locale, the widget transfers the selected
143 list items in the encoding of the locale. Otherwise, the
144 widget transfers the selected list items as type COM‐
145 POUND_TEXT. Each item transferred except the last includes a
146 trailing separator.
147 _MOTIF_CLIPBOARD_TARGETS
149 The widget transfers, as type ATOM, a list of the targets it
150 supports for immediate transfer for the CLIPBOARD selection.
151 These include _MOTIF_COMPOUND_STRING. If the selected list
152 items are fully convertible to STRING, these also include
153 STRING; otherwise, they also include COMPOUND_TEXT and
154 UTF8_STRING.
155 _MOTIF_COMPOUND_STRING
157 The widget transfers the selected list items as a compound
158 string in Byte Stream format. Each item transferred except
159 the last includes a trailing separator.
160 _MOTIF_DEFERRED_CLIPBOARD_TARGETS
162 The widget transfers, as type ATOM, a list of the targets it
163 supports for delayed transfer for the CLIPBOARD selection.
164 This widget currently supplies no targets for
165 _MOTIF_DEFERRED_CLIPBOARD_TARGETS.
166 _MOTIF_EXPORT_TARGETS
168 The widget transfers, as type ATOM, a list of the targets to
169 be used as the value of the DragContext's XmNexportTargets in
170 a drag-and-drop transfer. These include _MOTIF_COM‐
171 POUND_STRING, COMPOUND_TEXT, UTF8_STRING, the encoding of the
172 locale, STRING, TEXT, BACKGROUND, and FOREGROUND.
173 _MOTIF_LOSE_SELECTION
175 When the widget loses the selection, it deselects all list
176 items.
177 As a source of data, List also supports the following standard Motif
179 targets:
180 BACKGROUND
182 The widget transfers XmNbackground as type PIXEL.
183 CLASS The widget finds the first shell in the widget hierarchy that
185 has a WM_CLASS property and transfers the contents as text in
186 the current locale.
187 CLIENT_WINDOW
189 The widget finds the first shell in the widget hierarchy and
190 transfers its window as type WINDOW.
191 COLORMAP The widget transfers XmNcolormap as type COLORMAP.
193 FOREGROUND
195 The widget transfers XmNforeground as type PIXEL.
196 NAME The widget finds the first shell in the widget hierarchy that
198 has a WM_NAME property and transfers the contents as text in
199 the current locale.
200 TARGETS The widget transfers, as type ATOM, a list of the targets it
202 supports. These include the standard targets in this list.
203 These also include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT,
204 UTF8_STRING the encoding of the locale, STRING, and TEXT.
205 TIMESTAMP The widget transfers the timestamp used to acquire the selec‐
207 tion as type INTEGER.
208 _MOTIF_RENDER_TABLE
210 The widget transfers XmNrenderTable if it exists, or else the
211 default text render table, as type STRING.
212 _MOTIF_ENCODING_REGISTRY
214 The widget transfers its encoding registry as type STRING.
215 The value is a list of NULL separated items in the form of
216 tag encoding pairs. This target symbolizes the transfer tar‐
217 get for the Motif Segment Encoding Registry. Widgets and
218 applications can use this Registry to register text encoding
219 formats for specified render table tags. Applications access
220 this Registry by calling XmRegisterSegmentEncoding and
221 XmMapSegmentEncoding.
222 List has no widget class destination procedure. Subclasses and the
224 XmNdestinationCallback procedures are responsible for any data trans‐
225 fers to the widget.
226 Classes
228 List inherits behavior, resources, and traits from Core and XmPrimi‐
229 tive.
230 The class pointer is xmListWidgetClass.
232 The class name is XmList.
234 New Resources
236 The following table defines a set of widget resources used by the pro‐
237 grammer to specify data. The programmer can also set the resource val‐
238 ues for the inherited classes to set attributes for this widget. To
239 reference a resource by name or by class in a .Xdefaults file, remove
240 the XmN or XmC prefix and use the remaining letters. To specify one of
241 the defined values for a resource in a .Xdefaults file, remove the Xm
242 prefix and use the remaining letters (in either lowercase or uppercase,
243 but include any underscores between words). The codes in the access
244 column indicate if the given resource can be set at creation time (C),
245 set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
246 not applicable (N/A).
247 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
249 │ │ XmList Reso│urce Set │ │ │
250 │Name │ Class │ Type │ Default │ Access │
251 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
252 │XmNautomaticSelection │ XmCAutomaticSelection │ XtEnum │ False │ CSG │
253 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
254 │XmNbrowseSelectionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
255 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
256 │XmNdefaultActionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
257 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
258 │XmNdestinationCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
259 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
260 │XmNdoubleClickInterval │ XmCDoubleClickInterval │ int │ dynamic │ CSG │
261 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
262 │XmNextendedSelectionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
263 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
264 │XmNfontList │ XmCFontList │ XmFontList │ dynamic │ CSG │
265 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
266 │XmNitemCount │ XmCItemCount │ int │ 0 │ CSG │
267 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
268 │XmNitems │ XmCItems │ XmStringTable │ NULL │ CSG │
269 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
270 │XmNlistMarginHeight │ XmCListMarginHeight │ Dimension │ 0 │ CSG │
271 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
272 │XmNlistMarginWidth │ XmCListMarginWidth │ Dimension │ 0 │ CSG │
273 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
274 │XmNlistSizePolicy │ XmCListSizePolicy │ unsigned char │ XmVARIABLE │ CG │
275 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
276 │XmNlistSpacing │ XmCListSpacing │ Dimension │ 0 │ CSG │
277 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
278 │XmNmatchBehavior │ XmCMatchBehavior │ unsigned char │ XmQUICK_NAVIGATE │ CSG │
279 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
280 │XmNmultipleSelectionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
281 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
282 │XmNprimaryOwnership │ XmCPrimaryOwnership │ unsigned char │ XmOWN_NEVER │ CSG │
283 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
284 │XmNrenderTable │ XmCRenderTable │ XmRenderTable │ dynamic │ CSG │
285 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
286 │XmNscrollBarDisplayPolicy │ XmCScrollBarDisplayPolicy │ unsigned char │ XmAS_NEEDED │ CSG │
287 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
288 │XmNselectColor │ XmCSelectColor │ XmRSelectColor │ XmREVERSED_GROUND_COLORS │ CSG │
289 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
290 │XmNselectedItemCount │ XmCSelectedItemCount │ int │ 0 │ CSG │
291 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
292 │XmNselectedItems │ XmCSelectedItems │ XmStringTable │ NULL │ CSG │
293 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
294 │XmNselectedPositionCount │ XmCSelectedPositionCount │ int │ 0 │ CSG │
295 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
296 │XmNselectedPositions │ XmCSelectedPositions │ unsigned int * │ NULL │ CSG │
297 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
298 │XmNselectionMode │ XmCSelectionMode │ unsigned char │ dynamic │ CSG │
299 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
300 │XmNselectionPolicy │ XmCSelectionPolicy │ unsigned char │ XmBROWSE_SELECT │ CSG │
301 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
302 │XmNsingleSelectionCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
303 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
304 │XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CSG │
305 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
306 │XmNtopItemPosition │ XmCTopItemPosition │ int │ 1 │ CSG │
307 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
308 │XmNvisibleItemCount │ XmCVisibleItemCount │ int │ dynamic │ CSG │
309 ├─────────────────────────────┼───────────────────────────┼───────────────────┼──────────────────────────┼────────┤
310 └─────────────────────────────┴───────────────────────────┴───────────────────┴──────────────────────────┴────────┘
311 XmNautomaticSelection
312 Invokes either XmNbrowseSelectionCallback or XmNextendedSe‐
313 lectionCallback when <Btn1> is pressed and the items that are
314 shown as selected change if the value is True (or XmAUTO) and
315 the selection mode is either XmBROWSE_SELECT or XmEX‐
316 TENDED_SELECT respectively. If False (XmNO_AUTO_SELECT), no
317 selection callbacks are invoked until the user releases the
318 mouse button. See Behavior for further details on the inter‐
319 action of this resource with the selection modes.
320 XmNbrowseSelectionCallback
322 Specifies a list of callbacks that is called when an item is
323 selected in the browse selection mode. The reason is
324 XmCR_BROWSE_SELECT.
325 XmNdefaultActionCallback
327 Specifies a list of callbacks that is called when an item is
328 double clicked or <osfActivate> is pressed. The reason is
329 XmCR_DEFAULT_ACTION.
330 XmNdestinationCallback
332 Specifies a list of callbacks called when the List is the
333 destination of a transfer operation. The type of the struc‐
334 ture whose address is passed to these callbacks is XmDestina‐
335 tionCallbackStruct. The reason is XmCR_OK.
336 XmNdoubleClickInterval
338 If a button click is followed by another button click within
339 the time span specified by this resource (in milliseconds),
340 the button clicks are considered a double-click action,
341 rather than two single-click actions. The value must not be
342 negative. The default value is the display's multiclick
343 time.
344 XmNextendedSelectionCallback
346 Specifies a list of callbacks that is called when items are
347 selected using the extended selection mode. The reason is
348 XmCR_EXTENDED_SELECT.
349 XmNfontList
351 Specifies the font list associated with the list items. XmN‐
352 fontList is obsolete and exists only for compatibility with
353 previous releases. You should now use XmNrenderTable instead
354 of XmNfontList. If both are specified, the render table will
355 take precedence. The font list is used in conjunction with
356 the XmNvisibleItemCount resource to determine the height of
357 the List widget. If this value is NULL at initialization,
358 the parent hierarchy of the widget is searched for a widget
359 that holds the XmQTspecifyRenderTable trait. If such an
360 ancestor is found, the font list is initialized to the
361 XmTEXT_RENDER_TABLE value of the ancestor widget. If no such
362 widget is found, the default is implementation dependent.
363 Refer to XmFontList(3) for more information on a font list
364 structure.
365 XmNitemCount
367 Specifies the total number of items. The value must be the
368 number of items in XmNitems and must not be negative. It is
369 automatically updated by the list whenever an item is added
370 to or deleted from the list.
371 XmNitems Points to an array of compound strings that are to be dis‐
373 played as the list items. Refer to XmString(3) for more
374 information on the creation and structure of compound
375 strings. XtGetValues for this resource returns the list
376 items themselves, not a copy of the list items. The applica‐
377 tion must not free the returned items.
378 XmNlistMarginHeight
380 Specifies the height of the margin between the list border
381 and the items.
382 XmNlistMarginWidth
384 Specifies the width of the margin between the list border and
385 the items.
386 XmNlistSizePolicy
388 Controls the reaction of the List when an item grows horizon‐
389 tally beyond the current size of the list work area. If the
390 value is XmCONSTANT, the list viewing area does not grow, and
391 a horizontal ScrollBar is added for a List whose parent is a
392 ScrolledWindow. If this resource is set to XmVARIABLE, the
393 List grows to match the size of the longest item, and no hor‐
394 izontal ScrollBar appears.
395 When the value of this resource is XmRESIZE_IF_POSSIBLE, the
397 List attempts to grow or shrink to match the width of the
398 widest item. If it cannot grow to match the widest size, a
399 horizontal ScrollBar is added for a List whose parent is a
400 ScrolledWindow if the longest item is wider than the list
401 viewing area.
402 The size policy must be set at the time the List widget is
404 created. It cannot be changed at a later time through XtSet‐
405 Values.
406 XmNlistSpacing
408 Specifies the spacing between list items. This spacing
409 increases by the value of the XmNhighlightThickness resource
410 in Primitive.
411 XmNmatchBehavior
413 Specifies the matching behavior followed by XmList. The cur‐
414 rent values are XmNONE and XmQUICK_NAVIGATE, as follows:
415 XmNONE Specifies that the typed in characters are ignored.
417 XmQUICK_NAVIGATE
419 Specifies that 1-character navigation shall be sup‐
420 ported when List has focus. If the typed character
421 is the initial character of some set of items in
422 List, the first of those items following the cur‐
423 rent item will be navigated to (become the current
424 item). If all such items precede the current item,
425 the first such item becomes the current item. Sub‐
426 sequently, typing the same character will cycli‐
427 cally navigate among the items with the same first
428 character.
429 XmNmultipleSelectionCallback
431 Specifies a list of callbacks that is called when an item is
432 selected in multiple selection mode. The reason is XmCR_MUL‐
433 TIPLE_SELECT.
434 XmNprimaryOwnership
436 Specifies whether XmContainer takes ownership of the Primary
437 selection when a selection is made inside it. This resource
438 can take the following values:
439 XmOWN_NEVER
441 Never takes ownership.
442 XmOWN_ALWAYS
444 Always takes ownership.
445 XmOWN_MULTIPLE
447 Only takes ownership is more than one element has
448 been selected.
449 XmOWN_POSSIBLE_MULTIPLE
451 Only takes ownership if more than one element can
452 be selected at a time.
453 XmNrenderTable
455 Specifies the render table associated with the list items.
456 The render table is used in conjunction with the XmNvisi‐
457 bleItemCount resource to determine the height of the List
458 widget. If this value is NULL at initialization, List
459 searches its parent hierarchy for a widget that holds the
460 XmQTspecifyRenderTable trait. If such an ancestor is found,
461 the render table is initialized to the XmTEXT_RENDER_TABLE
462 value of the ancestor widget. If no such widget is found, the
463 default is implementation dependent. If a font list and a
464 render table are both specified, the render table will take
465 precedence. Refer to XmRenderTable(3) for more information on
466 the creation and structure of a render table.
467 XmNscrollBarDisplayPolicy
469 Controls the display of vertical ScrollBars in a List whose
470 parent is a ScrolledWindow. When the value of this resource
471 is XmAS_NEEDED, a vertical ScrollBar is displayed only when
472 the number of items in the List exceeds the number of visible
473 items. When the value is XmSTATIC, a vertical ScrollBar is
474 always displayed.
475 XmNselectColor
477 Allows the application to specify the color of the background
478 rectangle that indicates selected text. It takes two values:
479 XmDEFAULT_SELECT_COLOR
481 Causes the select color to be set to a color
482 between the background and the bottom shadow color.
483 XmREVERSED_GROUND_COLORS
485 Forces the select color to the foreground color and
486 the color of any text rendered over the select
487 color to be in the background color.
488 HIGHLIGHT_COLOR
490 Forces the fill color to use the highlight color.
491 XmNselectedItemCount
493 Specifies the number of strings in the selected items list.
494 The value must be the number of items in XmNselectedItems and
495 must not be negative.
496 XmNselectedItems
498 Points to an array of compound strings that represents the
499 list items that are currently selected, either by the user or
500 by the application. XtGetValues for this resource returns
501 the list items themselves, not a copy of the list items. The
502 application must not free the returned items or the array.
503 Setting XmNselectedItems selects those list items that
505 exactly match items in the given XmNselectedItems list. There
506 may be additional items in XmNselectedItems that do not match
507 items in the list. These items remain until XmNselectedItems
508 is updated. If XmNitems is changed such that the list now
509 contains items matching previously unmatched items in XmNse‐
510 lectedItems, those new items will also appear selected.
511 Any user interaction with the list that causes at least one
513 item to be selected or deselected and any call to XmList‐
514 DeleteAllItems, XmListDeleteItem, XmListDeleteItems, XmList‐
515 DeleteItemsPos, XmListDeletePos, XmListDeletePositions,
516 XmListDeselectAllItems, XmListDeselectItem, XmListDeselect‐
517 Pos, XmListSelectItem, XmListSelectPos, or XmListUpdateSe‐
518 lectedList cause XmNselectedItems to be updated immediately
519 to exactly reflect the visual state of the list. Calls to
520 any other XmList functions do not affect XmNselectedItems.
521 XmNselectedPositionCount
523 Specifies the number of positions in the selected positions
524 list. The value must be the number of items in XmNselected‐
525 Positions
526 XmNselectedPositions
528 Points to an array of the positions of the selected items in
529 the List. XtGetValues for this resource returns the list
530 items themselves, not a copy of the list items. The applica‐
531 tion must not free the returned items or the array.
532 XmNselectionMode
534 Defines what effect keyboard navigations have on selection.
535 The valid modes are:
536 XmADD_MODE
538 Allows no navigation operations to have effect on
539 selection, and <osfSelect> toggles the selection
540 state of the item at the location cursor without
541 deselecting any other selected items, except in
542 Single Select. However, the widget cannot be put
543 into add mode if the XmNselectionPolicy resource is
544 an incompatible mode (XmNselectionPolicy cannot be
545 XmBROWSE_SELECT).
546 XmNORMAL_MODE
548 Allows navigation operations and <osfSelect> to
549 select the item at the location cursor and deselect
550 any other selected items. However, the widget can‐
551 not be put into normal mode if the XmNselectionPol‐
552 icy resource is an incompatible mode (XmNselection‐
553 Policy cannot be XmSINGLE_SELECT or XmMULTI‐
554 PLE_SELECT).
555 XmNselectionPolicy
557 Defines the interpretation of the selection action. This can
558 be one of the following:
559 XmSINGLE_SELECT
561 Allows only single selections
562 XmMULTIPLE_SELECT
564 Allows multiple selections
565 XmEXTENDED_SELECT
567 Allows extended selections
568 XmBROWSE_SELECT
570 Allows drag-and-browse functionality
571 XmNsingleSelectionCallback
573 Specifies a list of callbacks that is called when an item is
574 selected in single selection mode. The reason is XmCR_SIN‐
575 GLE_SELECT.
576 XmNstringDirection
578 Is a synthetic resource for setting XmNlayoutDirection. The
579 values for this resource are XmSTRING_DIRECTION_L_TO_R and
580 XmSTRING_DIRECTION_R_TO_L. Refer to the XmNlayoutDirection
581 resource description. The XmNstringDirection resource is
582 obsoleted by XmNlayoutDirection, but is kept here for back‐
583 ward compatibility.
584 XmNtopItemPosition
586 Specifies the position of the item that is the first visible
587 item in the list. Setting this resource is equivalent to
588 calling the XmListSetPos function. The position of the first
589 item in the list is 1; the position of the second item is 2;
590 and so on. A position of 0 (zero) specifies the last item in
591 the list. The value must not be negative.
592 XmNvisibleItemCount
594 Specifies the number of items that can fit in the visible
595 space of the list work area. The List uses this value to
596 determine its height. The value must be greater than 0
597 (zero).
598 Inherited Resources
600 List inherits behavior and resources from the superclasses described in
601 the following tables. For a complete description of each resource,
602 refer to the reference page for that superclass.
603 ┌───────────────────────────────────────────────────────────────────────────────────────────────────┐
605 │ │ XmPrimitive│Resource Set │ │ │
606 │Name │ Class │ Type │ Default │ Access │
607 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
608 │XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
609 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
610 │XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
611 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
612 │XmNconvertCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
613 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
614 │XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
615 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
616 │XmNhelpCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
617 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
618 │XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
619 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
620 │XmNhighlightOnEnter │ XmCHighlightOnEnter │ Boolean │ False │ CSG │
621 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
622 │XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
623 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
624 │XmNhighlightThickness │ XmCHighlightThickness │ Dimension │ 2 │ CSG │
625 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
626 │XmNlayoutDirection │ XmCLayoutDirection │ XmDirection │ dynamic │ CG │
627 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
628 │XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmTAB_GROUP │ CSG │
629 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
630 │XmNpopupHandlerCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
631 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
632 │XmNshadowThickness │ XmCShadowThickness │ Dimension │ 2 │ CSG │
633 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
634 │XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
635 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
636 │XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
637 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
638 │XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
639 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
640 │XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
641 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
642 │XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
643 ├────────────────────────┼───────────────────────┼──────────────────┼──────────────────────┼────────┤
644 └────────────────────────┴───────────────────────┴──────────────────┴──────────────────────┴────────┘
645 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
646 │ │ Core Resource Se│t │ │ │
647 │Name │ Class │ Type │ Default │ Access │
648 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
649 │XmNaccelerators │ XmCAccelerators │ XtAccelerators │ dynamic │ CSG │
650 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
651 │XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
652 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
653 │XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
654 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
655 │XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
656 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
657 │XmNborderColor │ XmCBorderColor │ Pixel │ XtDefaultForeground │ CSG │
658 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
659 │XmNborderPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
660 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
661 │XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ CSG │
662 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
663 │XmNcolormap │ XmCColormap │ Colormap │ dynamic │ CG │
664 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
665 │XmNdepth │ XmCDepth │ int │ dynamic │ CG │
666 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
667 │XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
668 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
669 │XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
670 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
671 │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean │ True │ C │
672 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
673 │XmNmappedWhenManaged │ XmCMappedWhenManaged │ Boolean │ True │ CSG │
674 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
675 │XmNscreen │ XmCScreen │ Screen * │ dynamic │ CG │
676 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
677 │XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
678 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
679 │XmNtranslations │ XmCTranslations │ XtTranslations │ dynamic │ CSG │
680 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
681 │XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
682 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
683 │XmNx │ XmCPosition │ Position │ 0 │ CSG │
684 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
685 │XmNy │ XmCPosition │ Position │ 0 │ CSG │
686 ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
687 └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
688 Callback Information
689 List defines a new callback structure. The application must first look
690 at the reason field and use only the structure members that are valid
691 for that particular reason, because not all fields are relevant for
692 every possible reason. The callback structure is defined as follows:
693 typedef struct
695 {
696 int reason;
697 XEvent *event;
698 XmString item;
699 int item_length;
700 int item_position;
701 XmString *selected_items;
702 int selected_item_count;
703 int *selected_item_positions;
704 char selection_type;
705 unsigned char auto_selection_type;
706 } XmListCallbackStruct;
707 reason Indicates why the callback was invoked.
709 event Points to the XEvent that triggered the callback. It can be
711 NULL.
712 item The last item selected at the time of the event that caused
714 the callback. item points to a temporary storage space that
715 is reused after the callback is finished. Therefore, if an
716 application needs to save the item, it should copy the item
717 into its own data space.
718 item_length
720 The length in bytes of item. This member is obsolete and
721 exists for compatibility with earlier releases.
722 item_position
724 The position (plus one) of item in the List's XmNitems array.
725 An item_position value of one symbolizes the first element in
726 the list.
727 selected_items
729 A list of items selected at the time of the event that caused
730 the callback. selected_items points to a temporary storage
731 space that is reused after the callback is finished. There‐
732 fore, if an application needs to save the selected list, it
733 should copy the list into its own data space.
734 selected_item_count
736 The number of items in the selected_items list. This number
737 must be non-negative.
738 selected_item_positions
740 An array of integers, one for each selected item, represent‐
741 ing the position of each selected item in the List's XmNitems
742 array. selected_item_positions points to a temporary storage
743 space that is reused after the callback is finished. There‐
744 fore, if an application needs to save this array, it should
745 copy the array into its own data space.
746 selection_type
748 Indicates that the most recent extended selection was the
749 initial selection (XmINITIAL), a modification of an existing
750 selection (XmMODIFICATION), or an additional noncontiguous
751 selection (XmADDITION).
752 auto_selection_type
754 Indicates the type of automatic selection callback. The types
755 of callbacks include the following:
756 XmAUTO_BEGIN
758 Indicates the beginning of automatic selection.
759 XmAUTO_MOTION
761 Indicates that there is a button drag selection.
762 XmAUTO_CANCEL
764 Indicates that the new selection is cancelled.
765 XmAUTO_NO_CHANGE
767 Indicates that the currently selected item matches
768 the initial item.
769 XmAUTO_CHANGE
771 Indicates that the currently selected item does not
772 match the initial item.
773 The following table describes the reasons for which the individual
775 callback structure fields are valid.
776 ┌─────────────────────┬────────────────────────────┐
778 │Reason │ Valid Fields │
779 ├─────────────────────┼────────────────────────────┤
780 │XmCR_SINGLE_SELECT │ reason, event, item, │
781 │ │ item_length, item_position │
782 ├─────────────────────┼────────────────────────────┤
783 │XmCR_DEFAULT_ACTION │ reason, event, item, │
784 │ │ item_length, item_posi‐ │
785 │ │ tion, selected_items, │
786 │ │ selected_item_count, │
787 │ │ selected_item_positions │
788 ├─────────────────────┼────────────────────────────┤
789 │XmCR_BROWSE_SELECT │ reason, event, item, │
790 │ │ item_length, item_position │
791 ├─────────────────────┼────────────────────────────┤
792 │XmCR_MULTIPLE_SELECT │ reason, event, item, │
793 │ │ item_length, item_posi‐ │
794 │ │ tion, selected_items, │
795 │ │ selected_item_count, │
796 │ │ selected_item_positions │
797 ├─────────────────────┼────────────────────────────┤
798 │XmCR_EXTENDED_SELECT │ reason, event, item, │
799 │ │ item_length, item_posi‐ │
800 │ │ tion, selected_items, │
801 │ │ selected_item_count, │
802 │ │ selected_item_positions, │
803 │ │ selection_type │
804 ├─────────────────────┼────────────────────────────┤
805 └─────────────────────┴────────────────────────────┘
806 A pointer to the following callback structure is passed to the XmNdes‐
807 tinationCallback procedures:
808 typedef struct
810 {
811 int reason;
812 XEvent *event;
813 Atom selection;
814 XtEnum operation;
815 int flags;
816 XtPointer transfer_id;
817 XtPointer destination_data;
818 XtPointer location_data;
819 Time time;
820 } XmDestinationCallbackStruct;
821 reason Indicates why the callback was invoked.
823 event Points to the XEvent that triggered the callback. It can be
825 NULL.
826 selection Indicates the selection for which data transfer is being
828 requested. Possible values are CLIPBOARD, PRIMARY, SEC‐
829 ONDARY, and _MOTIF_DROP.
830 operation Indicates the type of transfer operation requested.
832 · When the selection is PRIMARY, possible values are
834 XmMOVE, XmCOPY, and XmLINK.
835 · When the selection is SECONDARY or CLIPBOARD, possible
837 values are XmCOPY and XmLINK.
838 · When the selection is _MOTIF_DROP, possible values are
840 XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of
841 XmOTHER means that the callback procedure must get fur‐
842 ther information from the XmDropProcCallbackStruct in
843 the destination_data member.
844 flags Indicates whether or not the destination widget is also the
846 source of the data to be transferred. Following are the pos‐
847 sible values:
848 XmCONVERTING_NONE
850 The destination widget is not the source of the
851 data to be transferred.
852 XmCONVERTING_SAME
854 The destination widget is the source of the data to
855 be transferred.
856 transfer_id
858 Serves as a unique ID to identify the transfer transaction.
859 destination_data
861 Contains information about the destination. When the selec‐
862 tion is _MOTIF_DROP, the callback procedures are called by
863 the drop site's XmNdropProc, and destination_data is a
864 pointer to the XmDropProcCallbackStruct passed to the XmN‐
865 dropProc procedure. When the selection is SECONDARY, desti‐
866 nation_data is an Atom representing a target recommmended by
867 the selection owner for use in converting the selection.
868 Otherwise, destination_data is NULL.
869 location_data
871 Contains information about the location where data is to be
872 transferred. The value is always NULL when the selection is
873 SECONDARY or CLIPBOARD. If the value is NULL, the data is to
874 be inserted at the widget's cursor position. Otherwise, the
875 value is an integer representing the position in the List
876 where the items are to be transferred. A value of 1 makes
877 the first new item the first item in the list; a value of 2
878 makes it the second item; and so on. Once XmTransferDone
879 procedures start to be called, location_data will no longer
880 be stable.
881 time Indicates the time when the transfer operation began.
883 Translations
885 XmList includes translations from Primitive. The XmList translations
886 are described in the following list.
887 The following key names are listed in the X standard key event transla‐
889 tion table syntax. This format is the one used by Motif to specify the
890 widget actions corresponding to a given key. A brief overview of the
891 format is provided under VirtualBindings(3). For a complete descrip‐
892 tion of the format, please refer to the X Toolkit Instrinsics Documen‐
893 tation.
894 <Btn1><Motion>:
896 ListButtonMotion()
897 s ∼m ∼a <Btn1Down>:
899 ListBeginExtend()
900 s ∼m ∼a <Btn1Up>:
902 ListEndExtend()
903 c ∼s ∼m ∼a <Btn1Down>:
905 ListBeginToggle()
906 c ∼s ∼m ∼a <Btn1Up>:
908 ListEndToggle()
909 ∼s ∼c ∼m ∼a <Btn1Down>:
911 ListBeginSelect()
912 ∼s ∼c ∼m ∼a <Btn1Up>:
914 ListEndSelect()
915 <Btn2Down>:
917 ListProcessDrag()
918 :s c <Key><osfBeginLine>:
920 ListBeginDataExtend()
921 :c <Key><osfBeginLine>:
923 ListBeginData()
924 :<Key><osfBeginLine>:
926 ListBeginLine()
927 :s c <Key><osfEndLine>:
929 ListEndDataExtend()
930 :c <Key><osfEndLine>:
932 ListEndData()
933 :<Key><osfEndLine>:
935 ListEndLine()
936 :<Key><osfPageLeft>:
938 ListLeftPage()
939 :c <Key><osfPageUp>:
941 ListLeftPage()
942 :<Key><osfPageUp>:
944 ListPrevPage()
945 :<Key><osfPageRight>:
947 ListRightPage()
948 :c <Key><osfPageDown>:
950 ListRightPage()
951 :<Key><osfPageDown>:
953 ListNextPage()
954 s <KeyDown><osfSelect>:
956 ListKbdBeginExtend()
957 :<KeyDown><osfSelect>:
959 ListKbdBeginSelect()
960 :s <KeyUp><osfSelect>:
962 ListKbdEndExtend()
963 :<KeyUp><osfSelect>:
965 ListKbdEndSelect()
966 :<Key><osfSelectAll>:
968 ListKbdSelectAll()
969 :<Key><osfDeselectAll>:
971 ListKbdDeSelectAll()
972 :<Key><osfActivate>:
974 ListKbdActivate()
975 :<Key><osfAddMode>:
977 ListAddMode()
978 :<Key><osfHelp>:
980 PrimitiveHelp()
981 :<Key><osfCancel>:
983 ListKbdCancel()
984 :c <Key><osfLeft>:
986 ListLeftPage()
987 :<Key><osfLeft>:
989 ListLeftChar()
990 :c <Key><osfRight>:
992 ListRightPage()
993 :<Key><osfRight>:
995 ListRightChar()
996 :s <Key><osfUp>:
998 ListExtendPrevItem()
999 :<Key><osfUp>:
1001 ListPrevItem()
1002 :s <Key><osfDown>:
1004 ListExtendNextItem()
1005 :<Key><osfDown>:
1007 ListNextItem()
1008 :c <Key><osfInsert>:
1010 ListCopyToClipboard()
1011 :<Key><osfCopy>:
1013 ListCopyToClipboard()
1014 ∼s c ∼m ∼a <Key>slash:
1016 ListKbdSelectAll()
1017 ∼s c ∼m ∼a <Key>backslash:
1019 ListKbdDeSelectAll()
1020 s ∼m ∼a <Key>Tab:
1022 PrimitivePrevTabGroup()
1023 ∼m ∼a <Key>Tab:
1025 PrimitiveNextTabGroup()
1026 ∼s ∼m ∼a <Key>Return:
1028 ListKbdActivate()
1029 ∼s ∼m ∼a <KeyDown>space:
1031 ListKbdBeginSelect()
1032 ∼s ∼m ∼a <KeyUp>space:
1034 ListKbdEndSelect()
1035 s ∼m ∼a <KeyDown>space:
1037 ListKbdBeginExtend()
1038 s ∼m ∼a <KeyUp>space:
1040 ListKbdEndExtend()
1041 <Key>: ListQuickNavigate()
1043 The List button event translations are modified when Display's XmNen‐
1045 ableBtn1Transfer resource does not have a value of XmOFF (in other
1046 words, it is either XmBUTTON2_TRANSFER or XmBUTTON2_ADJUST). This
1047 option allows the actions for selection and transfer to be integrated
1048 on <Btn1>, and the actions for extending the selection can be bound to
1049 <Btn2>. The actions for <Btn1> that are defined above still apply when
1050 the <Btn1> event occurs over text that is not selected. The following
1051 actions apply when the <Btn1> event occurs over text that is selected:
1052 <Btn1Motion>:
1054 ListProcessBtn1(ListButtonMotion)
1055 s ∼m ∼a <Btn1Down>
1057 ListProcessBtn1(ListBeginExtend)
1058 s ∼m ∼a <Btn1Up>
1060 ListProcessBtn1(ListEndExtend)
1061 c ∼s ∼m ∼a <Btn1Down>
1063 ListProcessBtn1(ListBeginToggle)
1064 c ∼s ∼m ∼a <Btn1Up>
1066 ListProcessBtn1(ListEndToggle)
1067 ∼s ∼c ∼m ∼a <Btn1Down>
1069 ListProcessBtn1(ListBeginSelect)
1070 ∼s ∼c ∼m ∼a <Btn1Up>
1072 ListProcessBtn1(ListEndSelect)
1073 When Display's XmNenableBtn1Transfer resource has a value of XmBUT‐
1075 TON2_ADJUST, the following actions apply:
1076 <Btn2Down>:
1078 ListProcessBtn2(ListBeginExtend)
1079 <Btn2Motion>:
1081 ListProcessBtn2(ListButtonMotion)
1082 <Btn2Up>: ListProcessBtn2(ListEndExtend)
1084 Action Routines
1086 The XmList action routines are described in the following list. The
1087 current selection is always shown with inverted colors.
1088 ListAddMode():
1090 Toggles the state of Add Mode for keyboard selection.
1091 ListBeginData():
1093 Moves the location cursor to the first item in the list. In
1094 Normal Mode, this also deselects any current selection,
1095 selects the first item in the list, and calls the appropriate
1096 selection callbacks (XmNbrowseSelectionCallback when XmNse‐
1097 lectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelec‐
1098 tionCallback when XmNselectionPolicy is set to XmEX‐
1099 TENDED_SELECT).
1100 ListBeginDataExtend():
1102 If XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEX‐
1103 TENDED_SELECT, this action moves the location cursor to the
1104 first item in the list.
1105 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1107 action does the following: If an extended selection has been
1108 made from the current anchor point, restores the selection
1109 state of the items in that range to their state before the
1110 extended selection was done; changes the selection state of
1111 the first item and all items between it and the current
1112 anchor point to the state of the item at the current anchor
1113 point; calls the XmNextendedSelectionCallback callbacks.
1114 ListBeginExtend():
1116 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1117 action does the following: If an extended selection has been
1118 made from the current anchor point, restores the selection
1119 state of the items in that range to their state before the
1120 extended selection was done, and changes the selection state
1121 of the item under the pointer and all items between it and
1122 the current anchor point to the state of the item at the cur‐
1123 rent anchor point. If XmNautomaticSelection is set to True,
1124 this action calls the XmNextendedSelectionCallback callbacks.
1125 The auto_selection_type component of the callback structure
1126 will be set to XmAUTO_BEGIN.
1127 ListBeginLine():
1129 Moves the horizontal scroll region to the beginning of the
1130 line.
1131 ListBeginSelect():
1133 If XmNselectionPolicy is set to XmSINGLE_SELECT, deselects
1134 any current selection and toggles the selection state of the
1135 item under the pointer.
1136 If XmNselectionPolicy is set to XmBROWSE_SELECT, deselects
1138 any current selection and selects the item under the pointer.
1139 If XmNautomaticSelection is set to True, calls the XmNbrows‐
1140 eSelectionCallback callbacks. The auto_selection_type compo‐
1141 nent of the callback structure will be set to XmAUTO_BEGIN.
1142 If XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles
1144 the selection state of the item under the pointer. Any pre‐
1145 vious selections remain.
1146 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1148 action deselects any current selection, selects the item
1149 under the pointer, and sets the current anchor at that item.
1150 If XmNautomaticSelection is set to True, this action calls
1151 the XmNextendedSelectionCallback callbacks. The auto_selec‐
1152 tion_type component of the callback structure will be set to
1153 XmAUTO_BEGIN.
1154 ListBeginToggle():
1156 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1157 action moves the current anchor to the item under the pointer
1158 without changing the current selection. If the item is unse‐
1159 lected, this action selects it; if the item is selected, this
1160 action unselects it. If XmNautomaticSelection is set to
1161 True, this action calls the XmNextendedSelectionCallback
1162 callbacks.
1163 Otherwise, the list takes keyboard focus. No other action
1165 occurs. The auto_selection_type component of the callback
1166 structure will be set to XmAUTO_BEGIN.
1167 ListButtonMotion():
1169 If XmNselectionPolicy is set to XmBROWSE_SELECT, this action
1170 deselects any current selection and selects the item under
1171 the pointer. If XmNautomaticSelection is set to True and the
1172 pointer has entered a new list item, this action calls the
1173 XmNbrowseSelectionCallback callbacks.
1174 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1176 action does the following: If an extended selection is being
1177 made and an extended selection has previously been made from
1178 the current anchor point, restores the selection state of the
1179 items in that range to their state before the previous
1180 extended selection was done and changes the selection state
1181 of the item under the pointer and all items between it and
1182 the current anchor point to the state of the item at the cur‐
1183 rent anchor point. If XmNautomaticSelection is set to True
1184 and the pointer has entered a new list item, calls the XmNex‐
1185 tendedSelectionCallback callbacks.
1186 If the pointer leaves a scrolled list, this action scrolls
1188 the list in the direction of the pointer motion. The
1189 auto_selection_type component of the callback structure will
1190 be set to XmAUTO_MOTION.
1191 ListCopyToClipboard()
1193 Copies the content of the selected items to the clipboard as
1194 a single compound string with each item separated by a new‐
1195 line. This action calls the XmNconvertCallback procedures,
1196 possibly multiple times, for the CLIPBOARD selection.
1197 ListEndData():
1199 Moves the location cursor to the last item in the list. In
1200 Normal Mode, this also deselects any current selection,
1201 selects the last item in the list, and calls the appropriate
1202 selection callbacks (XmNbrowseSelectionCallback when XmNse‐
1203 lectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelec‐
1204 tionCallback when XmNselectionPolicy is set to XmEX‐
1205 TENDED_SELECT).
1206 ListEndDataExtend():
1208 If XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEX‐
1209 TENDED_SELECT, this action moves the location cursor to the
1210 last item in the list.
1211 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1213 action does the following: If an extended selection has been
1214 made from the current anchor point, restores the selection
1215 state of the items in that range to their state before the
1216 extended selection was done; changes the selection state of
1217 the last item and all items between it and the current anchor
1218 point to the state of the item at the current anchor point;
1219 calls the XmNextendedSelectionCallback callbacks.
1220 ListEndExtend():
1222 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1223 action moves the location cursor to the last item selected or
1224 deselected and calls the XmNextendedSelectionCallback call‐
1225 backs.
1226 If XmNautomaticSelection is set to True, then the auto_selec‐
1228 tion_type field of the callback will be valid. If XmNselec‐
1229 tionPolicy is set to XmBROWSE_SELECT and the currently
1230 selected item position matches the position of the item that
1231 was selected before the browse selection began, or if XmNse‐
1232 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur‐
1233 rently selected item positions matches the set of item posi‐
1234 tions selected before the extended selection began, the call‐
1235 back will be called with auto_selection_type set to
1236 XmAUTO_NO_CHANGE. Otherwise, it will be set to
1237 XmAUTO_CHANGE.
1238 ListEndLine():
1240 Moves the horizontal scroll region to the end of the line.
1241 ListEndSelect():
1243 This action moves the location cursor to the last item
1244 selected or deselected and calls the appropriate selection
1245 callbacks (XmNsingleSelectionCallback when XmNselectionPolicy
1246 is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when
1247 XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSe‐
1248 lectionCallback when XmNselectionPolicy is set to XmMULTI‐
1249 PLE_SELECT, XmNextendedSelectionCallback when XmNselection‐
1250 Policy is set to XmEXTENDED_SELECT).
1251 If XmNautomaticSelection is set to True, then the auto_selec‐
1253 tion_type field of the callback will be valid. If XmNselec‐
1254 tionPolicy is set to XmBROWSE_SELECT and the currently
1255 selected item position matches the position of the item that
1256 was selected before the brose selection began, or if XmNse‐
1257 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur‐
1258 rently selected item positions matches the set of item posi‐
1259 tions selected before the extended selection began, the call‐
1260 back will be called with auto_selection_type set to
1261 XmAUTO_NO_CHANGE. Otherwise, it will be set to
1262 XmAUTO_CHANGE.
1263 ListEndToggle():
1265 If XmNselectionPolicy is set to XmEXTENDED_SELECT, moves the
1266 location cursor to the last item selected or deselected and
1267 calls the XmNextendedSelectionCallback callbacks.
1268 If XmNautomaticSelection is set to True, then the auto_selec‐
1270 tion_type field of the callback will be valid. If XmNselec‐
1271 tionPolicy is set to XmBROWSE_SELECT and the currently
1272 selected item position matches the position of the item that
1273 was selected before the browse selection began, or if XmNse‐
1274 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur‐
1275 rently selected item positions matches the set of item posi‐
1276 tions selected before the extended selection began, the call‐
1277 back will be called with auto_selection_type set to
1278 XmAUTO_NO_CHANGE. Otherwise, it will be set to
1279 XmAUTO_CHANGE.
1280 ListExtendNextItem():
1282 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1283 action does the following: If an extended selection has been
1284 made from the current anchor point, restores the selection
1285 state of the items in that range to their state before the
1286 extended selection was done; moves the location cursor to the
1287 next item and changes the selection state of the item and all
1288 items between it and the current anchor point to the state of
1289 the item at the current anchor point; calls the XmNextendedS‐
1290 electionCallback callbacks.
1291 ListExtendPrevItem():
1293 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1294 action does the following: If an extended selection has been
1295 made from the current anchor point, restores the selection
1296 state of the items in that range to their state before the
1297 extended selection was done; moves the location cursor to the
1298 previous item and changes the selection state of the item and
1299 all items between it and the current anchor point to the
1300 state of the item at the current anchor point; calls the
1301 XmNextendedSelectionCallback callbacks.
1302 ListScrollCursorVertically(percentage):
1304 Scrolls the line containing the insertion cursor vertically
1305 to an intermediate position in the visible window based on an
1306 input percentage. A value of 0 (zero) indicates the top of
1307 the window; a value of 100, the bottom of the window. If this
1308 action is called with no argument, the line containing the
1309 insertion cursor is scrolled vertically to a new position
1310 designated by the y event passed to the routine.
1311 ListKbdActivate():
1313 Calls the callbacks for XmNdefaultActionCallback. If the
1314 List's parent is a manager, this action passes the event to
1315 the parent.
1316 ListKbdBeginExtend():
1318 If XmNselectionPolicy is set to XmEXTENDED_SELECT, does the
1319 following: If an extended selection has been made from the
1320 current anchor point, restores the selection state of the
1321 items in that range to their state before the extended selec‐
1322 tion was done; changes the selection state of the item at the
1323 location cursor and all items between it and the current
1324 anchor point to the state of the item at the current anchor
1325 point. If XmNautomaticSelection is set to True, this action
1326 calls the XmNextendedSelectionCallback callbacks. The
1327 auto_selection_type component of the callback structure will
1328 be set to XmAUTO_BEGIN".
1329 ListKbdBeginSelect():
1331 If the XmNselectionPolicy is set to XmSINGLE_SELECT, dese‐
1332 lects any current selection and toggles the state of the item
1333 at the location cursor. The auto_selection_type component of
1334 the callback structure will be set to XmAUTO_BEGIN".
1335 If the XmNselectionPolicy is set to XmBROWSE_SELECT, dese‐
1337 lects any current selection and selects the item at the loca‐
1338 tion cursor. If XmNautomaticSelection is set to True, calls
1339 the XmNbrowseSelectionCallback callbacks.
1340 If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, tog‐
1342 gles the selection state of the item at the location cursor.
1343 Any previous selections remain.
1344 If the XmNselectionPolicy is set to XmEXTENDED_SELECT, moves
1346 the current anchor to the item at the location cursor. In
1347 Normal Mode, this action deselects any current selection and
1348 selects the item at the location cursor. In Add Mode, this
1349 action toggles the selection state of the item at the loca‐
1350 tion cursor and leaves the current selection unchanged. If
1351 XmNautomaticSelection is set to True, this action calls the
1352 XmNextendedSelectionCallback callbacks. The auto_selec‐
1353 tion_type component of the callback structure will be set to
1354 XmAUTO_BEGIN".
1355 ListKbdCancel():
1357 If XmNselectionPolicy is set to XmEXTENDED_SELECT and an
1358 extended selection is being made from the current anchor
1359 point, this action cancels the new selection and restores the
1360 selection state of the items in that range to their state
1361 before the extended selection was done. If XmNautomaticSe‐
1362 lection is set to True, this action calls the XmNextendedSe‐
1363 lectionCallback callbacks; otherwise, if the parent is a man‐
1364 ager, it passes the event to the parent. The auto_selec‐
1365 tion_type component of the callback structure will be set to
1366 XmAUTO_CANCEL".
1367 ListKbdDeSelectAll():
1369 If the XmNselectionPolicy is set to XmSINGLE_SELECT, XmMULTI‐
1370 PLE_SELECT, or XmEXTENDED_SELECT in Add Mode, this action
1371 deselects all items in the list. If the XmNselectionPolicy
1372 is set to XmEXTENDED_SELECT in Normal Mode, this action dese‐
1373 lects all items in the list (except the item at the location
1374 cursor if the shell's XmNkeyboardFocusPolicy is XmEXPLICIT).
1375 This action also calls the appropriate selection callbacks
1376 (XmNsingleSelectionCallback when XmNselectionPolicy is set to
1377 XmSINGLE_SELECT, XmNmultipleSelectionCallback when XmNselec‐
1378 tionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelection‐
1379 Callback when XmNselectionPolicy is set to XmEX‐
1380 TENDED_SELECT).
1381 ListKbdEndExtend():
1383 If XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1384 action calls the XmNextendedSelectionCallback callbacks.
1385 If XmNautomaticSelection is set to True, then the auto_selec‐
1387 tion_type field of the callback will be valid. If XmNselec‐
1388 tionPolicy is set to XmBROWSE_SELECT and the currently
1389 selected item position matches the position of the item that
1390 was selected before the browse selection began, or if XmNse‐
1391 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur‐
1392 rently selected item positions matches the set of item posi‐
1393 tions selected before the extended selection began, the call‐
1394 back will be called with auto_selection_type set to
1395 XmAUTO_NO_CHANGE. Otherwise, it will be set to
1396 XmAUTO_CHANGE.
1397 ListKbdEndSelect():
1399 Calls the appropriate selection callbacks (XmNsingleSelec‐
1400 tionCallback when XmNselectionPolicy is set to XmSIN‐
1401 GLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPol‐
1402 icy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback
1403 when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNex‐
1404 tendedSelectionCallback when XmNselectionPolicy is set to
1405 XmEXTENDED_SELECT).
1406 If XmNautomaticSelection is set to True, then the auto_selec‐
1408 tion_type field of the callback will be valid. If XmNselec‐
1409 tionPolicy is set to XmBROWSE_SELECT and the currently
1410 selected item position matches the position of the item that
1411 was selected before the browse selection began, or if XmNse‐
1412 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur‐
1413 rently selected item positions matches the set of item posi‐
1414 tions selected before the extended selection began, the call‐
1415 back will be called with auto_selection_type set to
1416 XmAUTO_NO_CHANGE. Otherwise, it will be set to
1417 XmAUTO_CHANGE.
1418 ListKbdSelectAll():
1420 If XmNselectionPolicy is set to XmSINGLE_SELECT or
1421 XmBROWSE_SELECT, this action selects the item at the location
1422 cursor. If XmNselectionPolicy is set to XmEXTENDED_SELECT or
1423 XmMULTIPLE_SELECT, it selects all items in the list. This
1424 action also calls the appropriate selection callbacks (XmNs‐
1425 ingleSelectionCallback when XmNselectionPolicy is set to XmS‐
1426 INGLE_SELECT, XmNbrowseSelectionCallback when XmNselection‐
1427 Policy is set to XmBROWSE_SELECT, XmNmultipleSelectionCall‐
1428 back when XmNselectionPolicy is set to XmMULTIPLE_SELECT,
1429 XmNextendedSelectionCallback when XmNselectionPolicy is set
1430 to XmEXTENDED_SELECT).
1431 ListLeftChar():
1433 Scrolls the list one character to the left.
1434 ListLeftPage():
1436 Scrolls the list one page to the left.
1437 ListNextItem():
1439 Moves the location cursor to the next item in the list.
1440 If the XmNselectionPolicy is set to XmBROWSE_SELECT, this
1442 action also selects the next item, deselects any current
1443 selection, and calls the XmNbrowseSelectionCallback call‐
1444 backs.
1445 If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1447 action in Normal Mode also selects the next item, deselects
1448 any current selection, moves the current anchor to the next
1449 item, and calls the XmNextendedSelectionCallback callbacks.
1450 In Add Mode, this action does not affect the selection or the
1451 anchor.
1452 ListNextPage():
1454 Scrolls the list to the next page, moving the location cursor
1455 to a new item.
1456 If the XmNselectionPolicy is set to XmBROWSE_SELECT, this
1458 action also selects the new item, deselects any current
1459 selection, and calls the XmNbrowseSelectionCallback call‐
1460 backs.
1461 If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1463 action in Normal Mode also selects the new item, deselects
1464 any current selection, moves the current anchor to the new
1465 item, and calls the XmNextendedSelectionCallback callbacks.
1466 In Add Mode, this action does not affect the selection or the
1467 anchor.
1468 ListPrevItem():
1470 Moves the location cursor to the previous item in the list.
1471 If the XmNselectionPolicy is set to XmBROWSE_SELECT, this
1473 action also selects the previous item, deselects any current
1474 selection, and calls the XmNbrowseSelectionCallback call‐
1475 backs.
1476 If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1478 action in Normal Mode also selects the previous item, dese‐
1479 lects any current selection, moves the current anchor to the
1480 previous item, and calls the XmNextendedSelectionCallback
1481 callbacks. In Add Mode, this action does not affect the
1482 selection or the anchor.
1483 ListPrevPage():
1485 Scrolls the list to the previous page, moving the location
1486 cursor to a new item.
1487 If the XmNselectionPolicy is set to XmBROWSE_SELECT, this
1489 action also selects the new item, deselects any current
1490 selection, and calls the XmNbrowseSelectionCallback call‐
1491 backs.
1492 If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this
1494 action in Normal Mode also selects the new item, deselects
1495 any current selection, moves the current anchor to the new
1496 item, and calls the XmNextendedSelectionCallback callbacks.
1497 In Add Mode this action does not affect the selection or the
1498 anchor.
1499 ListProcessBtn1(string)
1501 When Display's XmNenableBtn1Transfer resource is not XmOFF,
1502 the actions for selection and transfer are integrated on
1503 <Btn1>. When the button is not performing a transfer or
1504 drag, the action that is performed depends on the value of
1505 string, which can be one of the following actions:
1506 · ListButtonMotion
1508 · ListBeginExtend
1510 · ListEndExtend
1512 · ListBeginToggle
1514 · ListEndToggle
1516 · ListBeginSelect
1518 · ListEndSelect
1520 ListProcessBtn2
1522 When Display's XmNenableBtn1Transfer resource has a value of
1523 XmBUTTON2_TRANSFER, the actions for extending selection are
1524 bound on <Btn2>, and a drag starts immediately. When Dis‐
1525 play's XmNenableBtn1Transfer resource has a value of XmBUT‐
1526 TON2_ADJUST, the action that is performed depends on the
1527 value of string, which can be one of the following actions:
1528 · ListBeginExtend
1530 · ListButtonMotion
1532 · ListEndExtend
1534 ListProcessDrag():
1536 Drags the content of one or more selected list items. Each
1537 item is separated by a newline. If BTransfer is pressed on
1538 an unselected item, it drags only that item, excluding any
1539 other selected items. This action sets the XmNconvertProc of
1540 the DragContext to a function that calls the XmNconvertCall‐
1541 back procedures, possibly multiple times, for the _MOTIF_DROP
1542 selection.
1543 ListQuickNavigate
1545 Navigates to an item. When List's XmNmatchBehavior resource
1546 is XmQUICK_NAVIGATE, this action uses 1-character navigation
1547 to navigate. Refer to the XmNmatchBehavior resource for a
1548 description of how this navigation works.
1549 ListRightChar():
1551 Scrolls the list one character to the right.
1552 ListRightPage():
1554 Scrolls the list one page to the right.
1555 PrimitiveHelp():
1557 Calls the callbacks for XmNhelpCallback if any exist. If
1558 there are no help callbacks for this widget, this action
1559 calls the help callbacks for the nearest ancestor that has
1560 them.
1561 PrimitiveNextTabGroup():
1563 Moves the focus to the first item contained within the next
1564 tab group. If the current tab group is the last entry in the
1565 tab group list, it wraps to the beginning of the tab group
1566 list.
1567 PrimitivePrevTabGroup():
1569 Moves the focus to the first item contained within the previ‐
1570 ous tab group. If the beginning of the tab group list is
1571 reached, it wraps to the end of the tab group list.
1572 Additional Behavior
1574 The List widget has the following additional behavior:
1575 <Double Click>
1577 If a button click is followed by another button click within
1578 the time span specified by the display's multiclick time, the
1579 List interprets that as a double click and calls the call‐
1580 backs for XmNdefaultActionCallback. The item's colors invert
1581 to indicate that it is selected. The XmNdoubleClickInterval
1582 resource can be used to specify a time span that overrides
1583 the display's multi-click time.
1584 <FocusIn>:
1586 If the focus policy is Explicit, this action sets the focus
1587 and draw the location cursor.
1588 <FocusOut>:
1590 If the focus policy is Explicit, this action removes the
1591 focus and erase the location cursor.
1592 Virtual Bindings
1594 The bindings for virtual keys are vendor specific. For information
1595 about bindings for virtual buttons and keys, see VirtualBindings(3).
1596
1598 Core(3), XmCreateList(3), XmCreateScrolledList(3), XmFontListCreate(3),
1599 XmFontListAppendEntry(3), XmListAddItem(3), XmListAddItems(3), XmLis‐
1600 tAddItemUnselected(3), XmListAddItemsUnselected(3), XmListDeleteAl‐
1601 lItems(3), XmListDeleteItem(3), XmListDeleteItems(3), XmListDeleteItem‐
1602 sPos(3), XmListDeletePos(3), XmListDeletePositions(3), XmListDeselec‐
1603 tAllItems(3), XmListDeselectItem(3), XmListDeselectPos(3), XmListGetKb‐
1604 dItemPos XmListGetMatchPos(3), XmListGetSelectedPos(3), XmListItemEx‐
1605 ists(3), XmListItemPos(3), XmListPosToBounds(3), XmListReplaceItems(3),
1606 XmListReplaceItemsPos(3), XmListReplaceItemsPos(3), XmListReplaceItem‐
1607 sPosUnselected(3), XmListReplaceItemsUnselected(3), XmListSelec‐
1608 tItem(3), XmListSelectPos(3), XmListSetAddMode(3), XmListSetBot‐
1609 tomItem(3), XmListSetBottomPos(3), XmListSetHorizPos(3), XmList‐
1610 SetItem(3), XmListSetKbdItemPos(3), XmListSetPos(3), XmListUpdateSe‐
1611 lectedList(3), XmListYToPos(3), XmPrimitive(3) XmStringCreate(3),
1612 XmVaCreateList(3), and XmVaCreateManagedList(3).
1613 XmList(library call)