XmMultiList(3x)

🌸 NAME

XmMultiList — the Multi-column List widget, aka the manual page XmMultiList(3x) 💅

---

✨ SYNOPSIS

#include <Xm/MultiList.h>

---

💖 DESCRIPTION

okay bestie, sit down, because this widget is a lot and also lowkey iconic. XmMultiList is a multi-column list — headers chilling along the top 🌈, and a search area hanging out along the bottom. The list itself has scrollbars along the right and bottom edges, and those scrollbars let you scroll vertically and horizontally, both by column and by pixel. slay.

The part of the list data that's visible right now? That can change in three ways, periodt:

• scrollbar actions
• widget resource setting
• the redisplay of the list data after a string search has been successful

The sorting of elements within a particular column is also supported ✨. To sort the list by the elements in a given column, select the column's title. that's it. that's the whole vibe check.

---

🔍 the search situation

To search for a particular string in the list, type the string value you're looking for into the list's associated text field, then press the "Find" pushbutton 🫶.

The search for the string begins in the currently selected row, after the location of the previously searched for string, or at the first column and first row if there is no column selected.

If the string is not found in that row, then the search continues through all rows after and then before the currently selected row. If the string is found, the display of the list is adjusted to make the string visible.

If the string was not found, or if the string is visible, the application will issue a warning beep 😭. (yes really. beep. sorry.)

---

🖱️ the pointer situation

Pointer button one allows the user to select a row or a column for sorting. The callbacks on the doubleClickCallback list are called when the user double clicks pointer button one. If the list data can contain a row pixmap to display at the extreme left of the row. 👑

---

🧬 Classes

MultiList inherits behavior, resources, and traits from:

• Core
• Composite
• Constraint
• XmManager

The class pointer is xmMultiListWidgetClass.

The class name is XmMultiList.

---

🆕 New Resources

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). 💖

The codes in the access column indicate if the given resource can be:

• set at creation time (C)
• set by using XtSetValues (S)
• retrieved by using XtGetValues (G)
• or is not applicable (N/A)

no cap, those access codes are gonna matter for every single row of the table, so keep them in your notes bestie 🎀

✨ XmMultiList Resource Set ✨

okay bestie, buckle up 🎀 here is literally every resource this widget has, with its class, type, default and access mode, because we do not gatekeep info in this house:

• XmNcolumnTitles — class: XmCColumnTitles, type: XmString *, default: NULL, access: CSG
• XmNdoubleClickCallback — class: XmCCallback, type: XtCallbackList, default: NULL, access: C
• XmNentryData — class: XmCEntryData, type: XtPointer, default: NULL, access: CSG
• XmNfindLabel — class: XmCFindLabel, type: XmString, default: Find, access: CSG
• XmNfirstColumn — class: XmCFirstLocation, type: short, default: 0, access: CSG
• XmNfirstColumnPixmaps — class: XmCFirstColumnPixmaps, type: Boolean, default: False, access: CSG
• XmNfirstRow — class: XmCFirstLocation, type: short, default: 0, access: CSG
• XmNfontList — class: XmCFontList, type: XmFontList, default: dynamic, access: CSG
• XmNheight — class: XmCHeight, type: Dimension, default: 300, access: CSG
• XmNnumColumns — class: XmCNumColumns, type: short, default: 0, access: CSG
• XmNnumRows — class: XmCNumRows, type: short, default: 0, access: CSG
• XmNselectedColumn — class: XmCSelectedColumn, type: short, default: 0, access: CSG
• XmNselectionPolicy — class: XmCSelectionPolicy, type: unsigned char, default: XmEXTENDED_SELECT, access: CSG
• XmNshowFind — class: XmCShowFind, type: Boolean, default: True, access: CSG
• XmNsingleSelectionCallback — class: XmCCallback, type: XtCallbackList, default: NULL, access: CSG
• XmNsortFunctions — class: XmCFunction, type: XmMultiListSortFunction **, default: NULL, access: CSG
• XmNtitle — class: XmCTitle, type: XmString, default: NULL, access: CSG
• XmNwidth — class: XmCWidth, type: Dimension, default: 300, access: CSG

---

and now the ✨lore✨ on each one, going down the list like the good student you are 🦋

XmNcolumnTitles

this one is an array of length numColumns of strings, and it's literally what gets displayed at the top of each column 👑 the data is allocated and maintained by the client — yes bestie, that means you, so don't come crying when it leaks 💀

XmNdoubleClickCallback

every single routine in this list gets called whenever the user double clicks on a row in the list 🔥 double-click girlies stay winning.

XmNentryData

this resource is the data associated with each row in the list. the data is an array of XmMultiListRowInfo structures of length numRows, allocated by the client. allocated and maintained by the client, fr fr. the XmMultiListRowInfo structure is defined further down 👇

XmNfindLabel

the label to be shown on the find button 🎀 that's it, that's the resource, she's simple and she serves.

XmNfirstColumn

