XMLIST(3)

📦
version 2.3.8 · 3 versions
, in arch rolling, centos-stream 9, epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

okay bestie, welcome to the XmList(library call) page 💖 this is the manual for the List widget class, and we're gonna get you fluent in it. No cap.

💖 NAME 💖

XmList — The List widget class

✨ SYNOPSIS ✨

#include <Xm/List.h>

🌸 DESCRIPTION 🌸

okay so List lets a user pick one or more items from a group of choices. You can select stuff with the pointer or the keyboard, so pick your vibe. List works on an array of compound strings that the application defines. Each compound string becomes an item in the List: first compound string = item in position 1, second = item in position 2, and so on. periodt.

Specifying the number of items that are visible sets the size of the List. If you don't specify the number of visible items, the height of the list controls how many are visible. Each item takes the height of the tallest element in the list. If you want a list that scrolls easily through a huge number of items, use the XmCreateScrolledList convenience function. iconic.

To select items, move the pointer or cursor to the desired item and press the <Btn1> mouse button or the key defined as <osfSelect>. There are several styles of selection behavior, and they all highlight the selected item(s) by displaying them in inverse colors. An appropriate callback gets invoked to notify the application of the user's choice, and then the app does whatever it needs for that selection. When a List is insensitive, all the list items are displayed in a stippled fill pattern. 💅

List uses the XmQTspecifyRenderTable, XmQTscrollFrame, and XmQTnavigator traits, and holds the XmQTtransfer trait. slay.

🎀 Selection 🎀

Each list has one of four selection models:

  • Single Select
  • Browse Select
  • Multiple Select
  • Extended Select

In Single Select and Browse Select, at most one item is selected at a time. In Single Select, pressing <Btn1> on an item toggles its selection state and deselects any other selected item. In Browse Select, pressing <Btn1> on an item selects it and deselects any other selected item; dragging <Btn1> moves the selection as the pointer is moved. Releasing <Btn1> on an item moves the location cursor to that item.

In Multiple Select, any number of items can be selected at a time. Pressing <Btn1> on an item toggles its selection state but does not deselect any other selected items.

In Extended Select, any number of items can be selected at a time, and the user can easily select ranges of items. Pressing <Btn1> on an item selects it and deselects any other selected item. Dragging <Btn1> or pressing or dragging <Shift><Btn1> following a <Btn1> action selects all items between the item under the pointer and the item on which <Btn1> was pressed. This action also deselects any other selected items outside that range.

Extended Select also lets the user select and deselect discontiguous ranges of items. Pressing <Ctrl><Btn1> on an item toggles its selection state but does not deselect any other selected items. Dragging <Ctrl><Btn1> or pressing or dragging <Shift><Btn1> following a <Ctrl><Btn1> action sets the selection state of all items between the item under the pointer and the item on which <Ctrl><Btn1> was pressed to the state of the item on which <Ctrl><Btn1> was pressed. This action does not deselect any other selected items outside that range.

All selection operations available from the mouse are also available from the keyboard. List has two keyboard selection modes: Normal Mode and Add Mode. In Normal Mode, navigation operations and <osfSelect> select the item at the location cursor and deselect any other selected items. In Add Mode, navigation operations have no effect on selection, and <osfSelect> toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select.

Single and Multiple Select use Add Mode, and Browse Select uses Normal Mode.

Extended Select can use either mode; the user changes modes by pressing <osfAddMode>. In Extended Select Normal Mode, pressing <osfSelect> has the same effect as pressing <Btn1>; <osfExtend> and shifted navigation have the same effect as pressing <Shift><Btn1> following a <Btn1> action. In Extended Select Add Mode, pressing <osfSelect> has the same effect as pressing <Ctrl><Btn1>; <osfExtend> and shifted navigation have the same effect as pressing <Shift><Btn1> following a <Ctrl><Btn1> action.

Normal Mode is indicated by a solid location cursor, and Add Mode is indicated by a dashed location cursor. 👑

🦋 Data Transfer Behavior 🦋

List supports dragging of items from the List and transfer of items to the clipboard. When the user presses BTransfer on a selected item, the widget transfers all selected items. When the user presses BTransfer on an unselected item, the widget transfers only that item. Depending on the value of XmNprimaryOwnership, List can also support primary selection.

When the XmNconvertCallback procedures are called, the location_data member of the XmConvertCallbackStruct member is NULL if the selected items are being transferred. If the selected items are not being transferred, this member has the following value: If a single item is being transferred, the value is an integer representing the position of the item in the List. A value of 1 transfers the first item in the List; a value of 2 transfers the second item; and so on. If the entire contents of the List are being transferred, the value is -1.

As a source of data, List supports the following targets and associated conversions of data to these targets:

  • locale — If the locale target matches the widget's locale, the widget transfers the selected list items in the encoding of the locale. Each item transferred except the last includes a trailing separator.
  • COMPOUND_TEXT — The widget transfers the selected list items as type COMPOUND_TEXT. Each item transferred except the last includes a trailing separator.
  • UTF8_STRING — The widget transfers the selected list items as type UTF8_STRING. Each item transferred except the last includes a trailing separator.
  • STRING — The widget transfers the selected list items as type STRING. Each item transferred except the last includes a trailing separator.
  • TEXT — If the selected list items are fully convertible to the encoding of the locale, the widget transfers the selected list items in the encoding of the locale. Otherwise, the widget transfers the selected list items as type COMPOUND_TEXT. Each item transferred except the last includes a trailing separator.
  • _MOTIF_CLIPBOARD_TARGETS — The widget transfers, as type ATOM, a list of the targets it supports for immediate transfer for the CLIPBOARD selection. These include _MOTIF_COMPOUND_STRING. If the selected list items are fully convertible to STRING, these also include STRING; otherwise, they also include COMPOUND_TEXT and UTF8_STRING.
  • _MOTIF_COMPOUND_STRING — The widget transfers the selected list items as a compound string in Byte Stream format. Each item transferred except the last includes a trailing separator.
  • _MOTIF_DEFERRED_CLIPBOARD_TARGETS — The widget transfers, as type ATOM, a list of the targets it supports for delayed transfer for the CLIPBOARD selection. This widget currently supplies no targets for _MOTIF_DEFERRED_CLIPBOARD_TARGETS.
  • _MOTIF_EXPORT_TARGETS — The widget transfers, as type ATOM, a list of the targets to be used as the value of the DragContext's XmNexportTargets in a drag-and-drop transfer. These include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT, UTF8_STRING, the encoding of the locale, STRING, TEXT, BACKGROUND, and FOREGROUND.
  • _MOTIF_LOSE_SELECTION — When the widget loses the selection, it deselects all list items.