this resource lets the client adjust the current view of the list data so it has a new top left column location 👀 but listen — when you're setting this resource, firstRow should also be updated. they're a package deal, iykyk 💅

XmNfirstColumnPixmaps

this resource specifies that the pixmap stored in the row info structure should be used instead of XmMultiListRowInfo values[0] 🖼️ if pixmaps are present, the rows may be dragged by pressing on the pixmap with pointer button three. and pay attention bestie: if this resource is True, then values[0] is never referenced. if False, then the XmMultiListRowInfo data pixmap is never referenced. it's one or the other, no in-between, periodt.

XmNfirstRow

this resource lets the client adjust the current view of the list data so it has a new top left row location. same rule as her sister: when you're setting this resource, firstColumn should also be updated 🌸

XmNfontList

this is an OSF/Motif style font list 💜 the first font in this list will be used to display all text in the MultiList widget. and here's the tea — the MultiList widget currently supports only one font. so don't get cute with a whole font list, she's monogamous 😭

---

okay we're only partway through the resource breakdown, so don't go anywhere — more coming 🫶

• XmNheight — the overall height value handed to the MultiList widget. Change this one and the scrollbar size and location get affected too, so heads up 👀
• XmNnumColumns, XmNnumRows — these two say how many columns and rows the widget expects to display. They're used as the maximum indices for a bunch of the other resources in this widget, so if you modify them, please please please make sure you've updated the other values too. Care should be taken, bestie. That's the rule. 💅
• XmNselectedColumn — the index of the currently selected column. It's also the column the list is being sorted by. Two jobs, one resource, main character energy fr.
• XmNselectionPolicy — defines how the select action gets interpreted. It can be XmSINGLE_SELECT or XmEXTENDED_SELECT. Any other value → undefined behavior, and we do not do undefined behavior in this house 😭
• XmNshowFind — a boolean that manages and unmanages the find button. that's it. that's the whole resource. iconic.
• XmNsingleSelectionCallback — every routine in this list gets called whenever the user clicks on a line in the list. A pointer to the XmMultiListRowInfo structure for the line that got selected is passed as call_data. ⚠️ But if you're in extended select mode, the value of call_data is undefined.
• XmNsortFunctions — an array of functions, one for each column, called to figure out the ordering of the rows in that column. Think of it like qsort, but for your list ✨
• XmNtitle — the title displayed at the top of the MultiList widget. If this value is NULL, the title area just won't be shown at all. gone. vanished. 🫥
• XmNwidth — the overall width value assigned to the MultiList widget. Same deal as XmNheight: modifying it affects scrollbar size and location.

---

🧸 Specifying Children Resources

okay so here's the tea: the MultiList widget is actually a whole composed situation — it's made of many simple widgets. And sometimes, to get full functionality out of the Toolkit, you wanna set attribute values directly on those sub-widgets. Totally valid. 💖

To do that you grab the widget ids of the sub-widgets using the XtNameToWidget() function from the Xt Intrinsics.

Here's the family tree 🌳:

XmMultiList <named by application>

     XmLabel title

     XmScrollbar vertBar

     XmScrollBar horizBar

     XmFrame frame

          XmPushButton find

          XmText findText

---

🗄️ Using the Resource Database

Real talk: the MultiList widget is a collection of pieces. It gives you the geometry layout for the whole collection and ties the pieces together into one consistent package. Very glue. Very mother. 💅

But here's the catch — lots of the resources documented as being part of the MultiList widget are really part of the internal list sub-component. When you set those values at creation time, or with XtSetValues or XtGetValues, the MultiList widget passes them straight through to the proper child. Easy.

But when you're setting a resource via the resource database, you have to use either the name of the child or the general specification (*) rather than the specific one (.). Do not skip this. fr fr.

---

🌸 The XmMultiListRowInfo Structure

This structure holds the entryData associated with each Row in the List.

typedef struct {

     String * values;    /* The array of column strings */
     Pixmap pixmap; /* mini-icon pixmaps. */
     Boolean selected;   /* row selected. */

     /*
      * Provided for the convenience of the application programmer
      */

     short * sort_id;
     XtPointer data;

     /*
      * Private to the MultiList widget (do not modify these)
      */

     short pix_width;    /* of the pixmap. */
     short pix_height;   /* of the pixmap. */
     short pix_depth;    /* of the pixmap. */

     Boolean old_sel_state;

} XmMultiListRowInfo;

Now let's break down the members, one by one 🎀

• values — an array of strings of length numColumns, representing the strings displayed in each column of this row. The data is allocated and maintained by the client. If firstColumnPixmaps is True, then value[0] is never referenced.
• pixmap — the pixmap displayed to the left of this row. If firstColumnPixmaps is True, then this value is never referenced and mayn remain unset. And if you don't want a pixmap for this row, even though firstColumnPixmaps is True, just set the value of pixmap to None. Color pixmaps may be used 🌈
• sort_id — provided for the convenience of the client, and it's expected to be used as a sort index for this row. You should specify one value for each column of the row. See "sortFunctions" below for details. 👀
• data — provided for the convenience of the client and can be used for literally any purpose. It's intended to be used as an identifier for the object pointed to by this row.
• selected — True if this row is selected; may be set by the application.

Neither sort_id nor data are used by the MultiList widget; they exist solely for the convenience of the programmer. So like, they're yours. enjoy 🫶

---

🌸 XmManager Resource Set 🌸

okay bestie, here's everything our girl inherits from XmManager. every single one, no skips, no cap 💅

• XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG ✨
• XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG 🎀
• XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG 💖
• XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C 🫶
• XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG ⭐
• XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG 🌈
• XmNinitialFocus — class XmCInitialFocus, type Widget, default dynamic, access CSG 👑
• XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG 🦋
• XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG 🔥
• XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C 😭
• XmNshadowThickness — class XmCShadowThickness, type Dimension, default dynamic, access CSG 💅
• XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG 🌸
• XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG 💜
• XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG ✨
• XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG 🧚
• XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG 🍓
• XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG 💀

lowkey obsessed with how many of these defaults are just dynamic. she doesn't commit to a value until she has to. main character energy fr fr.

---

🦋 Composite Resource Set 🦋

and these are the ones coming straight from Composite — only three of them, tiny but mighty 🎀

• XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G 👑
• XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG 💫
• XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G ⭐

not the G on XmNchildren and XmNnumChildren — read-only, bestie. you can look, you can't touch 🙈

---

okay so now we're in the core resource set, bestie ✨ Here's every single one — name, class, type, default, access — no skips, no cap:

• XmNaccelerators — class XmCAccelerators, type XtAccelerators, default dynamic, access N/A
• 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

---

🎀 Translations 🎀

These are the default translation bindings the icon button uses, periodt:

~Ctrl ~Shift <Btn1Down>:   ButtonDown()
Ctrl ~Shift  <Btn1Down>:   ButtonDown(Toggle)
~Ctrl Shift  <Btn1Down>:   ButtonDown(Extend)
Button1 <Motion>:          Motion()
<Btn1Up>:                  ButtonUpOrLeave()

And here are the actions the MultiList supports, bestie:

• ButtonDown(type) — Handles a button press that could start a select or a double click. The type argument can be either Toggle or Extend — these decide which mode of an extended select gets initiated on this button event. Go check the OSF/Motif Style Guide for the full tea, fr fr.
• Motion() — Handles motion events so the selection region can be modified while you're in extended selection mode. It's assumed this action gets called between a ButtonDown() and a ButtonUpOrLeave() action, no cap.
• ButtonUpOrLeave() — Cleans up after ButtonDown() and Motion(). The designated cleanup crew 💅

✨ Callback Routines ✨

okay so bestie, listen up 💖 Every procedure chillin' on the MultiList's singleSelectionCallback and doubleClickCallback lists gets a pointer to an XmMultiListRowInfo structure slid into its call_data field. That structure is defined above, so you already know the vibe. 👑

⚠️ Note: if a single SelectionCallback is registered on an MultiList that's in extended_select_mode, the value of call_data is undefined — like, do not touch it, it's giving absolute chaos. 😭💀

void (callback)(Widget w, XtPointer client_data, XtPointer call_data)

• w — the MultiList widget itself, the main character 👑
• client_data — the client data specified by the application, no cap
• call_data — a pointer to an XmMultiListRowInfo structure corresponding to the row that got selected, periodt.

---

🔥 Sort Function 🔥

Here's the sort function vibe check, bestie ✨

typedef int (XmMultiListSortFunction) (short column, XmMultiRowInfo * row1, XmMultiRowInfo * row2);

• column — the column currently being sorted, iykyk
• row1, row2 — the two rows being compared, like a versus battle. The return value must be an integer less than, equal to, or greater than 0, depending on whether the first argument is less than, equal to, or greater than the second. So if row1 is less than row2, return something < 0; if they're equal, return 0; if row1 is greater, return something > 0. Slay. 💅

---

🌈 RELATED 🌈

You might also wanna peek at these besties 👀

Composite(3), Constraint(3), Core(3), XmCreateMultiList(3), XmManager(3), XmMultiListDeselectAllItems(3), XmMultiListDeselectItem(3), XmMultiListDeselectItems(3), XmMultiListDeselectRow(3), XmMultiListGetSelectedRowArray(3), XmMultiListGetSelectedRows(3), XmMultiListMakeRowVisible(3), XmMultiListSelectAllItems(3), XmMultiListSelectItems(3), XmMultiListSelectRow(3), and XmMultiListToggleRow(3).

---

💜 COPYRIGHT 💜

Copyright (c) 1992 by Integrated Computer Solutions, Inc. — periodt. Don't be stealing this, bestie. 💅

---

And that's the tea! ☕️ This whole page is from XmMultiList(3x) — that's the source/version right there in the footer. The date isn't listed on this page, but you know it's iconic. Stay slaying, bestie! 💖✨🦋