As a source of data, List also supports the following standard Motif targets:

  • BACKGROUND — The widget transfers XmNbackground as type PIXEL.
  • CLASS — The widget finds the first shell in the widget hierarchy that has a WM_CLASS property and transfers the contents as text in the current locale.
  • CLIENT_WINDOW — The widget finds the first shell in the widget hierarchy and transfers its window as type WINDOW.
  • COLORMAP — The widget transfers XmNcolormap as type COLORMAP.
  • FOREGROUND — The widget transfers XmNforeground as type PIXEL.
  • NAME — The widget finds the first shell in the widget hierarchy that has a WM_NAME property and transfers the contents as text in the current locale.
  • TARGETS — The widget transfers, as type ATOM, a list of the targets it supports. These include the standard targets in this list. These also include _MOTIF_COMPOUND_STRING, COMPOUND_TEXT, UTF8_STRING the encoding of the locale, STRING, and TEXT.
  • TIMESTAMP — The widget transfers the timestamp used to acquire the selection as type INTEGER.
  • _MOTIF_RENDER_TABLE — The widget transfers XmNrenderTable if it exists, or else the default text render table, as type STRING.
  • _MOTIF_ENCODING_REGISTRY — The widget transfers its encoding registry as type STRING. The value is a list of NULL separated items in the form of tag encoding pairs. This target symbolizes the transfer target for the Motif Segment Encoding Registry. Widgets and applications can use this Registry to register text encoding formats for specified render table tags. Applications access this Registry by calling XmRegisterSegmentEncoding and XmMapSegmentEncoding.

List has no widget class destination procedure. Subclasses and the XmNdestinationCallback procedures are responsible for any data transfers to the widget. no cap.

🌈 Classes 🌈

List inherits behavior, resources, and traits from Core and XmPrimitive.

The class pointer is xmListWidgetClass.

The class name is XmList.

✨ New Resources ✨

okay bestie, this is the part where we meet the resources 👑 — the table below defines a whole set of widget resources that you, the programmer, use to specify data. it's giving "choose your own adventure" but make it X11 💅

and here's the cute part: you can also set the resource values on the inherited classes, and that way you're setting attributes for this widget too. slay, inheritance ate fr fr 🧬✨

🌸 how to talk about them in your .Xdefaults 🌸

so if you wanna reference a resource by name or by class inside a .Xdefaults file, here's the move:

  • 🎀 drop the XmN or XmC prefix
  • 🎀 keep the remaining letters, that's your reference

and if you wanna specify one of the defined values for a resource in that same .Xdefaults file?

  • 🦋 drop the Xm prefix
  • 🦋 use the remaining letters — in either lowercase or uppercase, dealer's choice, no cap — but keep any underscores that live between the words. don't you dare ghost the underscores 🙈

💀 the access column (iykyk)

the codes in the access column are basically the vibe check for each resource, telling you what you're allowed to do with it:

  • C — you can set it at creation time 🍼
  • S — you can set it using XtSetValues ✍️
  • G — you can retrieve it using XtGetValues 👀
  • N/A — not applicable, it's just not that girl 💀

periodt. now go forth and read that table like the main character you are 🌈⭐

okay bestie the resource set is giving ✨full course meal✨ so let's go item by item, every single one, no skips 💅

  • XmNautomaticSelection — class XmCAutomaticSelection, type XtEnum, default False, access CSG
  • XmNbrowseSelectionCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNdefaultActionCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNdestinationCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNdoubleClickInterval — class XmCDoubleClickInterval, type int, default dynamic, access CSG
  • XmNextendedSelectionCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNfontList — class XmCFontList, type XmFontList, default dynamic, access CSG
  • XmNitemCount — class XmCItemCount, type int, default 0, access CSG
  • XmNitems — class XmCItems, type XmStringTable, default NULL, access CSG
  • XmNlistMarginHeight — class XmCListMarginHeight, type Dimension, default 0, access CSG
  • XmNlistMarginWidth — class XmCListMarginWidth, type Dimension, default 0, access CSG
  • XmNlistSizePolicy — class XmCListSizePolicy, type unsigned char, default XmVARIABLE, access CG
  • XmNlistSpacing — class XmCListSpacing, type Dimension, default 0, access CSG
  • XmNmatchBehavior — class XmCMatchBehavior, type unsigned char, default XmQUICK_NAVIGATE, access CSG
  • XmNmultipleSelectionCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNprimaryOwnership — class XmCPrimaryOwnership, type unsigned char, default XmOWN_NEVER, access CSG
  • XmNrenderTable — class XmCRenderTable, type XmRenderTable, default dynamic, access CSG
  • XmNscrollBarDisplayPolicy — class XmCScrollBarDisplayPolicy, type unsigned char, default XmAS_NEEDED, access CSG
  • XmNselectColor — class XmCSelectColor, type XmRSelectColor, default XmREVERSED_GROUND_COLORS, access CSG
  • XmNselectedItemCount — class XmCSelectedItemCount, type int, default 0, access CSG
  • XmNselectedItems — class XmCSelectedItems, type XmStringTable, default NULL, access CSG
  • XmNselectedPositionCount — class XmCSelectedPositionCount, type int, default 0, access CSG
  • XmNselectedPositions — class XmCSelectedPositions, type unsigned int *, default NULL, access CSG
fr fr keep scrolling, the list is longer than my skincare routine 🫶
  • XmNselectionMode — class XmCSelectionMode, type unsigned char, default dynamic, access CSG 💅
  • XmNselectionPolicy — class XmCSelectionPolicy, type unsigned char, default XmBROWSE_SELECT, access CSG 💅
  • XmNsingleSelectionCallback — class XmCCallback, type XtCallbackList, default NULL, access C 💅
  • XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CSG 💅
  • XmNtopItemPosition — class XmCTopItemPosition, type int, default 1, access CSG 💅
  • XmNvisibleItemCount — class XmCVisibleItemCount, type int, default dynamic, access CSG 💅

XmNautomaticSelection — okay so this one is a whole vibe. It invokes either XmNbrowseSelectionCallback or XmNextendedSelectionCallback when <Btn1> is pressed, and the items that show up as selected change — but ONLY if the value is True (or XmAUTO) and the selection mode is XmBROWSE_SELECT or XmEXTENDED_SELECT respectively. If it's False (XmNO_AUTO_SELECT), no selection callbacks fire at all until the user actually lets go of the mouse button. Wanna know how this resource plays with the selection modes? Go read Behavior, bestie, the details live there. 🫶

XmNbrowseSelectionCallback — a list of callbacks that gets called when an item is selected in the browse selection mode. The reason is XmCR_BROWSE_SELECT. ✨

XmNdefaultActionCallback — a list of callbacks that gets called when an item is double clicked, or when <osfActivate> is pressed. The reason is XmCR_DEFAULT_ACTION. 💥

XmNdestinationCallback — a list of callbacks called when the List is the destination of a transfer operation. The type of the structure whose address gets passed to these callbacks is XmDestinationCallbackStruct. The reason is XmCR_OK. 🎀

XmNdoubleClickInterval — if one button click is followed by another button click inside the time span this resource specifies (in milliseconds), the two clicks count as a double-click action instead of two separate single-click actions. The value must not be negative. The default value is the display's multiclick time. ⏱️

XmNextendedSelectionCallback — a list of callbacks that gets called when items are selected using the extended selection mode. The reason is XmCR_EXTENDED_SELECT. 🌈

XmNfontList — the font list associated with the list items. Heads up though: XmNfontList is obsolete and exists only for compatibility with previous releases. You should now use XmNrenderTable instead of XmNfontList. If you specify both, the render table takes precedence. The font list gets used together with the XmNvisibleItemCount resource to figure out the height of the List widget. If this value is NULL at initialization, the parent hierarchy of the widget gets searched for a widget holding the XmQTspecifyRenderTable trait. If such an ancestor is found, the font list is initialized to the XmTEXT_RENDER_TABLE value of that ancestor widget. If no such widget is found, the default is implementation dependent. For more on a font list structure, go check XmFontList(3). 📚

XmNitemCount — the total number of items. The value must be the number of items in XmNitems and must not be negative. It's automatically updated by the list whenever an item is added to or deleted from the list. 🔢

XmNitems — points to an array of compound strings that are to be displayed as the list items. For more on the creation and structure of compound strings, see XmString(3). Careful bestie: XtGetValues for this resource returns the list items themselves, not a copy of them. The application must not free the returned items. 🚨

XmNlistMarginHeight — the height of the margin between the list border and the items. 📏

XmNlistMarginWidth — the width of the margin between the list border and the items. 📐

XmNlistSizePolicy — controls how the List reacts when an item grows horizontally beyond the current size of the list work area.

  • If the value is XmCONSTANT, the list viewing area does not grow, and a horizontal ScrollBar gets added for a List whose parent is a ScrolledWindow.
  • If this resource is set to XmVARIABLE, the List grows to match the size of the longest item, and no horizontal ScrollBar appears.
  • When the value is XmRESIZE_IF_POSSIBLE, the List attempts to grow or shrink to match the width of the widest item. If it can't grow to match the widest size, a horizontal ScrollBar gets added for a List whose parent is a ScrolledWindow if the longest item is wider than the list viewing area.
The size policy must be set at the time the List widget is created. It cannot be changed later through XtSetValues. Periodt. 💅

XmNlistSpacing — the spacing between list items. This spacing increases by the value of the XmNhighlightThickness resource in Primitive. 📐

XmNmatchBehavior — the matching behavior that XmList follows. The current values are XmNONE and XmQUICK_NAVIGATE, like this:

  • XmNONE — means the typed-in characters are ignored. 🙈
  • XmQUICK_NAVIGATE — means 1-character navigation shall be supported when List has focus. If the typed character is the initial character of some set of items in List, the first of those items following the current item will be navigated to (it becomes the current item). If all such items precede the current item, the first such item becomes the current item. After that, typing the same character again cyclically navigates among the items with the same first character. 🔄

XmNmultipleSelectionCallback — a list of callbacks that gets called when an item is selected in multiple selection mode. The reason is XmCR_MULTIPLE_SELECT. 🌸

XmNprimaryOwnership — specifies whether XmContainer takes ownership of the Primary selection when a selection is made inside it. This resource can take the following values:

  • XmOWN_NEVER — never takes ownership. 🚫
  • XmOWN_ALWAYS — always takes ownership. 👑
  • XmOWN_MULTIPLE — only takes ownership if more than one element has been selected.
  • XmOWN_POSSIBLE_MULTIPLE — only takes ownership if more than one element can be selected at a time.

XmNrenderTable — the render table associated with the list items. The render table is used together with the XmNvisibleItemCount resource to determine the height of the List widget. If this value is NULL at initialization, List searches its parent hierarchy for a widget holding the XmQTspecifyRenderTable trait. If such an ancestor is found, the render table is initialized to the XmTEXT_RENDER_TABLE value of that ancestor widget. If no such widget is found, the default is implementation dependent. If a font list and a render table are both specified, the render table takes precedence. For more on the creation and structure of a render table, go see XmRenderTable(3). 🦋

  • XmNscrollBarDisplayPolicy — this one's the boss of the vertical ScrollBars in a List whose parent is a ScrolledWindow. ✨ When it's set to XmAS_NEEDED, a vertical ScrollBar only shows up when the number of items in the List is bigger than the number of visible items (so like… only when there's actually stuff hiding 👀). When it's XmSTATIC, that vertical ScrollBar is always there, no matter what. Periodt.
  • XmNselectColor — lets the application pick the color of the background rectangle that shows off which text is selected. It takes two values:
    • XmDEFAULT_SELECT_COLOR — makes the select color land somewhere between the background color and the bottom shadow color. Cute little in-between moment. 🎀
    • XmREVERSED_GROUND_COLORS — forces the select color to be the foreground color, and forces the color of any text drawn on top of the select color to be the background color. Full swap energy. 🔄
    • HIGHLIGHT_COLOR — forces the fill color to use the highlight color. That's it, that's the whole vibe. 💅
  • XmNselectedItemCount — says how many strings live in the selected items list. The value has to be the number of items in XmNselectedItems, and bestie it must not be negative. 🙅
  • XmNselectedItems — points to an array of compound strings representing the list items that are currently selected, whether the user did it or the application did it. XtGetValues on this resource hands you back the list items themselves, not a copy of them — so the application must not free the returned items or the array. Do not touch, do not free, we don't do that here. 💀

Setting XmNselectedItems selects those list items that exactly match items in the given XmNselectedItems list. There may be extra items sitting in XmNselectedItems that don't match anything in the list — and those just chill there until XmNselectedItems gets updated. And if XmNitems changes so the list now contains items matching those previously unmatched entries in XmNselectedItems, those new items will show up selected too. Surprise selection, love that for them. 🦋

Any user interaction with the list that causes at least one item to be selected or deselected, plus any call to XmListDeleteAllItems, XmListDeleteItem, XmListDeleteItems, XmListDeleteItemsPos, XmListDeletePos, XmListDeletePositions, XmListDeselectAllItems, XmListDeselectItem, XmListDeselectPos, XmListSelectItem, XmListSelectPos, or XmListUpdateSelectedList, causes XmNselectedItems to be updated immediately so it exactly reflects the visual state of the list. Calls to any other XmList functions do not affect XmNselectedItems. That's the whole list, no extras, no cap. 🔥

  • XmNselectedPositionCount — says how many positions are in the selected positions list. The value must be the number of items in XmNselectedPositions. (Yes, the original sentence just ends right there, we're not adding punctuation to the source material, we're just respecting the bit. ✨)
  • XmNselectedPositions — points to an array of the positions of the selected items in the List. XtGetValues on this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items or the array. Same rule as before, bestie — hands off. 🙈
  • XmNselectionMode — defines what effect keyboard navigations have on selection. The valid modes are:
    • XmADD_MODE — allows no navigation operations to have any effect on selection, and <osfSelect> toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select. But the widget cannot be put into add mode if the XmNselectionPolicy resource is an incompatible mode (XmNselectionPolicy cannot be XmBROWSE_SELECT). So check your policy first, okay? 👑
    • XmNORMAL_MODE — allows navigation operations and <osfSelect> to select the item at the location cursor and deselect any other selected items. But the widget cannot be put into normal mode if the XmNselectionPolicy resource is an incompatible mode (XmNselectionPolicy cannot be XmSINGLE_SELECT or XmMULTIPLE_SELECT). Same energy, different vibes. 💜
  • XmNselectionPolicy — defines the interpretation of the selection action. This can be one of the following:
    • XmSINGLE_SELECT — allows only single selections. One and done. 🎀
    • XmMULTIPLE_SELECT — allows multiple selections. Collect them all. 🌸
    • XmEXTENDED_SELECT — allows extended selections. Go long, go wide. 🌈
    • XmBROWSE_SELECT — allows drag-and-browse functionality. Scroll and snoop. 🦋
  • XmNsingleSelectionCallback — specifies a list of callbacks that gets called when an item is selected in single selection mode. The reason is XmCR_SINGLE_SELECT. ✨
  • XmNstringDirection — a synthetic resource for setting XmNlayoutDirection. The values for this resource are XmSTRING_DIRECTION_L_TO_R and XmSTRING_DIRECTION_R_TO_L. Peep the XmNlayoutDirection resource description for the full story. Lowkey important: XmNstringDirection is obsoleted by XmNlayoutDirection, but it's kept here for backward compatibility. Elder resource, still in the group chat. 🫶
  • XmNtopItemPosition — specifies the position of the item that is the first visible item in the list. Setting this resource is equivalent to calling the XmListSetPos function. The position of the first item in the list is 1; the position of the second item is 2; and so on. A position of 0 (zero) specifies the last item in the list. The value must not be negative. Counting starts at one, bestie, don't @ me. 💅
  • XmNvisibleItemCount — specifies the number of items that can fit in the visible space of the list work area. The List uses this value to determine its height. The value must be greater than 0 (zero). Zero is not it. 🔥

Inherited Resources

List inherits behavior and resources from the superclasses described in the following tables. For a complete description of each resource, refer to the reference page for that superclass. 👑

🎀 The XmPrimitive Resource Set 🎀

okay bestie, deep breath, because here comes the entire XmPrimitive resource lineup 💅 every widget in the XmPrimitive family rocks this exact set, and I am not skipping a single one — we are doing all of them, no cap. ✨

For each one you're getting the resource name, its class, its type, its default, and its access code. That's the whole vibe. Periodt. 🫶

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default is dynamic, access CSG. 💖
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default is XmUNSPECIFIED_PIXMAP, access CSG. 🎀
  • XmNconvertCallback — class XmCCallback, type XtCallbackList, default is NULL, access C. ✨
  • XmNforeground — class XmCForeground, type Pixel, default is dynamic, access CSG. 🌸
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default is NULL, access C. 🦋
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default is dynamic, access CSG. 💜
  • XmNhighlightOnEnter — class XmCHighlightOnEnter, type Boolean, default is False, access CSG. 🌈
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default is dynamic, access CSG. ⭐
  • XmNhighlightThickness — class XmCHighlightThickness, type Dimension, default is 2, access CSG. 🎀
  • XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default is dynamic, access CG. 👑
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default is XmTAB_GROUP, access CSG. 🔥
  • XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default is NULL, access C. 🙈
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default is 2, access CSG. 🍓
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default is dynamic, access CSG. 💖
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default is dynamic, access CSG. 🧚
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default is True, access CSG. ✨
  • XmNunitType — class XmCUnitType, type unsigned char, default is dynamic, access CSG. 🌸
  • XmNuserData — class XmCUserData, type XtPointer, default is NULL, access CSG. 💅

and yes, that's literally every single one — I counted twice, you're welcome. 💀

heads up bestie: watch the access codes, they're not all the same! CG and CSG are not interchangeable, and the ones marked C are a whole different lane. 👀

💖 Core Resource Set 💖

okay bestie, this is the whole core resource lineup, fr fr. every single one, no skipping, we're eating today 👑

  • XmNaccelerators — class XmCAccelerators, type XtAccelerators, default dynamic, access CSG
  • XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access G
  • XmNbackground — class XmCBackground, type Pixel, default dynamic, access CSG
  • XmNbackgroundPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderColor — class XmCBorderColor, type Pixel, default XtDefaultForeground, access CSG
  • XmNborderPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNborderWidth — class XmCBorderWidth, type Dimension, default 0, access CSG
  • XmNcolormap — class XmCColormap, type Colormap, default dynamic, access CG
  • XmNdepth — class XmCDepth, type int, default dynamic, access CG
  • XmNdestroyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNheight — class XmCHeight, type Dimension, default dynamic, access CSG
  • XmNinitialResourcesPersistent — class XmCInitialResourcesPersistent, type Boolean, default True, access C
  • XmNmappedWhenManaged — class XmCMappedWhenManaged, type Boolean, default True, access CSG
  • XmNscreen — class XmCScreen, type Screen *, default dynamic, access CG
  • XmNsensitive — class XmCSensitive, type Boolean, default True, access CSG
  • XmNtranslations — class XmCTranslations, type XtTranslations, default dynamic, access CSG
  • XmNwidth — class XmCWidth, type Dimension, default dynamic, access CSG
  • XmNx — class XmCPosition, type Position, default 0, access CSG
  • XmNy — class XmCPosition, type Position, default 0, access CSG

✨ Callback Information ✨

List defines a brand new callback structure, bestie, it's giving ✨new era✨. the way this works is: your app has to look at the reason field first, and only touch the struct members that are actually valid for that particular reason — because not every field is relevant for every possible reason, and reaching for the wrong one is not the vibe 😭. the callback structure is defined like this:

typedef struct
{
        int reason;
        XEvent *event;
        XmString item;
        int item_length;
        int item_position;
        XmString *selected_items;
        int selected_item_count;
        int *selected_item_positions;
        char selection_type;
        unsigned char auto_selection_type;
} XmListCallbackStruct;
  • reason — spills the tea on why the callback was invoked 👀
  • event — points at the XEvent that triggered the callback. it can be NULL, so like... check it, bestie.
  • item — the last item that got selected at the time of the event that caused the callback. heads up tho: item points to a temporary storage space that gets reused the second the callback is done. so if your app needs to keep the item around, it has to copy it into its own data space. no cap, it will not wait for you 🙈
  • item_length — the length in bytes of item. this member is obsolete and only exists for compatibility with earlier releases (it's giving legacy, we still love her 💅)

okay so, picking up right where we left off:

  • item_position — the position (plus one) of item in the List's XmNitems array. An item_position value of one means it's the first element in the list. periodt. 💅
  • selected_items — a list of items that were selected at the time of the event that caused the callback. It points to temporary storage that gets reused after the callback is finished. So if your app needs to save that selected list, copy it into its own data space, bestie. no cap. 🫶
  • selected_item_count — the number of items in the selected_items list. This number must be non-negative.
  • selected_item_positions — an array of integers, one for each selected item, showing the position of each selected item in the List's XmNitems array. It points to temporary storage that gets reused after the callback is finished. So if your app needs to save this array, copy it into its own data space. 💖
  • selection_type — tells you that the most recent extended selection was the initial selection (XmINITIAL), a modification of an existing selection (XmMODIFICATION), or an additional noncontiguous selection (XmADDITION).
  • auto_selection_type — indicates the type of automatic selection callback. The types include:
    • XmAUTO_BEGIN — the beginning of automatic selection.
    • XmAUTO_MOTION — there's a button drag selection.
    • XmAUTO_CANCEL — the new selection is cancelled.
    • XmAUTO_NO_CHANGE — the currently selected item matches the initial item.
    • XmAUTO_CHANGE — the currently selected item does not match the initial item.

The following table describes the reasons for which the individual callback structure fields are valid. Here's the breakdown, no cap:

  • XmCR_SINGLE_SELECT — valid fields: reason, event, item, item_length, item_position
  • XmCR_DEFAULT_ACTION — valid fields: reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions
  • XmCR_BROWSE_SELECT — valid fields: reason, event, item, item_length, item_position
  • XmCR_MULTIPLE_SELECT — valid fields: reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions
  • XmCR_EXTENDED_SELECT — valid fields: reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions, selection_type

A pointer to the following callback structure is passed to the XmNdestinationCallback procedures:

typedef struct
{
        int reason;
        XEvent *event;
        Atom selection;
        XtEnum operation;
        int flags;
        XtPointer transfer_id;
        XtPointer destination_data;
        XtPointer location_data;
        Time time;
} XmDestinationCallbackStruct;
  • reason — indicates why the callback was invoked.
  • event — points to the XEvent that triggered the callback. It can be NULL.
  • selection — indicates the selection for which data transfer is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP.
  • operation — indicates the type of transfer operation requested.
    • When the selection is PRIMARY, possible values are XmMOVE, XmCOPY, and XmLINK.
    • When the selection is SECONDARY or CLIPBOARD, possible values are XmCOPY and XmLINK.
    • When the selection is _MOTIF_DROP, possible values are XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of XmOTHER means that the callback procedure must get further information from the XmDropProcCallbackStruct in the destination_data member.
  • flags — indicates whether or not the destination widget is also the source of the data to be transferred. Following are the possible values:
    • XmCONVERTING_NONE — the destination widget is not the source of the data to be transferred.
    • XmCONVERTING_SAME — the destination widget is the source of the data to be transferred.
  • transfer_id — serves as a unique ID to identify the transfer transaction.
  • destination_data — contains information about the destination. When the selection is _MOTIF_DROP, the callback procedures are called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. When the selection is SECONDARY, destination_data is an Atom representing a target recommended by the selection owner for use in converting the selection. Otherwise, destination_data is NULL.
  • location_data — contains information about the location where data is to be transferred. The value is always NULL when the selection is SECONDARY or CLIPBOARD. If the value is NULL, the data is to be inserted at the widget's cursor position. Otherwise, the value is an integer representing the position in the List where the items are to be transferred. A value of 1 makes the first new item the first item in the list; a value of 2 makes it the second item; and so on. Once XmTransferDone procedures start to be called, location_data will no longer be stable.
  • time — indicates the time when the transfer operation began.

✨ Translations ✨

XmList includes translations from Primitive. The XmList translations are described in the following list.

The following key names are listed in the X standard key event translation table syntax. This format is the one used by Motif to specify the widget actions corresponding to a given key. A brief overview of the format is provided under VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation.

  • <Btn1><Motion>: — ListButtonMotion() 🦋
  • s ∼m ∼a <Btn1Down>: — ListBeginExtend()
  • s ∼m ∼a <Btn1Up>: — ListEndExtend()
  • c ∼s ∼m ∼a <Btn1Down>: — ListBeginToggle()
  • c ∼s ∼m ∼a <Btn1Up>: — ListEndToggle()
  • ∼s ∼c ∼m ∼a <Btn1Down>: — ListBeginSelect()
  • ∼s ∼c ∼m ∼a <Btn1Up>: — ListEndSelect()
  • <Btn2Down>: — ListProcessDrag() 🌸
  • :s c <Key><osfBeginLine>: — ListBeginDataExtend()
  • :c <Key><osfBeginLine>: — ListBeginData()
  • :<Key><osfBeginLine>: — ListBeginLine()
  • :s c <Key><osfEndLine>: — ListEndDataExtend()
  • :c <Key><osfEndLine>: — ListEndData()
  • :<Key><osfEndLine>: — ListEndLine()
  • :<Key><osfPageLeft>: — ListLeftPage()
  • :c <Key><osfPageUp>: — ListLeftPage()
  • :<Key><osfPageUp>: — ListPrevPage()
  • :<Key><osfPageRight>: — ListRightPage()
  • :c <Key><osfPageDown>: — ListRightPage()
  • :<Key><osfPageDown>: — ListNextPage() 💫
  • s <KeyDown><osfSelect>: — ListKbdBeginExtend()
  • :<KeyDown><osfSelect>: — ListKbdBeginSelect()
  • :s <KeyUp><osfSelect>: — ListKbdEndExtend()
  • :<KeyUp><osfSelect>: — ListKbdEndSelect()
  • :<Key><osfSelectAll>: — ListKbdSelectAll()
  • :<Key><osfDeselectAll>: — ListKbdDeSelectAll()
  • :<Key><osfActivate>: — ListKbdActivate()
  • :<Key><osfAddMode>: — ListAddMode()
  • :<Key><osfHelp>: — PrimitiveHelp() 🎀
  • :<Key><osfCancel>: — ListKbdCancel()
  • :c <Key><osfLeft>: — ListLeftPage()
  • :<Key><osfLeft>: — ListLeftChar()
  • :c <Key><osfRight>: — ListRightPage()
  • :<Key><osfRight>: — ListRightChar()
  • :s <Key><osfUp>: — ListExtendPrevItem()
  • :<Key><osfUp>: — ListPrevItem()
  • :s <Key><osfDown>: — ListExtendNextItem()
  • :<Key><osfDown>: — ListNextItem() 🔥
  • :c <Key><osfInsert>: — ListCopyToClipboard()
  • :<Key><osfCopy>: — ListCopyToClipboard() ✨
  • ∼s c ∼m ∼a <Key>slash — ListKbdSelectAll()
  • ∼s c ∼m ∼a <Key>backslash — ListKbdDeSelectAll()
  • s ∼m ∼a <Key>Tab — PrimitivePrevTabGroup()
  • ∼m ∼a <Key>Tab — PrimitiveNextTabGroup()
  • ∼s ∼m ∼a <Key>Return — ListKbdActivate()
  • ∼s ∼m ∼a <KeyDown>space — ListKbdBeginSelect()
  • ∼s ∼m ∼a <KeyUp>space — ListKbdEndSelect()
  • s ∼m ∼a <KeyDown>space — ListKbdBeginExtend()
  • s ∼m ∼a <KeyUp>space — ListKbdEndExtend()
  • <Key> — ListQuickNavigate()

okay so plot twist: all of those List button event translations get modified when Display's XmNenableBtn1Transfer resource does not have a value of XmOFF — like, in other words, when it's either XmBUTTON2_TRANSFER or XmBUTTON2_ADJUST. 🫶 This option lets the actions for selection and transfer get integrated onto <Btn1>, and lets the extending-the-selection actions get bound to <Btn2>. The <Btn1> actions defined up above still apply whenever the <Btn1> event happens over text that is not selected. But the following actions kick in when the <Btn1> event happens over text that is selected:

  • <Btn1Motion> — ListProcessBtn1(ListButtonMotion)
  • s ∼m ∼a <Btn1Down> — ListProcessBtn1(ListBeginExtend)
  • s ∼m ∼a <Btn1Up> — ListProcessBtn1(ListEndExtend)
  • c ∼s ∼m ∼a <Btn1Down> — ListProcessBtn1(ListBeginToggle)
  • c ∼s ∼m ∼a <Btn1Up> — ListProcessBtn1(ListEndToggle)
  • ∼s ∼c ∼m ∼a <Btn1Down> — ListProcessBtn1(ListBeginSelect)
  • ∼s ∼c ∼m ∼a <Btn1Up> — ListProcessBtn1(ListEndSelect)

And when Display's XmNenableBtn1Transfer resource has a value of XmBUTTON2_ADJUST, these actions apply:

  • <Btn2Down> — ListProcessBtn2(ListBeginExtend)
  • <Btn2Motion> — ListProcessBtn2(ListButtonMotion)
  • <Btn2Up> — ListProcessBtn2(ListEndExtend)

🎬 Action Routines 🎬

The XmList action routines are all described in the list below. Heads up bestie: the current selection is always shown with inverted colors. 💅

  • ListAddMode() — Toggles the state of Add Mode for keyboard selection.
  • ListBeginData() — Moves the location cursor to the first item in the list. In Normal Mode, this also deselects any current selection, selects the first item in the list, and calls the appropriate selection callbacks (XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).
  • ListBeginDataExtend() —
    • If XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEXTENDED_SELECT, this action moves the location cursor to the first item in the list.
    • If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; changes the selection state of the first item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the XmNextendedSelectionCallback callbacks.
  • ListBeginExtend() — If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done, and changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point. If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.
  • ListBeginLine() — Moves the horizontal scroll region to the beginning of the line.
  • ListBeginSelect() — literally four different vibes depending on your policy:
    • If XmNselectionPolicy is set to XmSINGLE_SELECT, deselects any current selection and toggles the selection state of the item under the pointer.
    • If XmNselectionPolicy is set to XmBROWSE_SELECT, deselects any current selection and selects the item under the pointer. If XmNautomaticSelection is set to True, calls the XmNbrowseSelectionCallback callbacks. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.
    • If XmNselectionPolicy is set to XmMULTIPLE_SELECT, toggles the selection state of the item under the pointer. Any previous selections remain.
    • If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action deselects any current selection, selects the item under the pointer, and sets the current anchor at that item. If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.
  • ListBeginToggle() — If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action moves the current anchor to the item under the pointer without changing the current selection. If the item is unselected, this action selects it; if the item is selected, this action unselects it. If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks.

Otherwise, the list takes keyboard focus. No other action occurs. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.

  • ListButtonMotion() —
    • If XmNselectionPolicy is set to XmBROWSE_SELECT, this action deselects any current selection and selects the item under the pointer. If XmNautomaticSelection is set to True and the pointer has entered a new list item, this action calls the XmNbrowseSelectionCallback callbacks.
    • If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: If an extended selection is being made and an extended selection has previously been made from the current anchor point, restores the selection state of the items in that range to their state before the previous extended selection was done and changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point. If XmNautomaticSelection is set to True and the pointer has entered a new list item, calls the XmNextendedSelectionCallback callbacks.
    • If the pointer leaves a scrolled list, this action scrolls the list in the direction of the pointer motion. The auto_selection_type component of the callback structure will be set to XmAUTO_MOTION.
  • ListCopyToClipboard() — Copies the content of the selected items to the clipboard as a single compound string with each item separated by a newline. This action calls the XmNconvertCallback procedures, possibly multiple times, for the CLIPBOARD selection. 🎀
  • ListEndData() — Moves the location cursor to the last item in the list. In Normal Mode, this also deselects any current selection, selects the last item in the list, and calls the appropriate selection callbacks (XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).
  • ListEndDataExtend() —
    • If XmNselectionPolicy is set to XmMULTIPLE_SELECT or XmEXTENDED_SELECT, this action moves the location cursor to the last item in the list.
    • If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; changes the selection state of the last item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the XmNextendedSelectionCallback callbacks.
  • ListEndExtend() — If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action moves the location cursor to the last item selected or deselected and calls the XmNextendedSelectionCallback callbacks.

If XmNautomaticSelection is set to True, then the auto_selection_type field of the callback will be valid. If XmNselectionPolicy is set to XmBROWSE_SELECT and the currently selected item position matches the position of the item that was selected before the browse selection began, or if XmNselectionPolicy is set to XmEXTENDED_SELECT and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with auto_selection_type set to XmAUTO_NO_CHANGE. Otherwise, it will be set to XmAUTO_CHANGE.

  • ListEndLine() — Moves the horizontal scroll region to the end of the line.
  • ListEndSelect() — This action moves the location cursor to the last item selected or deselected and calls the appropriate selection callbacks (XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT).

ListEndToggle() 🌸

  • If XmNselectionPolicy is set to XmEXTENDED_SELECT, it moves the location cursor to the last item selected or deselected and calls the XmNextendedSelectionCallback callbacks.
  • If XmNautomaticSelection is set to True, then the auto_selection_type field of the callback will be valid. If XmNselectionPolicy is set to XmBROWSE_SELECT and the currently selected item position matches the position of the item that was selected before the browse selection began, or if XmNselectionPolicy is set to XmEXTENDED_SELECT and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with auto_selection_type set to XmAUTO_NO_CHANGE. Otherwise, it will be set to XmAUTO_CHANGE.

ListExtendNextItem() ✨

If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: if an extended selection has been made from the current anchor point, it restores the selection state of the items in that range to their state before the extended selection was done; then it moves the location cursor to the next item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point; and then it calls the XmNextendedSelectionCallback callbacks.

ListExtendPrevItem() 🦋

If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action does the following: if an extended selection has been made from the current anchor point, it restores the selection state of the items in that range to their state before the extended selection was done; then it moves the location cursor to the previous item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point; and then it calls the XmNextendedSelectionCallback callbacks.

ListScrollCursorVertically(percentage) 🌈

Scrolls the line containing the insertion cursor vertically to an intermediate position in the visible window, based on an input percentage. A value of 0 (zero) means the top of the window; a value of 100 means the bottom of the window. And if this action gets called with no argument at all, then the line containing the insertion cursor gets scrolled vertically to a new position designated by the y event passed to the routine. 💅

ListKbdActivate() 🔥

Calls the callbacks for XmNdefaultActionCallback. And if the List's parent is a manager, this action passes the event to the parent.

ListKbdBeginExtend() 🎀

If XmNselectionPolicy is set to XmEXTENDED_SELECT, it does the following: if an extended selection has been made from the current anchor point, it restores the selection state of the items in that range to their state before the extended selection was done; then it changes the selection state of the item at the location cursor and all items between it and the current anchor point to the state of the item at the current anchor point.

If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.

ListKbdBeginSelect() 💖

Depends on your policy, bestie. Pick your lane:

  • If the XmNselectionPolicy is set to XmSINGLE_SELECT, it deselects any current selection and toggles the state of the item at the location cursor. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.
  • If the XmNselectionPolicy is set to XmBROWSE_SELECT, it deselects any current selection and selects the item at the location cursor. If XmNautomaticSelection is set to True, it calls the XmNbrowseSelectionCallback callbacks.
  • If the XmNselectionPolicy is set to XmMULTIPLE_SELECT, it toggles the selection state of the item at the location cursor. Any previous selections remain — no wiping the slate.
  • If the XmNselectionPolicy is set to XmEXTENDED_SELECT, it moves the current anchor to the item at the location cursor. In Normal Mode, this action deselects any current selection and selects the item at the location cursor. In Add Mode, this action toggles the selection state of the item at the location cursor and leaves the current selection unchanged. If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks. The auto_selection_type component of the callback structure will be set to XmAUTO_BEGIN.

ListKbdCancel() 🙈

If XmNselectionPolicy is set to XmEXTENDED_SELECT and an extended selection is being made from the current anchor point, this action cancels the new selection and restores the selection state of the items in that range to their state before the extended selection was done. If XmNautomaticSelection is set to True, this action calls the XmNextendedSelectionCallback callbacks; otherwise, if the parent is a manager, it passes the event to the parent. The auto_selection_type component of the callback structure will be set to XmAUTO_CANCEL.

ListKbdDeSelectAll() 💀

If the XmNselectionPolicy is set to XmSINGLE_SELECT, XmMULTIPLE_SELECT, or XmEXTENDED_SELECT in Add Mode, this action deselects all items in the list. And if the XmNselectionPolicy is set to XmEXTENDED_SELECT in Normal Mode, this action deselects all items in the list — with one little exception: the item at the location cursor stays selected if the shell's XmNkeyboardFocusPolicy is XmEXPLICIT.

This action also calls the appropriate selection callbacks: XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, and XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT.

ListKbdEndExtend() 🍓

If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action calls the XmNextendedSelectionCallback callbacks.

If XmNautomaticSelection is set to True, then the auto_selection_type field of the callback will be valid. If XmNselectionPolicy is set to XmBROWSE_SELECT and the currently selected item position matches the position of the item that was selected before the browse selection began, or if XmNselectionPolicy is set to XmEXTENDED_SELECT and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with auto_selection_type set to XmAUTO_NO_CHANGE. Otherwise, it will be set to XmAUTO_CHANGE.

ListKbdEndSelect() 👑

Calls the appropriate selection callbacks: XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, and XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT.

If XmNautomaticSelection is set to True, then the auto_selection_type field of the callback will be valid. If XmNselectionPolicy is set to XmBROWSE_SELECT and the currently selected item position matches the position of the item that was selected before the browse selection began, or if XmNselectionPolicy is set to XmEXTENDED_SELECT and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with auto_selection_type set to XmAUTO_NO_CHANGE. Otherwise, it will be set to XmAUTO_CHANGE.

ListKbdSelectAll() ⭐

If XmNselectionPolicy is set to XmSINGLE_SELECT or XmBROWSE_SELECT, this action selects the item at the location cursor. If XmNselectionPolicy is set to XmEXTENDED_SELECT or XmMULTIPLE_SELECT, it selects all the items in the list. 💅

This action also calls the appropriate selection callbacks: XmNsingleSelectionCallback when XmNselectionPolicy is set to XmSINGLE_SELECT, XmNbrowseSelectionCallback when XmNselectionPolicy is set to XmBROWSE_SELECT, XmNmultipleSelectionCallback when XmNselectionPolicy is set to XmMULTIPLE_SELECT, and XmNextendedSelectionCallback when XmNselectionPolicy is set to XmEXTENDED_SELECT.

ListLeftChar() 🧚

Scrolls the list one character to the left. Tiny little scoot. 🫶

ListLeftPage() 🌸

Scrolls the list one page to the left. Big scoot energy.

ListNextItem() 🔥

Moves the location cursor to the next item in the list.

  • If the XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the next item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.
  • If the XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the next item, deselects any current selection, moves the current anchor to the next item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode, this action does not affect the selection or the anchor. Periodt. 💜
  • ListNextPage() — scrolls the list to the next page and moves the location cursor onto a new item. 💫

If XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the new item, deselects whatever was selected before, and calls the XmNbrowseSelectionCallback callbacks.

If XmNselectionPolicy is set to XmEXTENDED_SELECT, then in Normal Mode this action also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode, bestie, this action does not touch the selection or the anchor. periodt.

  • ListPrevItem() — moves the location cursor to the previous item in the list. ⬅️

If XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the previous item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the previous item, deselects any current selection, moves the current anchor to the previous item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode, it does not affect the selection or the anchor.

  • ListPrevPage() — scrolls the list to the previous page, moving the location cursor to a new item. 🦋

If XmNselectionPolicy is set to XmBROWSE_SELECT, this action also selects the new item, deselects any current selection, and calls the XmNbrowseSelectionCallback callbacks.

If XmNselectionPolicy is set to XmEXTENDED_SELECT, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the XmNextendedSelectionCallback callbacks. In Add Mode this action does not affect the selection or the anchor.

  • ListProcessBtn1(string) — okay so when Display's XmNenableBtn1Transfer resource is not XmOFF, the actions for selection and transfer are integrated on <Btn1>. When the button is not performing a transfer or drag, the action that gets performed depends on the value of string, which can be one of these:
    • ListButtonMotion
    • ListBeginExtend
    • ListEndExtend
    • ListBeginToggle
    • ListEndToggle
    • ListBeginSelect
    • ListEndSelect
  • ListProcessBtn2 — when Display's XmNenableBtn1Transfer resource has a value of XmBUTTON2_TRANSFER, the actions for extending selection are bound on <Btn2>, and a drag starts immediately. 🏃‍♀️ When Display's XmNenableBtn1Transfer resource has a value of XmBUTTON2_ADJUST, the action that is performed depends on the value of string, which can be one of these:
    • ListBeginExtend
    • ListButtonMotion
    • ListEndExtend
  • ListProcessDrag() — drags the content of one or more selected list items. Each item is separated by a newline. If BTransfer is pressed on an unselected item, it drags only that item, excluding any other selected items. This action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures, possibly multiple times, for the _MOTIF_DROP selection. 🫳✨
  • ListQuickNavigate — navigates to an item. When List's XmNmatchBehavior resource is XmQUICK_NAVIGATE, this action uses 1-character navigation to navigate. Go peek at the XmNmatchBehavior resource for a description of how this navigation works. iykyk.
  • ListRightChar() — scrolls the list one character to the right. ➡️
  • ListRightPage() — scrolls the list one page to the right.
  • PrimitiveHelp() — calls the callbacks for XmNhelpCallback if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. 🆘
  • PrimitiveNextTabGroup() — moves the focus to the first item contained within the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. 🔁
  • PrimitivePrevTabGroup() — moves the focus to the first item contained within the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list.

✨ Additional Behavior ✨

The List widget has the following additional behavior, and yes this is its own little moment:

  • <Double Click> — if a button click is followed by another button click within the time span specified by the display's multiclick time, the List interprets that as a double click and calls the callbacks for XmNdefaultActionCallback. The item's colors invert to indicate that it is selected. The XmNdoubleClickInterval resource can be used to specify a time span that overrides the display's multi-click time. 👆👆
  • <FocusIn> — if the focus policy is Explicit, this action sets the focus and draw the location cursor.
  • <FocusOut> — if the focus policy is Explicit, this action removes the focus and erase the location cursor.

🌈 Virtual Bindings 🌈

The bindings for virtual keys are vendor specific, no cap — every vendor does their own thing. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

The whole friend group, in order: Core(3), XmCreateList(3), XmCreateScrolledList(3), XmFontListCreate(3), XmFontListAppendEntry(3), XmListAddItem(3), XmListAddItems(3), XmListAddItemUnselected(3), XmListAddItemsUnselected(3), XmListDeleteAllItems(3), XmListDeleteItem(3), XmListDeleteItems(3), XmListDeleteItemsPos(3), XmListDeletePos(3), XmListDeletePositions(3), XmListDeselectAllItems(3), XmListDeselectItem(3), XmListDeselectPos(3), XmListGetKbdItemPos XmListGetMatchPos(3), XmListGetSelectedPos(3), XmListItemExists(3), XmListItemPos(3), XmListPosToBounds(3), XmListReplaceItems(3), XmListReplaceItemsPos(3), XmListReplaceItemsPos(3), XmListReplaceItemsPosUnselected(3), XmListReplaceItemsUnselected(3), XmListSelectItem(3), XmListSelectPos(3), XmListSetAddMode(3), XmListSetBottomItem(3), XmListSetBottomPos(3), XmListSetHorizPos(3), XmListSetItem(3), XmListSetKbdItemPos(3), XmListSetPos(3), XmListUpdateSelectedList(3), XmListYToPos(3), XmPrimitive(3) XmStringCreate(3), XmVaCreateList(3), and XmVaCreateManagedList(3).

And that's the whole page, bestie — you made it to the end of the List saga. 🎀 This one's from the XmList library call manual, and it's dated the classic Motif manpage era (that source/version + date line lives at the footer of the original). Go forth and select responsibly. 💅🦋

📦 where this page comes from