XbaeMatrix(3)

bestie, welcome to the XbaeMatrix(3) page from the xbae manual — it's the whole XbaeMatrix widget class situation, and it's honestly iconic. 💅

💖 NAME 💖

XbaeMatrix — The Bellcore Application Environment (BAE) XbaeMatrix widget class. That's the whole name, no cap. ✨

🌸 SYNOPSIS 🌸

Include this and you're in:

#include <Xbae/Matrix.h>

🦋 DESCRIPTION 🦋

okay so picture this: XbaeMatrix presents an editable array of string data to the user in a scrollable, grid-like format that's giving spreadsheet realness. Non editable pixmaps can also be displayed on the matrix. The rows and columns of the Matrix may optionally be labeled. Also, a number of fixed leading or trailing rows or columns may be specified — these behave similarly to the labels. The way it looks and acts like a grid of XmText widgets? Iconic. But it actually contains only one XmText. This means that XbaeMatrix widgets with hundreds or thousands of rows have much less overhead than they would if they used an XmText for each cell. Periodt. 💅

Clicking on a cell with Button1 will edit the cell. While a cell is being edited, Tab and Shift-Tab will edit the cell to the right or left respectively. The osfUp and osfDown keys will edit the cell above or below. Ctrl-Tab and Shift-Ctrl-Tab will traverse out of the Matrix and into the next or previous tab groups. 🫶

The osfCancel key will cancel any edits made to a cell. The osfActivate key will commit any edits made to a cell and store them in the Matrix. When traversing from another tab group into the Matrix, the focus will go to whichever cell is currently being edited. If no cells are being edited, then the upper left most visible non-fixed cell will be edited. That's the default, bestie. ✨

The column sizes may be dynamically resized by pressing the Shift-Button2 combination when over a column boundary, similar to the behaviour of some popular spreadsheets. After a column has been resized in this manner, the XbaeMatrix calls the callbacks on the XmNresizeColumnCallback callback list for post processing. Slay. 🔥

If the Matrix is resized until it is too small to display all of the cells in a given dimension, then it will display a ScrollBar for that dimension. The horizontal ScrollBar will scroll the cells and column labels, but not the row labels, fixed columns or trailing fixed columns. The vertical ScrollBar will scroll the cells and row labels, but not the column labels, fixed rows or trailing fixed rows. No cap. 🎀

For the application programmer, XbaeMatrix provides callbacks to assist in data validation. The callbacks on the XmNmodifyVerifyCallback callback list are called before text is inserted into, or deleted from, a cell. This callback list can be used to force user input to match a certain pattern (e.g. a date format). Similarly, the XmNvalueChangedCallback is called after text is inserted or deleted. 💖

When a cell is edited (by clicking on it or tabbing into it), the XmNleaveCellCallback callbacks are called for the previous cell being edited, if any. The application can verify the data entered in that cell and disallow editing of the new cell if the data is invalid. If the data was valid, then the XmNenterCellCallback callbacks for the new cell are called. These callbacks can be used to specify the editability of the new cell. 🎀

The XmNtraverseCellCallback callbacks are also called when the user attempts to edit a new cell and when the matrix gains or looses focus. This allows the application to override the default traversal behavior of XbaeMatrix. ✨

The XmNdefaultActionCallback is provided to allow a double click action in a cell to perform some function. Motif's Drag and Drop functionality can be achieved via the XmNprocessDragCallback. 🦋

For large amounts of data, the overhead of assigning data to the widget can be avoided using the XmNdrawCellCallback. This callback also allows user defined pixmaps to be placed in a certain cell. When using this callback, data for string fields can be written back to the application by using the XmNwriteCellCallback. Obsessed. 💅

👑 Classes 👑

• XbaeMatrix inherits behavior and resources from the Core, Composite, Constraint, and XmManager widget classes.
• The class pointer is xbaeMatrixWidgetClass.
• The class name is XbaeMatrix.

✨ New Resources ✨

The following table lists the new resources defined by XbaeMatrix. The codes in the Access column indicate whether the given resource can be set at creation time (C), or set by using XtSetValues (S), or retrieved by using XtGetValues (G). That's the whole access-code setup before the table shows up, bestie. 💖

• XmNallowColumnResize — class XmCAllowResize, type Boolean, default True, access CSG. yes bestie it ships as True 💅
• XmNallowRowResize — class XmCAllowResize, type Boolean, default True, access CSG. also True out of the box, we love a matching pair 🫶
• XmNaltRowCount — class XmCAltRowCount, type int, default 1, access CSG. it's giving one, literally just 1 🎀
• XmNboldLabels — class XmCBoldLabels, type Boolean, default False, access CSG. default is False, ngl
• XmNbuttonLabels — class XmCButtonLabels, type Boolean, default False, access CSG. False, periodt
• XmNbuttonLabelBackground — class XmCColor, type Pixel, default dynamic, access CSG. the default is dynamic, iykyk ✨
• XmNcalcCursorPosition — class XmCCalcCursorPosition, type Boolean, default False, access CSG. again False, no notes 💀
• XmNcellBackgrounds — class XmCColors, type PixelTable, default NULL, access CSG. NULL bestie, empty, nothing there 🙈
• XmNcellHighlightThickness — class XmCHighlightThickness, type Dimension, default dynamic, access CSG. type is Dimension, default dynamic
• XmNcellMarginHeight — class XmCMarginHeight, type Dimension, default dynamic, access CSG. Dimension energy, dynamic default 🌸
• XmNcellMarginWidth — class XmCMarginWidth, type Dimension, default dynamic, access CSG. twin of the one above, same dynamic default 🦋
• XmNcellShadowThickness — class XmCShadowThickness, type Dimension, default 2, access CSG. default is the number 2, iconic
• XmNcellShadowType — class XmCShadowType, type unsigned char, default XmSHADOW_OUT, access CSG. default XmSHADOW_OUT — write it exactly like that, don't come for me 😭
• XmNcellShadowTypes — class XmCCellShadowTypes, type unsigned char **, default NULL, access CSG. note the double star unsigned char **, she's a whole pointer-to-pointer 👑
• XmNcellUserData — class XmCCellUserData, type XtPointer **, default NULL, access CSG. also XtPointer **, also NULL, also double-starred 🌈
• XmNclipWindow — class XmCClipWindow, type Widget, default NULL, access G. heads up, access is just G — not CSG like the rest, main character exception ⭐
• XmNcells — class XmCCells, type CellTable, default NULL, access CSG. type CellTable 💜
• XmNcolors — class XmCColors, type PixelTable, default NULL, access CSG. PixelTable, NULL default
• XmNcolumnAlignments — class XmCAlignments, type AlignmentArray, default dynamic, access CSG. AlignmentArray with a dynamic default ✨
• XmNcolumnButtonLabels — class XmCButtonLabels, type BooleanArray, default NULL, access CSG. careful, this class is XmCButtonLabels just like XmNbuttonLabels but the type is BooleanArray this time 🎀
• XmNcolumnLabelAlignments — class XmCAlignments, type AlignmentArray, default dynamic, access CSG. dynamic default, yes ma'am
• XmNcolumnLabelColor — class XmCColor, type Pixel, default dynamic, access CSG. notice: XmCColor, not XmCColors — singular slay 💅
• XmNcolumnLabels — class XmCLabels, type StringArray, default NULL, access CSG. StringArray vibes 🌸
• XmNcolumnMaxLengths — class XmCColumnMaxLengths, type MaxLengthArray, default NULL, access CSG. that class name is a whole mouthful, XmCColumnMaxLengths, fr fr
• XmNcolumnShadowTypes — class XmCShadowTypes, type unsigned char *, default NULL, access CSG. single star here unsigned char *, don't mix her up with XmNcellShadowTypes 😤
• XmNcolumnUserData — class XmCUserDatas, type XtPointer *, default NULL, access CSG. class XmCUserDatas, type XtPointer * — singular pointer, plural class, that's just how she is 🦋
• XmNcolumnWidthInPixels — class XmCColumnWidthInPixels, type Boolean, default False, access CSG. False default, obsessed
• XmNcolumnWidths — class XmCColumnWidths, type WidthArray, default NULL, access CSG. WidthArray, NULL
• XmNcolumns — class XmCColumns, type int, default 0, access CSG. default is literally 0 — zero columns at launch, she starts empty bestie 🔥

🎀 XbaeMatrix Resource Set (continued) 🎀

Okay bestie, the resource list keeps going, and honestly? It ate. Every single one is here — name, class, type, default, access — no skips, no cap 💅

• XmNdefaultActionCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG. The default-action callback, just vibing at NULL until you claim it ✨
• XmNdoubleClickInterval — class XmCDoubleClickInterval, type int, default dynamic, access CSG. How fast you gotta double-tap for it to count as a double click 🫶
• XmNdrawCellCallback — class XmCCallback, type Callback, default NULL, access CSG. Lets you draw the cells yourself, main character energy 🎨
• XmNenterCellCallback — class XmCCallback, type Callback, default NULL, access CSG. Fires when the pointer enters a cell, hi bestie 👋
• XmNevenRowBackground — class XmCBackground, type Pixel, default dynamic, access CSG. The background color for even rows, so they can be all matchy-matchy 🌸
• XmNfill — class XmCFill, type Boolean, default False, access CSG. Fill mode: on or off, no in-between 💀
• XmNhorzFill — class XmCHorzFill, type Boolean, default False, access CSG. The horizontal flavor of fill ✨
• XmNvertFill — class XmCVertFill, type Boolean, default False, access CSG. And the vertical one, we love a symmetry moment 🦋
• XmNfixedColumns — class XmCFixedColumns, type Dimension, default 0, access CSG. How many columns are locked in place, fr fr 🔒
• XmNfixedRows — class XmCFixedRows, type Dimension, default 0, access CSG. Same but for rows, iconic 👑
• XmNfontList — class XmCFontList, type FontList, default fixed, access CSG. The font list, defaulting to fixed like it's too cool to try 💅
• XmNgridLineColor — class XmCColor, type Pixel, default dynamic, access CSG. Grid line color, because the lines deserve a lil glow-up 🌈
• XmNgridType — class XmCGridType, type GridType, default XmGRID_CELL_LINE, access CSG. What kind of grid you're serving ⭐

---

💜 XbaeMatrix Resource Set (continued, again) 💜

Not me having another table for you 😭 but it's all here, gorl:

• XmNhighlightedCells — class XmCHighlightedCells, type HighlightTable *, default dynamic, access CSG. A whole table of which cells are highlighted, highkey obsessed ✨
• XmNhorizontalScrollBar — class XmCHorizontalScrollBar, type Widget, default NULL, access G. The horizontal scrollbar widget — note the access is G, so it's get-only, no touching 🙈
• XmNhorizontalScrollBarDisplayPolicy — class XmCMatrixScrollBarDisplayPolicy, type unsigned char, default XmDISPLAY_AS_NEEDED, access CSG. When the horizontal scrollbar shows up, defaulting to XmDISPLAY_AS_NEEDED 🫶
• XmNlabelActivateCallback — class XmCCallback, type Callback, default NULL, access CSG. Fires when a label gets activated, slay 🎀
• XmNlabelFont — class XmCFontList, type FontList, default dynamic, access CSG. The label font, dynamic by default because it keeps it fresh 💅
• XmNleaveCellCallback — class XmCCallback, type Callback, default NULL, access CSG. The goodbye callback for when the pointer dips out of a cell, bye bestie 😭
• XmNleftColumn — class XmCLeftColumn, type int, default 0, access CSG. Which column is leftmost, starting at 0 obviously ⭐
• XmNmodifyVerifyCallback — class XmCCallback, type Callback, default NULL, access CSG. Vibe check for modifications before they happen — verify first, edit later 🔥
• XmNmultiLineCell — class XmCMultiLineCell, type Boolean, default False, access CSG. Whether cells can be multi-line, off by default 🌸
• XmNnonFixedDetachedLeft — class XmCNonFixedDetachedLeft, type Boolean, default False, access CSG. Detached-left behavior for the non-fixed section, False by default 🦋
• XmNnonFixedDetachedTop — class XmCNonFixedDetachedTop, type Boolean, default False, access CSG. And the top version of that same vibe, also False ✨
• XmNoddRowBackground — class XmCBackground, type Pixel, default dynamic, access CSG. Background color for odd rows — the even rows got theirs, gotta keep it fair 💖
• XmNprocessDragCallback — class XmCCallback, type Callback, default NULL, access CSG. A callback slot just chilling at NULL until you give it something to do 💅
• XmNrenderTable — class XmCRenderTable, type RenderTable, default NULL, access CSG. Ngl this one's giving "very important and you should know what a RenderTable is" energy 👑
• XmNresizeCallback — class XmCCallback, type Callback, default NULL, access CSG. Callback, NULL until further notice ✨
• XmNresizeColumnCallback — class XmCCallback, type Callback, default NULL, access CSG. Another callback, also NULL, also waiting for its moment 🎀
• XmNreverseSelect — class XmCReverseSelect, type Boolean, default False, access CSG. Defaults to False, bestie, so it's off unless you say otherwise 🙈
• XmNrowButtonLabels — class XmCButtonLabels, type BooleanArray, default NULL, access CSG. A whole BooleanArray, starting out as NULL 🌸
• XmNrowHeightInPixels — class XmCRowHeightInPixels, type Boolean, default True, access CSG. This one clocks in at True by default, lowkey iconic ⭐
• XmNrowHeights — class XmCColumnWidths, type WidthArray, default NULL, access CSG. Type WidthArray, default NULL — and yes the class really is XmCColumnWidths even though the resource says row heights. Not a typo, that's literally what's written, iykyk 👀
• XmNrowLabelAlignment — class XmCAlignment, type Alignment, default XmALIGNMENT_END, access CSG. Ships aligned to XmALIGNMENT_END 🎯
• XmNrowLabelColor — class XmCColor, type Pixel, default dynamic, access CSG. Default is the mysterious dynamic, which is so main character of it 🔥
• XmNrowLabelWidth — class XmCRowLabelWidth, type Short, default dynamic, access CSG. Short, default dynamic, periodt 💜
• XmNrowLabels — class XmCLabels, type StringArray, default NULL, access CSG. A StringArray of labels, starting at NULL until you feed it 🍓
• XmNrowShadowTypes — class XmCShadowTypes, type unsigned char *, default NULL, access CSG. Careful with the type, it's unsigned char * — pointer and all, don't go dropping the * 😭
• XmNrowUserData — class XmCUserDatas, type XtPointer *, default NULL, access CSG. Note the class plural: XmCUserDatas. And the type is XtPointer *. Copy it exactly, bestie 🫶
• XmNrows — class XmCRows, type int, default 0, access CSG. Starts at 0 rows, which is honestly so relatable 💀
• XmNscrollBarPlacement — class XmCScrollBarPlacement, type unsigned char, default XmBOTTOM_RIGHT, access CSG. Defaults to XmBOTTOM_RIGHT, exactly as written 🧭
• XmNselectCellCallback — class XmCCallback, type Callback, default NULL, access CSG. One more callback, one more NULL 🌈
• XmNselectScrollVisible — class XmCSelectScrollVisible, type Boolean, default True, access CSG. True by default — visible unless you intervene ✨
• XmNselectedBackground — class XmCColor, type Pixel, default dynamic, access CSG. dynamic again, keeping the mystery alive 🦋
• XmNselectedCells — class XmCSelectedCells, type BooleanTable, default dynamic, access CSG. A BooleanTable, default dynamic 💖
• XmNselectedForeground — class XmCColor, type Pixel, default dynamic, access CSG. Same trio, different name: XmCColor / Pixel / dynamic 🧚
• XmNshadowType — class XmCShadowType, type unsigned char, default XmSHADOW_IN, access CSG. Defaults to XmSHADOW_IN. Singular XmCShadowType, don't confuse it with the plural XmNrowShadowTypes one up there 👑
• XmNshowArrows — class XmCShowArrows, type Boolean, default False, access CSG. False by default — no arrows unless you say so 🙈
• XmNspace — class XmCSpace, type Dimension, default dynamic, access CSG. Type Dimension, default dynamic. That's the whole bit 🎀
• XmNtextBackground — class XmCBackground, type Pixel, default XmUNSPECIFIED_PIXEL, access CSG. Yes, the class is XmCBackground and the default is XmUNSPECIFIED_PIXEL — write it out in full, no abbreviations, I'm begging 😭
• XmNtextBackgroundIsCell — class XmCTextBackgroundIsCell, type Boolean, default False, access CSG. Last of this batch, defaulting to False like a calm little icon ⭐

---

And we are so not done yet — the resource list keeps going, so stay with me bestie 💅

...okay picking right back up where we left off in the resource table, alphabetically speaking we're in the t's and the vibe is immaculate ✨ same columns as before — Name, Class, Type, Default, Access — no cap, keep 'em straight:

• XmNtextField — class XmCTextField, type Widget, default NULL, access G 💅
• XmNtextShadowThickness — class XmCTextShadowThickness, type Dimension, default 0, access CSG
• XmNtextTranslations — class XmCTranslations, type TranslationTable, default dynamic, access CSG
• XmNtopRow — class XmCTopRow, type int, default 0, access CSG
• XmNtrackcellCallback — class XmCCallback, type Callback, default NULL, access CSG
• XmNtrailingAttachedBottom — class XmCTrailingAttachedBottom, type Boolean, default False, access CSG
• XmNtrailingAttachedRight — class XmCTrailingAttachedRight, type Boolean, default False, access CSG
• XmNtrailingFixedColumns — class XmCTrailingFixedColumns, type Dimension, default 0, access CSG
• XmNtrailingFixedRows — class XmCTrailingFixedRows, type Dimension, default 0, access CSG
• XmNtraverseCellCallback — class XmCCallback, type Callback, default NULL, access CSG
• XmNtraverseFixedCells — class XmCTraverseFixedCells, type Boolean, default False, access CSG

---

🦋 XbaeMatrix Resource Set (continued) 🦋

and the table just keeps giving, honestly main character energy — here's the rest of the resource set:

• XmNuseXbaeInput — class XmCUseXbaeInput, type Boolean, default False, access CSG
• XmNvalueChangedCallback — class XmCCallback, type Callback, default NULL, access CSG
• XmNverticalScrollBar — class XmCVerticalScrollBar, type Widget, default NULL, access G 👀
• XmNverticalScrollBarDisplayPolicy — class XmCMatrixScrollBarDisplayPolicy, type unsigned char, default XmDISPLAY_AS_NEEDED, access CSG
• XmNvisibleColumns — class XmCVisibleColumns, type Dimension, default 0, access CSG
• XmNvisibleRows — class XmCVisibleRows, type Dimension, default 0, access CSG
• XmNwrapType — class XmCWrapType, type Boolean, default XbaeWrapNone, access CSG
• XmNwriteCellCallback — class XmCCallback, type Callback, default NULL, access CSG
• XmNxmColumnLabels — class XmCXmLabels, type XmString *, default NULL, access CSG
• XmNxmRowLabels — class XmCXmLabels, type XmString *, default NULL, access CSG

🫶 heads up bestie, one very important footnote: This resource cannot be specified in a resource file — so don't go trying to sneak it into your app-defaults and then act surprised when it ghosts you 😭

and that's the whole resource set babes, every last one accounted for, no skipping, no "oh that one's boring" — we do not do that here 💖 more coming, don't go anywhere

• XmNallowColumnResize — set it to True and your columns can be dragged wider or narrower on the fly with the ResizeColumns() action ✨. Default vibe? Resizing is allowed. Have fun with it 💅
• XmNallowRowResize — same energy but for rows: True means the ResizeRows() action can actually resize them 🦋. Default is yes, rows are resizable.
• XmNaltRowCount — tells the widget how many rows each of the XmNevenRowBackground and XmNoddRowBackround colors covers 🌈. Heads up though: this resource is straight-up ignored if you're not using XmNevenRowBackground and XmNoddRowBackround at all. No colors, no counting, no point 💀
• XmNboldLabels — when True, it overstrikes the row and column labels so they look bold 🔥 (fake bold, real slay).
• XmNbuttonLabels — set this to True and your labels get drawn with a shadow around them, lowkey giving XmPushButton 👑. When it's True, a ButtonPress event on a label makes the shadow reverse and the label go all pushed-in looking; a ButtonRelease on that same label then fires the callbacks on the XmNlabelActivateCallback list 🫶. Default value is False.
• XmNbuttonLabelBackground — a Pixel value that says what color to draw the XmNbuttonLabels in 🎨.
• XmNcalcCursorPosition — set to True and the insertion position in the text field gets calculated based on where in the cell you actually clicked 🖱️✨. Default is False. Ngl, the insertion position gets overridden anyway if the position member of the XbaeEnterCellCallbackStruct is set to a valid position — so like, that wins 💅
• XmNcellBackgrounds — points to an array of pointers to rows, where each row is an array of Pixel values, one per column in that row 🎀. Same data structure as XmNcells, except every entry is a Pixel instead of a String. Each cell's background gets drawn in the color you specified for it. If XmNcellBackgrounds is NULL, backgrounds fall back to the color in XmNbackground. This resource is copied.

You can specify it in a resource file, but because XbaeMatrix is two-dimensional you gotta terminate each line with a \n character — no cap, that's the rule 😭. So if the widget had XmNrows set to 5 and XmNcolumns set to 5, you'd write XmNcellBackgrounds like:

*mw.cellBackgrounds:   blue, white, blue, white, blue\n\
                       white, blue, white, blue, white\n\
                       blue, white, blue, white, blue\n\
                       white, blue, white, blue, white\n\
                       blue, white, blue, white, blue\n

Careful bestie 🙈 — specify these values in a resource file with an incorrect format and you can produce undesirable results. Be precise.

• XmNcellHighlightThickness — the XmNhighlightThickness resource of the XmText cell edit widget. It's also used to compute the size of each cell. Peep the description of XmNhighlightThickness in XmText(3X) 📖.
• XmNcellMarginHeight — the XmNmarginHeight resource of the XmText widget, and yes, it's also used to compute the size of each cell. See XmNmarginHeight in XmText(3X) ✨.
• XmNcellMarginWidth — the XmNmarginWidth resource of the XmText cell edit widget. Also used to compute the size of each cell. See XmNmarginWidth in XmText(3X) 💖.
• XmNcellShadowThickness — the XmNshadowThickness resource of the XmText cell edit widget, also used to compute the size of each cell. See XmNshadowThickness in XmText(3X) 🌸.
• XmNcellShadowType — what kind of shadow gets drawn around each cell 🎀. Possible values are XmSHADOW_OUT, XmSHADOW_IN, XmSHADOW_ETCHED_OUT, and XmSHADOW_ETCHED_IN. Default shadow type is XmSHADOW_OUT.
• XmNcellShadowTypes — same as XmNcellShadowType but on a per-cell basis 😌. Values are the same as for XmNcellShadowType. This resource is copied.
• XmNcellUserData — points to an array of pointers to individual user-defined data areas, one per cell 🫶. Set the data with XbaeMatrixSetCellUserData() and get it back with XbaeMatrixGetCellUserData(). This resource cannot be specified in a resource file, and it's copied.
• XmNcells — points to an array of pointers to rows, each row being an array of String, one for each column in that row ✨. For example, the cells for a 2x3 Matrix could be set up like this:

String rows[2][3] =
{
     "00",   "01",   "02",
     "10",   "11",   "12"
};
    String *cells[2];
    cells[0] = &rows[0][0];
    cells[1] = &rows[1][0];

Then cells could be used as the XmNcells resource 👑. If XmNcells is NULL, XbaeMatrix will not generate an internal table of empty Strings — which means if XmNcells is NULL, no cells have been set, periodt 💅. This resource is copied. For how to specify XmNcells in a resource file, go read the discussion in XmNcellBackgrounds 👀.

• XmNclipWindow — the widget ID of the clip window, i.e. the widget that contains the non-fixed region of cells 🦋. This resource cannot be set to a new value. Read-only, bestie.
• XmNcolors — points to an array of pointers to rows, each row an array of Pixel values, one per column in that row 🎨. Same structure as XmNcells, except every entry is a Pixel instead of a String. The text in a cell gets drawn in the color you specified for it. If XmNcolors is NULL, text falls back to the color in XmNforeground. This resource is copied. See the discussion in XmNcellBackgrounds for how to specify XmNcolors in a resource file 🌈.
• XmNcolumnAlignments — points to an array of alignments (unsigned char), one per column 📐. Each element can be XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END. It specifies the alignment of the text or pixmap in each cell of that column — see the description of XmNalignment for XmLabel(3X). If XmNcolumnAlignments is NULL, every column defaults to XmALIGNMENT_BEGINNING. This resource is copied.
• XmNcolumnButtonLabels — an array of Booleans that tells XbaeMatrix which column labels should be drawn as buttons 👑. Each Boolean can be specified as a Boolean string or an integer. In order to use this resource, XmNbuttonLabels should be set to False ⚠️ (yes, fr fr — that's the deal).
• XmNcolumnLabelAlignments — points to an array of alignments (unsigned char), one per column label 📐✨. Each element can be XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END, and it sets the alignment of the text of each column label. See the description of XmNalignment for XmLabel(3X). If XmNcolumnLabelAlignments is NULL, each column label defaults to XmALIGNMENT_BEGINNING. This resource is copied.
• XmNcolumnLabelColor — a Pixel value saying what color to draw the XmNcolumnLabels in 🎀.
• XmNcolumnLabels — points to an array of Strings drawn above each column 🌸. Each String can have embedded newline characters, in which case the label is drawn on multiple lines. If there's an XmNxmColumnLabels defined for this column, that gets displayed in place of the XmNcolumnLabels 👀. If both XmNcolumnLabels and XmNxmColumnLabels are NULL, no labels get drawn at all. This resource is copied.
• XmNcolumnMaxLengths — points to an array of int, one per column 🔢. These set the maximum length of a String that can be entered into the cells in that column — see the description of the XmText(3X) XmNmaxLength resource. If XmNcolumnMaxLengths is NULL, or an element of the array equals 0, then the corresponding width from XmNcolumnWidths is used instead. This resource is copied.
• XmNcolumnShadowTypes — same as XmNcellShadowType but on a per-column basis 💅. Values for the resource are the same as for XmNcellShadowType. This resource is copied.
• XmNcolumnUserData — points to a user-defined data area associated with one particular column 🫶. Set it with XbaeMatrixSetColumnUserData() and get it with XbaeMatrixGetColumnUserData(). This resource cannot be specified in a resource file.
• XmNcolumnWidthInPixels — decides whether the elements of XmNcolumnWidths are measured in pixels or in characters 📏.
• XmNcolumnWidths — points to an array of short, one per column, specifying the visible width of the cells in each column ✨. See the description of the XmText(3X) XmNcolumns resource. This resource is copied.
• XmNcolumns — the total number of columns of cells. XmNcolumns must be at least one 🚨. If you change the number of columns via XtSetValues, then XmNcolumnMaxLengths must change or be NULL, XmNcolumnLabels must change or be NULL, XmNcolumnAlignments must change or be NULL, and XmNcolumnLabelAlignments must change or be NULL. The preferred way to dynamically change the number of columns is XbaeMatrixAddColumns() or XbaeMatrixDeleteColumns() — that's the move 👑
• XmNdefaultActionCallback — a list of callbacks to call when a double click happens in a cell 🖱️🔥. A pointer to an XbaeMatrixDefaultActionCallbackStruct gets passed to the callbacks. Events are reported to the cell where the double click happens regardless of whether a callback exists or not. This callback is called by the DefaultAction() action and is NULL by default. Obsessed with this one for popping up a dialog or other window when a double click occurs 🎀
• XmNdoubleClickInterval — how much time can pass between mouse clicks before it's not a double click anymore ⏱️. A double click is defined as the time between the release of the mouse button and the subsequent press in the same cell. The default value is inherited from the display 💅
• XmNdrawCellCallback — the callback list that fires whenever a cell needs to be drawn, and bestie, this one's the whole personality of the widget. A pointer to an XbaeMatrixDrawCellCallbackStruct gets passed to your callbacks, and you can literally decide what goes in the cell by messing with that struct's data fields. When your callback returns to the widget code, the type field is the vibe check that decides what the widget actually paints on screen 🌈:
  • if it's XbaeString, the widget calls its regular string drawing function with whatever value you assigned to the string field in the struct;
  • if it's XbaeStringFree, the widget also calls XtFree on that string when it's not needed anymore (so it cleans up for you, iconic);
  • otherwise, if it's XbaePixmap, the widget does an XCopyPlane() for a single plane bitmap, or an XCopyArea() for a color pixmap ✨. The width and height of the cell are passed in the struct so you know exactly how big to make that pixmap — no guessing, fr fr. In no case will a copy of the string or the pixmap value be made (👀 read that again). The widget also uses XmNcolumnAlignments to figure out the horizontal alignment of the Pixmap. And if you want an editable array of data while XmNdrawCellCallback is in play and the cell is of type XbaeString or XbaeStringFree, use XmNwriteCellCallback. That's the pairing, iykyk 💅
• XmNenterCellCallback — a callback list called immediately before a cell is about to be edited. This one's invoked by the EditCell() action. A pointer to an XbaeMatrixEnterCellCallbackStruct comes along for the ride. You can use it to specify the editability of specific cells and to set configuration options for the XmText — very much giving main character energy for your per-cell rules 🎀
• XmNevenRowBackground — a background cell Pixel value used on even rows. It makes the matrix look like computer paper 📄 (yes, that's the actual aesthetic goal). Want wider bands of color? Increase the size of XmNaltRowCount.
• XmNfill — if True, this controls whether the matrix should fill all of its available space when additional space is available, or whether it should simply size itself as large as necessary, regardless of any additional available space. Pick your fighter 💫
• XmNhorzFill — if True, controls whether the matrix should highlight the available space on the right of the selected cell(s) when the selected cell(s) are in the last column of the matrix. Little glow-up for the empty space 👑
• XmNvertFill — if True, controls whether the matrix should highlight the available space below the selected cell(s) when the selected cell(s) are in the last row of the Matrix. Same energy, but downward 🦋
• XmNfixedColumns — the number of leading columns (starting from the left column) that should not be horizontally scrollable. XmNfixedColumns must be less than XmNcolumns-XmNtrailingFixedColumns. Heads up: cells in fixed columns are not editable unless XmNtraverseFixedCells is set to True. Locked in place, no cap 🔒
• XmNfixedRows — the number of leading rows (starting from the top row) that should not be vertically scrollable. XmNfixedRows must be less than XmNrows-XmNtrailingFixedRows. Same deal: cells in fixed rows are not editable unless XmNtraverseFixedCells is set to True.
• XmNfontList — if the value of XmNrenderTable is NULL, this resource specifies the font list used for the text displayed in the cells and the XmText cell edit widget. See XmFontListCreate(3X) to create a font list. This resource is copied. The preferred way of specifying a font for the table is in a resource file (ngl, do it that way).

When drawing a cell, the matrix uses the first entry with the tag XmFONTLIST_DEFAULT_TAG if no tag has been set on the cell using XbaeMatrixSetCellTag. If a tag has been set on the cell, the first entry with a matching tag is used. Matching matters, bestie 💖

• XmNgridLineColor — the color in which the grid line should be drawn if XmNgridType is set to XmGRID_CELL_LINE, XmGRID_ROW_LINE or XmGRID_COLUMN_LINE. The default is that of XmNforeground.
• XmNgridType — sets the way the matrix grid is drawn 🕸️. The grid types available include XmGRID_NONE, XmGRID_CELL_LINE, XmGRID_CELL_SHADOW, XmGRID_ROW_LINE, XmGRID_ROW_SHADOW, XmGRID_COLUMN_LINE and XmGRID_COLUMN_SHADOW. All of them vary the way the shadow or line is drawn around the cell. XmGRID_ROW_LINE, XmGRID_ROW_SHADOW, XmGRID_COLUMN_LINE, and XmGRID_COLUMN_SHADOW only draw a border around the rows and columns, giving a more tabular rather than spreadsheet appearance. The default is XmGRID_CELL_LINE, which draws a solid line around the cells. Solid. Line. Around. The. Cells. Periodt 🔥
• XmNhighlightedCells — points to an array of pointers to rows. Each row is an array of unsigned char values, one for each column in that row. This data structure is the same as that for XmNcells, except each entry is an unsigned char instead of a String. Each entry in the array will have a value that is either HighlightNone, HighlightCell, HighlightRow, HighlightColumn, HighlightOther, or the bitwise OR of those values — depending on the value of XmNgridType and which call was used to highlight the cell. A cell will be drawn as highlighted if the corresponding unsigned char does not have the value HighlightNone. If XmNhighlightedCells is NULL, then no cells have been highlighted. This resource is copied, and cannot be specified in a resource file 🚫
• XmNhorizontalScrollBar — the widget ID of the horizontal XmScrollBar. This resource exists only for those applications that need to tie another scrollbar to the matrix's, for synchronized scrolling. This resource can not be set to a new value (read-only, don't even try it 💀).
• XmNhorizontalScrollBarDisplayPolicy — determines when to display a horizontal scrollbar in the matrix. Possible values are XmDISPLAY_NONE, which makes the matrix never display the scrollbar, XmDISPLAY_AS_NEEDED, which makes the matrix display the scrollbar when the list is too large, and XmDISPLAY_STATIC, which makes the matrix always display the scrollbar. Never / whenever / always — pick one 🎚️
• XmNlabelFont — if the value of XmNrenderTable is NULL, this resource specifies the font list used for the text displayed in row and column labels. If XmNlabelFont is not specified, the value of XmNfontList is used for the label fonts. See XmFontListCreate(3X) to create a font list. This resource is copied. The preferred way of specifying a font for the labels is in a resource file ✨

When drawing a label, the matrix uses the first entry with the tag XmFONTLIST_DEFAULT_TAG.

• XmNlabelActivateCallback — a callback list called after a button label has been pressed. A pointer to an XbaeMatrixLabelActivateCallbackStruct is passed to the callbacks on this list 🫶
• XmNleaveCellCallback — a callback list called immediately after a cell has been edited. This one's invoked by the EditCell() and CommitEdit() actions. A pointer to an XbaeMatrixLeaveCellCallbackStruct is passed to the callbacks. Perfect spot for your cell-specific data checks, so nothing sus sneaks through 👀
• XmNleftColumn — lets the programmer specify the first non fixed column to appear on the leftmost side of the matrix. This resource compliments the XmNtopRow resource. See the discussion of XmNtopRow for more details 📍
• XmNmodifyVerifyCallback — a callback list called before text is deleted from or inserted into the XmText cell edit widget. A pointer to an XbaeMatrixModifyVerifyCallbackStruct is passed to the callbacks. See the description of the XmText(3X) XmNmodifyVerifyCallback resource — it's the same flavor of interception 💜
• XmNmultiLineCell — a boolean (default False) which specifies whether the matrix displays more than one line of text in a cell, when appropriate. Multi-line glow-up, but only when it actually makes sense 🧚
• XmNnonFixedDetachedLeft — indicated that empty space should be displayed after the fixed rows. This resource only has effect when XmNfill is true and XmNfixedRows is greater than zero. (Yes, that's what it says — rows, with XmNfixedRows. Copying it exactly, bestie 💖)
• XmNnonFixedDetachedTop — indicated that empty space should be displayed after the fixed columns. This resource only has effect when XmNfill is true and XmNfixedColumns is greater than zero.
• XmNoddRowBackground — a background cell color to use on odd rows. This allows the matrix to look like computer paper 📄 (the sibling of the even-row one, we stan a matching set). For wider bands of color, increase the size of XmNaltRowCount.
• XmNprocessDragCallback — a callback list called from the ProcessDrag() action. A pointer to an XbaeMatrixProcessDragCallbackStruct will be passed to the callbacks. Use this list to perform particular processing during a drag — very "custom behavior mid-drag" of you 🖱️✨
• XmNrenderTable — specifies the render table used to derive a font set or a font to draw the text displayed in the cells, the XmText cell edit widget and the labels 🎨

When drawing a cell, the matrix uses the first entry with the tag _MOTIF_DEFAULT_LOCALE if no tag has been set on the cell using XbaeMatrixSetCellTag. If a tag has been set on the cell, the first entry with a matching tag is used.

When drawing a label, the matrix uses the first entry with the tag "labels". If there is no such entry, the first entry with the tag _MOTIF_DEFAULT_LOCALE is used. Fallback behavior that actually slays 💅

• XmNresizeCallback — a callback list called when the matrix is resized 📐
• XmNresizeColumnCallback — a callback list called when a column is dynamically resized by the user. User-driven resizing, so you get to react in real time 🦋
• XmNreverseSelect — overrides the default XmNselectedForeground and XmNselectedBackground and draws a selected cell in the colours specified by XmNcellBackgrounds and XmNcolors for that particular cell. If these values are not set, then the default colours will be used. Flip the whole selection aesthetic, no cap 🌈
• XmNrowButtonLabels — an array of Booleans that tells the XbaeMatrix which row labels should be drawn as a button. Each Boolean can be specified as a Boolean string or integer. In order to use this resource, XmNbuttonLabels should be set to False 👑 (that's the catch — set it or it won't work)
• XmNrowLabelAlignment — specifies the alignment of the row labels. It can be one of XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER or XmALIGNMENT_END. See the description of XmNalignment for XmLabel(3X). XmNrowLabelAlignment defaults to XmALIGNMENT_END 🎯
• XmNrowLabelColor — a Pixel value in which to draw the XmNrowLabels 🖍️
• XmNrowLabelWidth — how wide your row labels get to be. Defaults to the width of the longest row label, so it auto-sizes unless you're like "no bestie, I want this width." 💅
• XmNrowLabels — points to an array of Strings that get drawn to the left of each row. Each String can have embedded newline characters and then the label draws on multiple lines, which is lowkey iconic. If there's an XmNxmRowLabels defined for that row, it shows that instead of the XmNrowLabels. If both XmNrowLabels and XmNxmRowLabels are NULL, no labels get drawn at all, nada. This resource is copied.
• XmNrowHeightInPixels — tells you whether the elements of XmNrowHeights are measured in pixels or in lines. Pick your unit, bestie 📏
• XmNrowHeights — points to an array of short, one for each row. Each one says how tall the visible height of the cells in that row is. This resource is copied.
• XmNrowShadowTypes — sets the XmNcellShadowType on a per-row basis, like a little shadow outfit for each row 👑 Values are the same as for XmNcellShadowType. This resource is copied.
• XmNrowUserData — points to a user-defined data area that's associated with a particular row. Set it with XbaeMatrixSetRowUserData() and get it back with XbaeMatrixGetRowUserData(). This resource cannot be specified in a resource file, so don't even try it 🫶
• XmNrows — the total number of rows of cells. XmNrows must be at least one. If you change the number of rows via XtSetValues, then XmNrowLabels must change too or be NULL. The preferred way to dynamically change the number of rows is XbaeMatrixAddRows() or XbaeMatrixDeleteRows(), so go through the official door bestie.
• XmNscrollBarPlacement — determines where the scrollbars get drawn. See the discussion of XmNscrollBarPlacement in XmScrolledWindow(3) for the full tea on this resource.
• XmNselectCellCallback — a list of callbacks that get called from the SelectCell() action. A pointer to an XbaeMatrixSelectCellCallbackStruct gets passed to the callbacks. Your app can use this callback list to do selection/deselection of cells using the provided widget methods ✨
• XmNselectScrollVisible — whether the matrix scrolls to make the selected cell visible. This flag is only checked when cells are selected programmatically, because when the user picks a cell with the mouse it's already visible, obviously 🙈
• XmNselectedBackground — lets you specify the background of selected cells in XmNselectedCells.
• XmNselectedCells — points to an array of pointers to rows. Each row is an array of Boolean values, one for each column in that row. Same data structure as XmNcells, except every entry is a Boolean instead of a String. A cell gets drawn as selected if the corresponding Boolean is True. If XmNselectedCells is NULL, then no cells have been selected. This resource is copied, and it cannot be specified in a resource file 🚫
• XmNselectedForeground — lets you specify the foreground of selected cells in XmNselectedCells.
• XmNshadowType — the type of shadow drawn around the border of the matrix. Possible values are XmSHADOW_OUT, XmSHADOW_IN, XmSHADOW_ETCHED_OUT, and XmSHADOW_ETCHED_IN. The default shadow type is XmSHADOW_OUT.
• XmNshowArrows — whether arrows should be drawn when data in a cell has been obscured because of the value of XmNcolumnWidths. Little "hey there's more over here" vibes ⭐
• XmNspace — the distance that separates the ScrollBars from the cell grid. Default value is 4 pixels. Personal space matters 🎀
• XmNtextBackground — the background of the XmText cell edit widget. Use it to make the XmText stand out against a uniformly colored matrix, main character energy 💖
• XmNtextBackgroundIsCell — specifies whether the background of the XmText cell edit widget defaults to the core background of the matrix or the background of the cell being edited, when XmNtextBackground has the value XmUNSPECIFIED_PIXEL.
• XmNtextField — the widget ID of the XmText. This resource cannot be set to a new value, it's read-only bestie.
• XmNtextShadowThickness — the XmNshadowThickness of the XmText. Interesting effects can be achieved by setting the XmNcellHighlightThickness to 0 and replacing the highlight with an indented shadow. Go off, customizer 💅
• XmNtextTranslations — the XmNtranslations resource of the XmText cell edit widget. See the description of XmNtranslations in XmText(3X).
• XmNtopRow — the row which should be displayed at the top of the non-fixed rows. XmNtopRow is specified relative to the first non-fixed row, so (XmNfixedRows + XmNtopRow) is the actual row number that gets moved to the top. If (XmNtopRow > (XmNrows - (<number of rows visible> + XmNfixedRows), then the actual row moved to the top is (XmNrows - (<number of rows visible> + XmNfixedRows). Math, but make it fashion 🧮
• XmNtrackCellCallback — a list of callbacks that get called when the mouse pointer is being moved.
• XmNtrailingAttachedBottom — indicates that any trailing fixed rows should be attached to the bottom of the matrix. This resource only has an effect when XmNfill is true and XmNtrailingFixedRows is greater than zero.
• XmNtrailingAttachedRight — indicates that any trailing fixed columns should be attached to the right of the matrix. This resource only has an effect when XmNfill is true and XmNtrailingFixedColumns is greater than zero.
• XmNtrailingFixedColumns — the number of trailing columns (starting from the right column) which should not be horizontally scrollable. XmNtrailingFixedColumns must be less than XmNcolumns-XmNfixedColumns. Cells in trailing fixed columns are not editable unless XmNtraverseFixedCells is set to True. Locked in place 🔒
• XmNtrailingFixedRows — the number of trailing rows (starting from the bottom row) which should not be vertically scrollable. XmNtrailingFixedRows must be less than XmNrows-XmNfixedRows. Cells in trailing fixed rows are not editable unless XmNtraverseFixedCells is set to True.
• XmNtraverseCellCallback — a list of callbacks to be called before a new cell is edited. These get called by the EditCell() action and when XbaeMatrix receives or looses focus. A pointer to an XbaeMatrixTraverseCellCallbackStruct is passed to the callbacks. Your app can specify the next cell that should be edited via this callback list, thereby performing custom traversal. So you're basically directing traffic 🚦
• XmNtraverseFixedCells — if True, this resource allows fixed cells and columns to be edited. The default is to not allow fixed rows or columns to be edited, no cap.
• XmNuseXbaeInput — this boolean value determines whether to use XbaeInput or XmTextField as the widget used for editing cells. Default is not to use XbaeInput.
• XmNvalueChangedCallback — a list of callbacks to be called after text is deleted from or inserted into the XmText cell edit widget. A pointer to an XbaeMatrixValueChangedCallbackStruct is passed to the callbacks. See the description of the XmText(3X) XmNvalueChangedCallback resource.
• XmNverticalScrollBar — the widget ID of the vertical XmScrollBar. This resource only exists for those applications that need to tie another scrollbar to the matrix's for synchronized scrolling 🌀 This resource can not be set to a new value.
• XmNverticalScrollBarDisplayPolicy — determines when to display a horizontal scrollbar in the matrix. Possible values and their effects are listed under XmNhorizontalScrollBarDisplayPolicy. (Yes, it says horizontal. That's what the page says, bestie, I don't make the rules 🙈)
• XmNvisibleColumns — the number of non-fixed columns which should be visible. The widget will request a size which will allow XmNvisibleColumns columns to be displayed. The programmer should take into allowance any XmNfixedColumns that are specified. This feature becomes even more apparent if the number of XmNfixedColumns changes at runtime, as the value may need to be adjusted to avoid a warning ⚠️
• XmNvisibleRows — the number of rows which should be visible at any one time. The widget will request a size which will allow XmNvisibleRows rows to be displayed.
• XmNwrapType — when XmNmultiLineCell is true, this resource specifies how to break the lines. Set it to XbaeWrapNone and lines break on newlines only. Set it to XbaeWrapContinuous and long lines get further broken up so they fit in their cell. Set it to XbaeWrapWord and the breaking of long lines occurs preferably on spaces. Choose your fighter 🌸
• XmNwriteCellCallback — a list of callbacks to be called when a cell value changes and an XmNdrawCellCallback is defined. A pointer to an XbaeMatrixWriteCellCallbackStruct is passed to the callbacks. The XmNwriteCellCallback allows data to be written back into the application's data structure and must be defined for an editable XbaeMatrix with an XmNdrawCellCallback. Like, mandatory mandatory 👑
• XmNxmRowLabels — points to an array of XmStrings to be drawn to the left of each row. If XmNxmRowLabels is NULL, XmNrowLabels will be used. This resource is copied.
• XmNxmColumnLabels — points to an array of XmStrings to be drawn above each column. If XmNxmColumnLabels is NULL, XmNcolumnLabels will be used. This resource is copied.

---

🌈 INHERITED RESOURCES 🌈

Okay so the following table lists the resources which XbaeMatrix inherits from its superclasses XmManager, Composite and Core. For a complete description of each resource, refer to the man page for that superclass, they've got the full lore 📚

The codes in the ``Access'' column indicate whether the given resource can be set at creation time (C), or set by using XtSetValues (S), or retrieved by using XtGetValues (G).

🫶 XmManager Resource Set (the hand-me-downs from your manager bestie)

Okay so these are the resources XbaeMatrix inherits from XmManager — you didn't ask for them, but they're part of the package, and honestly? Some of them are cute. 💅

• XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG. The colour of the bottom shadow, i.e. the little 3D lie that makes your widget look raised. ✨
• XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG. Same energy as above, but a pixmap instead. If you don't set it you get XmUNSPECIFIED_PIXMAP, no cap.
• XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG. The actual colour of your text and drawings. Main character of the colour story, fr fr.
• XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG. The colour used when something's highlighted — the little sparkle when you're the chosen one 👑.
• XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG. Pixmap version of the highlight vibe.
• XmNinitialFocus — class XmCInitialFocus, type Widget, default NULL, access CSG. Which widget gets the focus first. Default NULL means nobody's volunteering 🙈.
• XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG. How keyboard traversal treats this widget. Default is XmTAB_GROUP, iykyk.
• XmNshadowThickness — class XmCShadowThickness, type Dimension, default dynamic, access CSG. How thick the 3D shadow is. Big number = big drama.
• XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG. Which way your strings read. Note the access is just CG here, not CSG — literally the only rebel in the list 🦋.
• XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG. Top shadow colour. The light source of the whole situation ✨.
• XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG. Pixmap flavour of the top shadow. Yes, again.
• XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG. Is keyboard traversal allowed to visit you? Default True. Don't be a hermit 🫶.
• XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG. The unit type for all your measurements. unsigned char, bestie. That's the whole type. 💀
• XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG. A little pocket for whatever you want to stash on the widget. Default NULL, so it starts empty — go fill it with your hopes and dreams 🎀.

---

🌈 Composite Resource Set (the kids)

These come from Composite, aka "the widget that has children". Very mother energy 💜.

• XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G. The list of child widgets. Read-only (G only!), so you can look but you cannot touch 🫣.
• XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG. A procedure that decides where a new child gets inserted in the order. Default NULL, meaning the default behaviour just happens, and honestly? Let it. ✨
• XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G. How many children live here. Default 0, read-only (G). Counting is a spectator sport tonight, bestie 💅.

Heads up: those two G-only resources (XmNchildren and XmNnumChildren) are read-only — you're not setting those, the toolkit is. Clock it now so you don't embarrass yourself later 😭.

💖 Core Resource Set 💖

Okay bestie, this is the core resource lineup. Every row keeps its class, type, default, and access exactly where it belongs — no cap, no dropped details. ✨

• XmNaccelerators — class XmCAccelerators, type XtAccelerators, default NULL, 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 1, 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 💬

🫶 XbaeMatrixAnyCallbackStruct

This one is the universal callback struct — suitable for all callbacks that need reason, event, row, and column available. So any callback that gets called can cast the third parameter to this struct in XbaeMatrix and trust that everything in it will be there waiting for you. 💅

            typedef struct
            {
                 XbaeReasonType   reason;
                 int              row;
                 int              column;
                 XEvent           *event;
            } XbaeMatrixAnyCallbackStruct;

Each member gets set to whatever’s appropriate for that callback. ✨

If casting the third parameter feels a little foreign, the recommended reading is literally K&R II page 213. 📚

🎯 XmNdefaultActionCallback

Callbacks on the XmNdefaultActionCallback list get called when the DefaultAction() action occurs. The application can bind the DefaultAction() action to any pointer based event. When a double click happens on this pointer event, DefaultAction() will call the callbacks on the XmNdefaultActionCallback list. A pointer to the following structure is passed to each callback on the XmNdefaultActionCallback list:

            typedef struct
            {
                    XbaeReasonType       reason;
                    XEvent               *event;
                    int                  row;
                    int                  column;
            } XbaeMatrixDefaultActionCallbackStruct;

• reason — set to XbaeDefaultActionReason.
• event — the event that invoked this callback.
• row — the row number of the cell where the double click occurred.
• column — the column number of the cell where the double click occurred.

event — yep, the original lists it again down here too; it’s still the event that invoked this callback. 🙈

If an application has an XmNdefaultActionCallback, then the callbacks on the list will be called when the user clicks twice in a cell within XmNdoubleClickInterval, enabling some action to occur for that particular cell. 🔥

🎨 XmNdrawCellCallback

Callbacks on the XmNdrawCellCallback list get called when the widget needs to draw a cell. A pointer to the following structure is passed to each callback on the XmNdrawCellCallback list:

typedef struct
{
     XbaeReasonType    reason;
     XEvent            *event;
     int               row;
     int               column;
     int               width;
     int               height;
     XbaeCellType      type;
     String            string;
     Pixmap            pixmap;
     Pixmap            mask;
     Pixel             foreground;
     Pixel             background;
     int               depth;
} XbaeMatrixDrawCellCallbackStruct;

• reason — gets set to XbaeDrawCellReason, bestie, that's just how it is ✨
• event — always NULL. Like, always. don't come for me, it's just built that way 🙈
• row — which row the cell that needs drawing lives in
• column — which column that same cell is chillin' in
• width — how wide the cell that needs drawing is
• height — how tall the cell that needs drawing is
• type — the type of "data" the programmer wants drawn in the cell, or, lowkey, which field should be peeked at for data to draw: string or pixmap. iykyk 💅
• string — the string to draw if type is set to XbaeString or XbaeStringFree
• pixmap — the pixmap to copy if type is set to XbaePixmap. it will be clipped to width by height if necessary, no cap
• mask — a mask for the pixmap as obtained from the XPM library. mask is only necessary when pixmap has a depth greater than one 🎀
• foreground — the foreground color of the cell
• background — the background color of the cell
• depth — the depth of the pixmap image (in bits per pixel)

So here's the vibe: if the application adds this callback, then whenever XbaeMatrix figures out that a cell at (row, column) needs to be redrawn, the normal cell drawing mechanism gets skipped and this callback gets called instead — so the app can tell the widget what to put in the cell. main character callback energy, honestly 👑

The type field is defaulted to XbaeString, and no cacheing or saving of the string or pixmap is done. literally none. don't expect it 🫶

If the application sets type to XbaePixmap, the width, height and depth of the returned pixmap will be calculated with a call to XGetGeometry(). If the programmer wishes to supply the width, height and depth there is a marked improvement as a round trip to the X server is avoided — yes bestie, skipping the server round trip is the glow-up ✨ Note that all geometry parameters must be supplied to ensure successful display of the pixmap. all of them. not some. all 💀

If a mask is also provided, it will be used to display the pixmap transparently. Pixmaps drawn in cells also respect the value of XmNcolumnAlignments. slay 💅

By defining an XmNdrawCellCallback the need for the storage of the XbaeMatrix data within the matrix is eliminated and can prove to be advantageous for memory usage. your RAM will thank you fr fr 🌸

To write the data back to the application, use the XmNwriteCellCallback described below.

XmNenterCellCallback

Callbacks on the XmNenterCellCallback list are called from the EditCell() action just before a cell is edited, to determine it's editability. A pointer to the following structure is passed to each callback on the XmNenterCellCallback list:

typedef struct
{
    XbaeReasonType   reason;
    XEvent           *event;
    int              row;
    int              column;
    int              position;
    String           pattern;
    Boolean          auto_fill;
    Boolean          convert_case;
    Boolean          overwrite_mode;
    Boolean          select_text;
    Boolean          map;
    Cardinal         num_params;
    String           *params;
    Boolean          doit;
} XbaeMatrixEnterCellCallbackStruct;

• reason — set to XbaeEnterCellReason ✨
• event — the event that invoked the callback
• row — the row number of the cell about to be edited
• column — the column number of the cell about to be edited
• position — the location of the cursor in the text field. the default is to place the cursor at the end of the string in the cell 🎀
• pattern — a pattern for the XbaeInput widget (see XbaeInput(3)). the default is to not specify a pattern
• auto_fill — used in conjunction with the setting of the pattern to allow literals in the pattern to be automatically inserted
• convert_case — if the pattern specifies an upper or lower case letter, the character typed in the position can automatically be converted to the appropriate case when set to True. the default is to not convert the case of the typed letter 🔤
• overwrite_mode — normally, the cursor appears as the familiar I caret. by setting overwrite_mode to True, the text field will go into overwrite mode where keystrokes replace the character underneath the block cursor
• select_text — indicates whether the text in the cell should be highlighted (only valid if doit is set to True also 👀)
• map — tells the matrix if the XmText should be mapped onto the cell. only makes sense if doit is set to False
• num_params — the number of String parameters passed to the EditCell() action
• params — an array containing the num_params String parameters passed to the EditCell() action
• doit — indicates whether or not this cell is editable. setting doit to False will make this cell not editable. the default value is True ✅

If the application determines that the cell at (row, column) is not editable, it should set the doit flag to False. If the map flag is also set to False, XbaeMatrix will not place the XmText cell editor on the cell. If map is left as True, the XmText will be placed on the cell but the user will not be able to add or delete characters from it. rude, but okay 💀

If the application leaves doit as True, then the TextField will be editable. In addition, if select_text is set to True, the text in the cell will be selected via XmTextSetSelection. Assuming XmNpendingDelete for the XmText is also True, the selected text will be deleted as soon as the next text insertion occurs — so like, type once and the highlight's gone, periodt ✨

XmNlabelActivateCallback

Callbacks on the XmNlabelActivateCallback list are called after a button label has been activated via a mouse click. A pointer to the following structure is passed to each callback on the XmNlabelActivateCallback list:

typedef struct
{
       XbaeReasonType      reason;
       XEvent              *event;
       int                 row;
       int                 column;
       Boolean             row_label;
       String              label;
} XbaeMatrixLabelActivateCallbackStruct;

• reason — set to XbaeLabelActivateReason 🌈
• event — the event that invoked this callback
• row — the row number of the button label, or -1 if the button was a column label
• column — the column number of the button label, or -1 if the button was a row label
• row_label — if the button label that invoked the callback is a row label, then this value is set to True. if it was a column label then it is set to False 🎯
• label — the label on the button that was pressed

When the XbaeMatrix receives a ButtonRelease event on the same button label that it received a ButtonPress event, the XmNlabelActivateCallback is called to allow the programmer to respond to the event. The callback has been provided to emulate some popular spreadsheets on the market. iconic spreadsheet behavior ngl 👑

XmNleaveCellCallback

Callbacks on the XmNleaveCellCallback list are called from the EditCell() and CommitEdit() actions just before the edit to the current cell is committed. The application can validate the changes made to the cell, and allow or disallow them — like a little bouncer for your data 🫶 A pointer to the following structure is passed to each callback on the XmNleaveCellCallback list:

typedef struct
{
     XbaeReasonType    reason;
     XEvent            *event;
     int               row, column;
     String            value;
     Boolean           doit;
} XbaeMatrixLeaveCellCallbackStruct;

• reason — set to XbaeLeaveCellReason ✨
• event — the event that invoked this callback
• row — the row number of the cell being edited
• column — the column number of the cell being edited
• value — contains the new data which will be stored in this cell if doit is True. the memory pointed to by value may be modified, or if the new contents are larger than the current contents, then value should be set to point to a larger piece of allocated memory ⚠️ like, actually do this, don't just vibe and overflow
• doit — indicates whether the edits applied to this cell should actually be stored into XbaeMatrix. setting doit to False will cause the changes to be discarded and the cell will retain its original value. the default value is True 💖

If the application determines that the value entered in the cell at (row, column) is not valid, it should set the doit flag to False. This will prevent the changes from being stored in the cell. The TextField edit widget will remain on the current cell. If the application leaves doit as True, then the changes made to the cell will be committed and the TextField will move to the next cell or be unmapped. The application can also modify the String in value, e.g. to force a String to be all upper case. yes, force it. make it SCREAM 🔥

XmNmodifyVerifyCallback

Callbacks on the XmNmodifyVerifyCallback list are called while a cell is being edited. The callbacks are called before text is inserted into or deleted from the TextField edit widget. A pointer to the following structure is passed to each callback on the XmNmodifyVerifyCallback list:

typedef struct
{
    XbaeReasonType               reason;
    XEvent                       *event;
    int                          row;
    int                          column;
    XmTextVerifyCallbackStruct   *verify;
    const char                   *prev_text;
} XbaeMatrixModifyVerifyCallbackStruct;

okay so the fields lowkey go like this, bestie:

• reason — set to XbaeModifyVerifyReason.
• event — always NULL, no cap.
• row — the row number of the cell being edited.
• column — the column number of the cell being edited.
• verify — the contents of this structure and its use are documented in the XmText(3X) man page.
• prev_text — the contents of the cell as seen by this user before the new text. If other text has already been entered, this value will not match the official XbaeMatrix value of the cell. This pointer and the string should not be modified.

XmNprocessDragCallback 🫶

Callbacks on the XmNprocessDragCallback list are called from the ProcessDrag() action. The application can bind the ProcessDrag() action to any pointer based event, though by default it is bound to the Button2Down event. When this event occurs, ProcessDrag() will call the callbacks on the XmNprocessDragCallback list. A pointer to the following structure is passed to each callback on the XmNprocessDragCallback list:

typedef struct
{
      XbaeReasonType      reason;
      XEvent              *event;
      int                 row;
      int                 column;
      String              string;
      XbaeCellType        type;
      Pixmap              pixmap;
      Pixmap              mask;
      Cardinal            num_params;
      String              *params;
} XbaeMatrixProcessDragCallbackStruct;

• reason — set to XbaeProcessDragReason.
• event — the XEvent which invoked the ProcessDrag() action.
• row — the row number of the cell where the drag was initiated.
• column — the column number of the cell where the drag was initiated.
• string — the string in the cell where the drag was initiated if type is XbaeString or XbaeStringFree. This is provided as a convenience to the application.
• type — the type of the cell in which the drag was initiated.
• pixmap — the pixmap in the cell where the drag was initiated if type is XbaePixmap. This is provided as a convenience to the application.
• mask — a mask for the pixmap as obtained from the XPM library. mask is only necessary when pixmap has a depth greater than one. Also provided as a convenience to the application.
• num_params — the number of String parameters passed to the ProcessDrag() action.
• params — an array containing the num_params String parameters passed to the ProcessDrag() action.

The application can use the XmNprocessDragCallback list to implement particular processing for Motif's drag-and-drop.

---

XmNresizeCallback 🌸

Callbacks on the XmNresizeCallback list are called when the XbaeMatrix widget is resized. A pointer to the following structure is passed to each callback on the XmNresizeCallback list:

typedef struct
{
      XbaeReasonType     reason;
      XEvent             *event;
      int                row;
      int                column;
      Dimension          width;
      Dimension          height;
} XbaeMatrixResizeCallbackStruct;

• reason — set to XbaeResizeReason.
• event — always set to NULL.
• row — set to the number of rows in the matrix (provided for convenience).
• column — set to the number of columns in the matrix (provided for convenience).
• width — the new width of the XbaeMatrix widget.
• height — the new height of the XbaeMatrix widget.

The application can use the XmNresizeCallback to adjust such resources as XmNcolumnWidths, XmNvisibleColumns and XmNvisibleRows when the widget containing an XbaeMatrix widget is resized.

---

XmNresizeColumnCallback 🎀

Callbacks on the XmNresizeColumnCallback list are called when a column of the XbaeMatrix widget is dynamically resized by the user. A pointer to the following structure is passed to each callback on the XmNresizeColumnCallback list:

typedef struct
{
     XbaeReasonType     reason;
     XEvent             *event;
     int                row;
     int                column;
     int                which;
     int                columns;
     short              *column_widths;
} XbaeMatrixResizeColumnCallbackStruct;

• reason — set to XbaeResizeColumnReason.
• event — the XEvent that ended the resize. The event will be of type XButtonReleasedEvent.
• row — the row in which the ResizeColumn() action began.
• column — the column in which the ResizeColumn() action began (and ended).
• which — the column that was resized in the ResizeColumn() action.
• columns — the number of columns in the XbaeMatrix widget.
• column_widths — the widths of each column as they stand after the ResizeColumn() action.

The application can use the XmNresizeColumnCallback to perform post processing after a column has been resized. By adjusting the values contained in column_widths the XbaeMatrix widget will use the values upon return from the callback.

Changing the number of columns in the matrix in the XmNresizeColumnCallback should be used carefully as it may cause unexpected results.

---

XmNselectCellCallback ✨

Callbacks on the XmNselectCellCallback list are called from the SelectCell() action. The application can bind the SelectCell() action to any pointer based event. When this event occurs, SelectCell() will call the callbacks on the XmNselectCellCallback list. A pointer to the following structure is passed to each callback on the XmNselectCellCallback list:

typedef struct
{
    XbaeReasonType   reason;
    XEvent           *event;
    int              row;
    int              column;
    Boolean          **selected_cells;
    String           **cells;
    Cardinal         num_params;
    String           *params;
} XbaeMatrixSelectCellCallbackStruct;

• reason — set to XbaeSelectCellReason.
• event — the XEvent which invoked the SelectCell() action.
• row — the row number of the cell which was selected.
• column — the column number of the cell which was selected.
• selected_cells — the value of the XmNselectedCells resource. This is provided as a convenience to the application and will be NULL if no cells have yet been selected.
• cells — the value of the XmNcells resource. This is provided as a convenience to the application and will be NULL if no cells have been specified or the XmNdrawCellCallback is being used.
• num_params — the number of String parameters passed to the SelectCell() action.
• params — an array containing the num_params String parameters passed to the SelectCell() action.

The application can use the XmNselectCellCallback list to implement its own selection model. The XbaeMatrixSelectCellCallbackStruct contains the array of String parameters passed to the SelectCell() action which invoked this callback. By binding the SelectCell() action to various events via the translation manager, and using String action parameters to distinguish them, the application can implement various selection models. For example, the following translations could be used to implement a model in which a modifier key indicates whether a single cell or an entire row should be selected. The callbacks on the XmNselectCellCallback list would examine the parameter and take the appropriate action.

            #override\n\
                            Shift<Btn1Down>:   SelectCell(cell)\n\
                            Ctrl<Btn1Down>:    SelectCell(row)

The callbacks on the XmNselectCellCallback list can also be used in other ways, e.g. to pop up a cell specific menu.

NOTE: If no cells have been selected, the value of selected_cells will be NULL. The same applies for cells. Care must be taken so as not to dereference these members of the callback struct.

---

XmNtrackCellCallback 🦋

Callbacks on the XmNtrackCellCallback list are being called by the HandleTracking() action, which is triggered by pointer motion. One of the purposes of this callback list is to figure out from which cell to which cell the pointer is being moved. A pointer to the XbaeMatrixTrackCellCallbackStruct structure is being passed. Its fields are defined as:

typedef struct _XbaeMatrixTrackCellCallbackStruct
{
      XbaeReasonType     reason;
      XEvent             *event;
      int                row, column;
      int                prev_row, prev_column;
      Position           pointer_x, pointer_y;
} XbaeMatrixTrackCellCallbackStruct;

• reason — set to XbaeSelectCellReason.
• event — the XEvent which invoked the HandleTracking() action.
• row — this is the row number that the pointer is currently in.
• column — this is the column number that the pointer is currently in.
• prev_row — the row that the pointer was previously in.
• prev_column — the column that the pointer was previously in.
• pointer_x — the x position of the pointer.
• pointer_y — the y position of the pointer.

💅 XmNtraverseCellCallback — the ✨who-goes-next✨ committee

Callbacks on the XmNtraverseCellCallback list get pinged from the EditCell() action, and also whenever XbaeMatrix either receives or loses focus. Basically: any time we're like "okay which cell are we on now, bestie?" — these callbacks get a say. The app can fully customize cell traversal this way. XbaeMatrix has a default traversal order (breakdown below, keep scrolling 🫶) and the app can override it, no cap. Every callback on the list gets handed a pointer to this struct:

typedef struct
{
    XbaeReasonType   reason;
    XEvent           *event;
    int              row;
    int              column;
    int              next_row;
    int              next_column;
    int              fixed_rows;
    int              fixed_columns;
    int              trailing_fixed_rows;
    int              trailing_fixed_columns;
    int              num_rows;
    int              num_columns;
    String           param;
    XrmQuark         qparam;
} XbaeMatrixTraverseCellCallbackStruct;

• reason — set to XbaeTraverseCellReason.
• event — the event that invoked this callback.
• row — the row number of the cell currently being edited.
• column — the column number of the cell currently being edited.
• next_row — the row number of the next cell to be edited. The app can change this, it's fair game ✨
• next_column — the column number of the next cell to be edited. Also changeable by the app.
• fixed_rows — the value of the XmNfixedRows resource. It's here purely as a convenience, so the app can compute next_row and next_column without reaching for the resource itself.
• fixed_columns — the value of the XmNfixedColumns resource. Same deal, convenience only, for calculating next_row and next_column.
• trailing_fixed_rows — the value of the XmNtrailingFixedRows resource. Again: convenience for the next_row/next_column math.
• trailing_fixed_columns — the value of the XmNtrailingFixedColumns resource. Convenience, next_row/next_column, you already know the drill 💅
• num_rows — the value of the XmNrows resource. Convenience for computing next_row and next_column.
• num_columns — the value of the XmNcolumns resource. Convenience for computing next_row and next_column.
• param — the String value of the parameter passed to the EditCell() action.
• qparam — the XrmQuark value of the parameter passed to the EditCell() action.

So the EditCell() action takes an arbitrary parameter and passes it straight through to the XmNtraverseCellCallback callbacks in both String and XrmQuark flavors. Iconic of it. 🎀

EditCell() recognizes five special parameters that it uses to pull off its default cell traversal. Here's what each one does:

• Pointer — set next_row and next_column to the cell underneath the mouse pointer. 🖱️
• Left — if we're currently editing cell (XmNfixedRows, XmNfixedColumns), then do not move. Otherwise, move one column to the left; if that column is less than XmNfixedColumns, then move up to the last column of the row above.
• Right — if we're currently editing cell (XmNrows - 1, XmNcolumns - 1), then do not move. Otherwise, move one column to the right; if that column is greater than or equal to XmNcolumns, then move down to column XmNfixedColumns of the row below.
• Up — move up one row. If that row is less than XmNfixedRows, then move to the last row.
• Down — move down one row. If that row is greater than or equal to XmNrows, then move to row XmNfixedRows.

If EditCell() recognizes one of these special parameters, it computes the new cell to be edited accordingly and drops the results into the next_row and next_column fields of the XbaeMatrixTraverseCellCallbackStruct. If EditCell() does not recognize its parameter, it sets next_row and next_column to the current row and column. Either way it also stores a String and an XrmQuark version of its parameter in the param and qparam fields. Then EditCell() calls the callbacks on the XmNtraverseCellCallback list — and those callbacks can peek at the parameter and recalculate next_row and next_column however they want. 🔥

The application can override the default calculation for those special parameters, or define a whole brand-new parameter with its own brand-new calculation — you'd do that by binding EditCell() with a new application-specific parameter to an event in a translation table. And the expectation is that app callbacks will use the XrmQuark version of the parameter for efficiency reasons (by statically creating the new XrmQuarks and comparing them against the incoming qparam). iykyk ⚡

When XbaeMatrix receives the focus, it also calls the XmNtraverseCellCallback callbacks before returning to the current cell — or the upper left most visible cell if no cell is currently edited. The XbaeMatrixTraverseCellCallbackStruct will have param and qparm set to Focus. And if there's no current cell, row and column get set to -1.

When XbaeMatrix loses the focus, it also calls the XmNtraverseCellCallback with param and qparm set to LoosingFocus. 👋

---

🌸 XmNvalueChangedCallback — live updates while you type

Callbacks on the XmNvalueChangedCallback list fire while a cell is being edited. They're called after text is inserted into or deleted from the TextField edit widget. Each callback on the list gets a pointer to this:

typedef struct
{
      XbaeReasonType  reason;
      XEvent  *event;
      int     row;
      int     column;
} XbaeMatrixValueChangedCallbackStruct;

• reason — set to XbaeValueChangedReason.
• event — the event that triggered this callback.
• row — the row number of the cell being edited.
• column — the column number of the cell being edited.

---

🦋 XmNwriteCellCallback — pushing data back into a cell

Callbacks on the XmNwriteCellCallback list (though honestly it probably only makes sense to have one of them 💀) are called when the widget needs to write data to a cell — but only when XmNdrawCellCallback is defined. Each callback gets a pointer to this struct:

typedef struct
{
       XbaeReasonType     reason;
       XEvent             *event;
       int                row;
       int                column;
       XbaeCellType       type;
       String             string;
       Pixmap             pixmap;
       Pixmap             mask;
} XbaeMatrixWriteCellCallbackStruct;

• reason — set to XbaeWriteCellReason.
• event — always set to NULL.
• row — the row number of the cell that needs to be written.
• column — the column number of the cell that needs to be written.
• type — the type of "data" contained in the cell, either XbaeString or XbaePixmap.
• string — the string to store if type is set to XbaeString.
• pixmap — the pixmap to store if type is set to XbaePixmap. (Maybe a lil meaningless unless you can edit a pixmap in a cell 🙈)
• mask — a mask for the pixmap as obtained from the XPM library. mask is only necessary when pixmap has a depth greater than one.

If the app adds this callback, then when the XbaeMatrix is editable and has been assigned an XmNdrawCellCallback, data on the widget can be edited and stored back in the application's data structure. 🔁 And fr fr: only if an XmNdrawCellCallback has been assigned to the XbaeMatrix widget will the XmNwriteCellCallback be called.

At the moment, pixmap and mask will be sent to the XmNwriteCellCallback as NULL. Yeah. Nothing. 💀

---

✨ Translations ✨

XbaeMatrix inherits translations from XmManager. On top of that, XbaeMatrix uses the following translation:

:<Btn1Up>:                 DefaultAction()\n\
:<Btn1Down>:               DefaultAction() EditCell(Pointer)\n\
:Shift<Btn2Down>:          ResizeColumns()\n\
:<Btn2Down>:               ProcessDrag()\n\
:<Btn1Motion>:             HandleMotion() HandleTracking()()\n\
:<Motion>:                 HandleTracking()()\n\
:<Btn4Down>:               ScrollRows(-50)()\n<Btn5Down>:

And XbaeMatrix installs the following default XmNtextTranslations on the TextField edit widget:

#override\n\
Shift ~Ctrl ~Meta ~Alt <Key>Tab:   EditCell(Left)\n\
~Ctrl ~Meta ~Alt <Key>Tab:         EditCell(Right)\n\
<Key>osfUp:                        EditCell(Up)\n\
<Key>osfDown:                      EditCell(Down)\n\
<Key>osfActivate:                  CommitEdit(False)\n\
~Shift ~Meta ~Alt <Key>Return:     CommitEdit(False)\n\
<Key>osfCancel:                    CommitEdit(False)\n\
Shift Ctrl ~Meta ~Alt <Key>Tab:    TraversePrev()\n\
Ctrl ~Meta ~Alt <Key>Tab:          TraverseNext()\n\
<Key>osfPageDown:                  PageDown()\n\
<Key>osfPageUp:                    PageUp()\n

Tab goes right, Shift+Tab goes left, arrows go up and down, and Ctrl+Tab / Ctrl+Shift+Tab traverse. Keyboard navigation? Ate. ⌨️💅

🎬 Action Routines

Okay so these are the action routines, and every parameter detail is staying right here — no cap. 💅

💅 CancelEdit()

If the single parameter to CancelEdit() is the String True, then it unmaps the edit TextField, discarding any changes which were made to the cell being edited. If the parameter is False, then CancelEdit() restores the edit TextField to the original contents of the cell, discarding any changes made to the cell being edited. The TextField is not unmapped.

✨ CommitEdit()

CommitEdit() first calls any callbacks on the XmNleaveCellCallback list to determine if the changes made to the current cell are valid. If they are, it then saves any changes made to the cell into the cell. If the callbacks on the XmNleaveCellCallback list return that the changes are not valid, CommitEdit() does nothing.

If the changes are valid, CommitEdit() examines its one parameter, which must be the string True or False. If the parameter is True, then the edit TextField is unmapped. If it is False, then the TextField is not unmapped.

🖱️ DefaultAction()

DefaultAction() sets up a mechanism for determining whether two successive mouse clicks form a double click. DefaultAction() should normally be used in conjunction with other pointer based events and provides a mechanism for acting on double clicks in a cell.

🧚 EditCell()

EditCell() edits a new cell. EditCell() first calculates the new cell to edit based on its single parameter. It then calls the callbacks on the XmNtraverseCellCallback list to allow them to specify a different cell to edit (see the discussion of XmNtraverseCellCallback above). EditCell() then calls the callbacks on the XmNleaveCellCallback list to determine if the changes made to the current cell are valid. If they are, it then saves any changes made to the cell into the cell. If the changes are not valid, EditCell() does nothing further.

If the changes are valid, EditCell() attempts to scroll the new cell to be edited so that it is fully visible. If the new cell is in a fixed row or column, EditCell() returns and does nothing further (these cells are not editable). Otherwise, EditCell() calls the callbacks on the XmNenterCellCallback list to determine if the new cell is editable. It then moves the XmText edit widget to the new cell, setting its editability based on the return from the XmNenterCellCallback callbacks.

🌀 ProcessDrag()

ProcessDrag() calls the callbacks on the XmNprocessDragCallback list, passing them a pointer to a XbaeMatrixProcessDragCallbackStruct.

📐 ResizeColumns()

Allows the user to dynamically resize the column widths, provided that XmNallowColumnResize is True.

↕️ ScrollRows()

ScrollRows() makes the rows of the matrix scroll by the pixel amount specified by its argument.

↔️ ScrollColumns()

ScrollColumns() makes the columns of the matrix scroll by the pixel amount specified by its argument.

🎯 SelectCell()

SelectCell() calls the callbacks on the XmNselectCellCallback list, passing them a pointer to a XbaeMatrixSelectCellCallbackStruct. This structure will contain the String parameters passed to the SelectCell() action, among other things (see the discussion of XmNselectCellCallback above).

➡️ TraverseNext()

TraverseNext() will traverse out of the Matrix and into the next tab group.

⬅️ TraversePrev()

TraversePrev() will traverse out of the Matrix and into the previous tab group.

⬇️ PageDown()

PageDown() causes the Matrix to scroll down a full page. The text widget is placed on the first non fixed row of the new page.

⬆️ PageUp()

PageUp() causes the Matrix to scroll up a full page. The text widget is placed on the first non fixed row of the new page.

---

🔄 Type Converters

In addition to the standard type converters registered by Xt and Motif, XbaeMatrix registers the following additional type converters:

🔤 CvtStringToStringArray()

Converts a comma separated list of Strings to an array of String pointers, one for each substring. Commas in the list may be escaped with the character \. This converter allows the XmNrowLabels and XmNcolumnLabels resources to be specified in resource files.

📏 CvtStringToWidthArray()

Converts a comma separated list of numeric Strings to an array of short integers. This converter allows the XmNcolumnWidths resource to be specified in resource files.

📐 CvtStringToMaxLengthArray()

Converts a comma separated list of numeric Strings to an array of integers. This converter allows the XmNcolumnMaxLengths resource to be specified in resource files.

🧭 CvtStringToAlignmentArray()

Converts a comma separated list of alignments to an array of unsigned chars. This converter allows the XmNcolumnLabelAlignments and XmNcolumnAlignments resources to be specified in resource files.

🪟 CvtStringToGridType()

Converts a single string as discussed in XmNgridType to a grid type value. This converter allows XmNgridType to be specified in resource files.

🎚️ CvtStringToMatrixScrollBarDisplayPolicy()

Converts a single string as discussed in XmNhorizontalScrollBarDisplayPolicy and XmNverticalScrollBarDisplayPolicy to a display policy value. This converter allows XmNhorizontalScrollBarDisplayPolicy and XmNverticalScrollBarDisplayPolicy to be specified in resource files.

🧩 CvtStringToCellTable()

Converts a comma separated list of Strings with \n delimited rows to a two dimensional array of String pointers. This converter allows the XmNcells resource to be specified in resource files.

🎨 CvtStringToPixelTable()

Converts a comma separated list of color names with \n delimited rows to a two dimensional array of Pixel values. This converter allows the XmNcellBackgroundsandXmNcolors resources to be specified in resource files. (Yes, the page runs those resource names together exactly like that.)

✅ CvtStringToBooleanArray()

Converts a comma separated list of string or numeric values to an array of Booleans. The converter recognises a comma separated list of values. Heads up, the source sentence is glitched: “Each value is parsed such that if the first character is This converter allows the XmNcolumnButtonLabels and XmNrowButtonLabels resources to be specified in resource files.”

---

🛠️ Public Functions

The following external entry points to XbaeMatrix class methods are defined:

🌟 XbaeCreateMatrix()

Widget XbaeCreateMatrix()
    Widget      parent;
    String      name;
    ArgList     arglist;
    Cardinal    argcount;

• parent — Specifies the parent widget ID.
• name — Specifies the name of the created widget.
• arglist — Specifies the argument list.
• argcount — Specifies the number of attribute/value pairs in the argument list (arglist).

XbaeCreateMatrix() creates an unmanaged instance of an XbaeMatrix widget and returns the associated widget ID.

🧱 XbaeMatrixAddColumns()

void XbaeMatrixAddColumns()
    Widget     w;
    int        position;
    String     *columns;
    String     *labels;
    short      *widths;
    int        *max_lengths;
    unsigned   char *alignments;
    unsigned   char *label_alignments;
    Pixel      *colors;
    int        num_columns;

• w — An XbaeMatrix widget.
• position — The column position before which to add the new columns. Must be greater than or equal to zero, and less than or equal to XmNcolumns.
• columns — Points to an ordinary two dimensional array of String, or NULL. These Strings will be used to modify the XmNcells resource to populate the new columns. Each row in the array must have XmNrows elements and represents one of the new columns. columns must have num_columns rows. If columns is NULL, empty columns will be added.
• labels — Points to an array of String, or NULL. These Strings will be used as the XmNcolumnLabels for the new columns. The labels array must have num_columns elements. If labels is NULL, and XmNcolumnLabels is set, then blank column labels will be used.
• widths — Points to an array of short or NULL. These values will be used as the XmNcolumnWidths for the new columns. The widths array must have num_columns elements. if widths is NULL then a default width will be used for the new columns.
• max_lengths — Points to an array of int, or NULL. These values will be used as the XmNcolumnMaxLengths for the new columns. The max_lengths array must have num_columns elements. If max_lengths is NULL, then the corresponding value from widths will be used.
• alignments — Points to an array of unsigned char, or NULL. These values will be used as the XmNcolumnAlignments for the new columns. The alignments array must have num_columns elements. If alignments is NULL, then XmALIGNMENT_BEGINNING will be used.
• label_alignments — Points to an array of unsigned char, or NULL. These values will be used as the XmNcolumnLabelAlignments for the new column labels. The label_alignments array must have num_columns elements. If label_alignments is NULL, then XmALIGNMENT_BEGINNING will be used.
• colors — Points to an array of Pixel, or NULL. These values will be used to set the corresponding columns in the XmNcolors table for the new columns. The colors array must have num_columns elements. If colors is NULL, then XmNforeground will be used.
• num_columns — The number of columns which are being added to the widget.

Oh and bestie — one thing to know about the column stuff before we even start:

So XbaeMatrixAddColumns() is literally your girl for sliding brand-new columns into the Matrix dynamically, anywhere you want. The columns get added before the column you name in position. Columns are numbered starting at zero (classic), and if you wanna just slap new columns onto the end of the Matrix, you set position to the total number of columns. Most of the arguments to XbaeMatrixAddColumns() can just be NULL — the widget will pick default values for you, no stress. ✨

⚠️ Okay but real talk: if you try to add columns with XbaeMatrixAddColumns() when there are no rows, you get a warning message. There must be at least one row in the XbaeMatrix widget to add columns. That's just the rules, sorry bestie 😭

And for backward compatibility reasons (vintage, iconic), the cell backgrounds cannot be set in a call to XbaeMatrixAddColumns() — if you want them, you gotta do it in a separate call to XtVaSetValues(). Periodt.

---

XbaeMatrixAddRows()

void XbaeMatrixAddRows()
     Widget   w;
     int      position;
     String   *rows;
     String   *labels;
     Pixel    *colors;
     int      num_rows;

• w — an XbaeMatrix widget. The main character 💅
• position — the row position before which to add the new rows. Has to be greater than or equal to zero, and less than or equal to XmNrows.
• rows — points to an ordinary two dimensional array of String, or NULL. These Strings get used to modify the XmNcells resource to populate the new rows. Each row in the array must have XmNcolumns elements and represents one of the new rows. rows must have num_rows rows. If rows is NULL, you get empty rows added. 🫶
• labels — points to an array of String, or NULL. These Strings get used as the XmNrowLabels for the new rows. The labels array must have num_rows elements. If labels is NULL, and XmNrowLabels is set, then blank row labels will be used.
• colors — points to an array of Pixel, or NULL. These values set the corresponding rows in the XmNcolors table for the new rows. The colors array must have num_rows elements. If colors is NULL, then XmNforeground will be used.
• num_rows — the number of rows which are being added to the widget.

XbaeMatrixAddRows() lets the application developer dynamically add new rows anywhere in the Matrix. The rows get added before the row specified in position. Rows are numbered starting at zero, and to append new rows onto the end of the Matrix, you specify position as the total number of rows. So easy. 🌸

To maintain backward compatibility, the cell backgrounds cannot be set in a call to XbaeMatrixAddRows() and must be set (if so desired) in a separate call to XtVaSetValues().

---

XbaeMatrixCancelEdit()

void XbaeMatrixCancelEdit()
      Widget       w;
      Boolean      unmap;

• w — an XbaeMatrix widget.
• unmap — specifies whether the TextField cell edit widget should be unmapped after the edit is canceled.

XbaeMatrixCancelEdit() lets the application developer programmatically cancel a cell edit that's in progress, yeeting any changes the user made. This function unmaps the TextField edit widget if the unmap flag is True. If unmap is False, the contents of the TextField are restored to their original value, and the TextField is not unmapped. Choose your fighter 💀

---

XbaeMatrixCommitEdit()

Boolean XbaeMatrixCommitEdit()
       Widget        w;
       Boolean       unmap;

• w — an XbaeMatrix widget.
• unmap — specifies whether the TextField cell edit widget should be unmapped after an edit is successfully committed.

XbaeMatrixCommitEdit() can be used by the application developer to programmatically commit an edit, saving any changes made by the user. This will cause the callbacks on the XmNleaveCellCallback list to be called to verify that the changes the user made are valid. If the changes are valid, then they get saved into the cell, and if the unmap flag is True, the TextField widget will be unmapped. Signed, sealed, delivered 🔥

---

XbaeMatrixDeleteColumns()

void XbaeMatrixDeleteColumns()
      Widget    w;
      int       position;
      int       num_columns;

• w — an XbaeMatrix widget.
• position — the column position at which to begin deleting columns. Must be greater than or equal to zero, and (position + num_columns) must be less than or equal to XmNcolumns.
• num_columns — the number of columns to delete from the widget.

XbaeMatrixDeleteColumns() lets the application developer dynamically delete columns from anywhere in the Matrix. Columns will be deleted starting at the column specified by position. Bye bye bestie 👋

---

XbaeMatrixDeleteRows()

void XbaeMatrixDeleteRows()
      Widget    w;
      int       position;
      int       num_rows;

• w — an XbaeMatrix widget.
• position — the row position at which to begin deleting rows. Must be greater than or equal to zero, and (position + num_rows) must be less than or equal to XmNrows.
• num_rows — the number of rows to delete from the widget.

XbaeMatrixDeleteRows() lets the application developer dynamically delete rows from anywhere in the Matrix. Rows will be deleted starting at the row specified by position.

---

XbaeMatrixDeselectAll()

void XbaeMatrixDeselectAll()
        Widget        w;

• w — an XbaeMatrix widget.

XbaeMatrixDeselectAll() lets the application developer programmatically deselect all the cells. XbaeMatrixDeselectAll() redraws the cells in normal video, and all Booleans in the XmNselectedCells array will be set to False. Clean slate energy ✨

---

XbaeMatrixDeselectCell()

void XbaeMatrixDeselectCell()
       Widget      w;
       int         row;
       int         column;

• w — an XbaeMatrix widget.
• row — the row of the cell to deselect.
• column — the column of the cell to deselect.

XbaeMatrixDeselectCell() lets the application developer programmatically deselect a single cell. XbaeMatrixDeselectCell() redraws the cell in normal video, and the corresponding Boolean in the XmNselectedCells array will be set to False. One at a time, we love precision 🎀

---

XbaeMatrixDeselectColumn()

void XbaeMatrixDeselectColumn()
        Widget      w;
        int         column;

• w — an XbaeMatrix widget.
• column — the column to deselect.

XbaeMatrixDeselectColumn() lets the application developer programmatically deselect a whole column. XbaeMatrixDeselectColumn() draws the column in normal video, and the corresponding Booleans in the XmNselectedCells array will be set to False.

---

XbaeMatrixDeselectRow()

void XbaeMatrixDeselectRow()
        Widget      w;
        int         row;

• w — an XbaeMatrix widget.
• row — the row to deselect.

XbaeMatrixDeselectRow() lets the application developer programmatically deselect a row. XbaeMatrixDeselectRow() draws the row in reverse video (or selectedForeground / selectedBackground if set). The corresponding Booleans in the XmNselectedCells array will be set to False.

👀 Yes bestie, that's exactly what the page says — we're not editing the lore, we're just vibing with it.

---

XbaeMatrixDisableRedisplay()

int XbaeMatrixDisableRedisplay()
          Widget        w;

• w — an XbaeMatrix widget.

XbaeMatrixDisableRedisplay() and XbaeMatrixEnableRedisplay() let an application make multiple changes to a matrix without immediate visual updates. When multiple changes are made with redisplay enabled, visual flashing often occurs. (So tacky 😭) These routines help eliminate this problem. It's giving glow-up-in-private 💅

---

XbaeMatrixEditCell()

void XbaeMatrixEditCell()
      Widget    w;
      int       row;
      int       column;

• w — an XbaeMatrix widget.
• row — the row of the cell to be edited.
• column — the column of the cell to be edited.

XbaeMatrixEditCell() allows the application developer to programmatically force a specific cell to be edited. Here's the whole run of show, in order, no skipping:

1. This function will first attempt to commit the edit in the current cell.
2. If the XmNleaveCellCallback callbacks disallow this commit, then XbaeMatrixEditCell() will return.
3. Otherwise the specified cell is scrolled until it is visible.
4. If the specified cell is in a fixed row or column, it cannot be edited and XbaeMatrixEditCell() will return.
5. Next, the callbacks on the XmNenterCellCallback callback list are called for the specified cell to determine it's editability.
6. Then the TextField edit widget is mapped on top of the specified cell.

It's giving ✨ process ✨ and honestly? Obsessed.

---

XbaeMatrixEnableRedisplay()

int XbaeMatrixEnableRedisplay()
      Widget       w;
      Boolean      redisplay;

• w — an XbaeMatrix widget.
• redisplay — force the matrix to redisplay if True and no other calls to XbaeMatrixDisableRedisplay() have been made.

XbaeMatrixDisableRedisplay() and XbaeMatrixEnableRedisplay() let an application make multiple changes to a matrix without immediate visual updates. When multiple changes are made with redisplay enabled, visual flashing often occurs. These routines help eliminate this problem. Tag team, unstoppable 🫶

---

XbaeMatrixEventToXY()

Boolean XbaeMatrixEventToXY()
      Widget      w;
      XEvent      *event;
      int         *x;
      int         *y;

• w — an XbaeMatrix widget.
• event — an X event structure pointer, usually from an XEventHandler function.
• x — the translated x coordinate.
• y — the translated y coordinate.

XbaeMatrixEventToXY enables the programmer to determine the x and y values of a given event with respect to the XbaeMatrix widget. The returned values are also adjusted to allow for the XbaeClip widget. Coordinate translation, but make it cute 🦋

---

XbaeMatrixFirstSelectedCell()

XbaeMatrixFirstSelectedCell()

void XbaeMatrixFirstSelectedCell()
        Widget        w;
        int           *row;
        int           *column;

• w — an XbaeMatrix widget, bestie.
• row — the first selected row, dropped right in here.
• column — the first selected column, same deal.

XbaeMatrixFirstSelectedCell() is literally your "who's first tho" function 💅 it lets you, the application developer, find out which cell is the first selected one. It does this by traversing the XbaeMatrix widget left to right, top to bottom — like reading a book but make it grid — to figure out the value. And if nothing is selected? Then row and column both get set to -1. Iconic "no thoughts, empty grid" behaviour 🫶

---

XbaeMatrixFirstSelectedColumn()

int XbaeMatrixFirstSelectedColumn()
           Widget         w;

• w — an XbaeMatrix widget.

XbaeMatrixFirstSelectedColumn() returns the column number of the first selected column in the widget, and it starts its little journey from column 0. ⭐ Heads up though: a column has to be entirely selected before it counts as selected — no half-vibes allowed. If no column is selected, it hands you back -1. 😭

---

XbaeMatrixFirstSelectedRow()

int XbaeMatrixFirstSelectedRow()
          Widget        w;

• w — an XbaeMatrix widget.

Same energy, different axis 🌸 XbaeMatrixFirstSelectedRow() returns the row number of the first selected row in the widget, traversing from row 0. And again, the row has to be entirely selected to be considered selected. No row selected? You get -1, sorry bestie 💀

---

XbaeMatrixGetCell()

String XbaeMatrixGetCell()
      Widget     w;
      int        row;
      int        column;

• w — an XbaeMatrix widget.
• row — the row of the cell whose value should be retrieved.
• column — the column of the cell whose value should be retrieved.

XbaeMatrixGetCell() returns the String value stored in the cell you point at. 🔥 Big important thing: this String should not be freed — it is not yours to release, hands off 🙈

And if you're planning to peek at many cells, it's way more efficient to do an XtGetValues() on XmNcells and just examine the values in that array instead of calling this over and over. Efficiency is the moment ✨

---

XbaeMatrixGetCellBackground()

Pixel XbaeMatrixGetCellBackground()
         Widget        w;
         int           row;
         int           column;

• w — a XbaeMatrix widget.
• row — the row of the cell whose background color should be retrieved.
• column — the column of the cell whose background color should be retrieved.

Background colour of a cell, on demand 💖 that's it, that's the function.

---

XbaeMatrixGetCellColor()

Pixel XbaeMatrixGetCellColor()
       Widget       w;
       int          row;
       int          column;

• w — a XbaeMatrix widget.
• row — the row of the cell whose foreground color should be retrieved.
• column — the column of the cell whose foreground color should be retrieved.

Foreground colour this time 🎀 the Pixel you get back is the cell's foreground, gorgeous.

---

XbaeMatrixGetCellPixmap()

int XbaeMatrixGetCellPixmap()
       Widget     w;
       int        row;
       int        column;
       Pixmap     *pixmap;
       Pixmap     *mask;

• w — a XbaeMatrix widget.
• row — the row of the cell whose pixmap and mask should be retrieved.
• column — the column of the cell whose pixmap and mask should be retrieved.
• pixmap — a pointer to a Pixmap variable, and the function stores the cell's pixmap in there for you.
• mask — a pointer to a Pixmap variable, and the function stores the cell's pixmap mask in there.

Two outputs, one call, very efficient of it honestly 🦋

---

XbaeMatrixGetCellTag()

XmStringTag XbaeMatrixGetCellTag()
         Widget       w;
         int          row;
         int          column;

• w — a XbaeMatrix widget.
• row — the row of the cell whose tag should be retrieved.
• column — the column of the cell tag should be retrieved.

XbaeMatrixGetCellTag returns the font tag of the indicated cell. And the application should not modify or free the returned value — look with your eyes, not your hands 💅 no cap.

---

XbaeMatrixGetCellUserData()

XtPointer XbaeMatrixGetCellUserData()
          Widget        w;
          int           row;
          int           column;

• w — an XbaeMatrix widget.
• row — the row of the cell whose data should be retrieved.
• column — the column of the cell whose data should be retrieved.

XbaeMatrixGetCellUserData() gives you a pointer to the data assigned to the cell at those coordinates 🫶 that data should've been set with XbaeMatrixSetCellUserData(). And if there's nothing associated with that particular cell? NULL. Empty. Void. Nothing there bestie 🌸

---

XbaeMatrixGetColumnWidth()

int XbaeMatrixGetColumnWidth()
       Widget       w;
       int          column;

• w — an XbaeMatrix widget.
• column — the column whose width we're querying.

XbaeMatrixGetColumnWidth() is just a convenient way to query a column width. Short king 👑

---

XbaeMatrixGetColumnLabel()

String XbaeMatrixGetColumnLabel()
        Widget        w;
        int           column;

• w — an XbaeMatrix widget.
• column — the column of the label that should be retrieved.

XbaeMatrixGetColumnLabel() returns a pointer to the label of the given column. If no column labels exist, or the given column isn't a valid column, you get NULL. And if no data is found associated with that particular column — yeah, also NULL. 😭 it's giving "we tried, there's nothing".

---

XbaeMatrixGetColumnUserData()

XtPointer XbaeMatrixGetColumnUserData()
          Widget          w;
          int             column;

• w — an XbaeMatrix widget.
• column — the column of the cell whose data should be retrieved.

XbaeMatrixGetColumnUserData() returns a pointer to the data assigned to the given column, which you should've set with XbaeMatrixSetColumnUserData(). Nothing found for that column? NULL, as always 🫠

---

XbaeMatrixGetCurrentCell()

void XbaeMatrixGetCurrentCell()
       Widget       w;
       int          *row;
       int          *column;

• w — an XbaeMatrix widget.
• row — the row of the cell the ``cursor'' or TextField is in.
• column — the column of the cell the ``cursor'' or TextField is in.

XbaeMatrixGetCurrentCell() lets you, the application developer, figure out exactly which cell is being edited or has focus. Main character cell detection ✨

---

XbaeMatrixGetEventRowColumn()

int XbaeMatrixGetEventRowColumn()
        Widget       w;
        XEvent       *event;
        int          *row;
        int          *column;

• w — an XbaeMatrix widget.
• event — an X event structure pointer. This usually comes from an XEventHandler function. It can be either a button or a key event.
• row — the row of the cell the ``cursor'' or TextField is in.
• column — the column of the cell the ``cursor'' or TextField is in.

XbaeMatrixGetEventRowColumn() lets the application developer figure out which cell corresponds to an (x, y) inside an event. 🎯 If the (x, y) of the event lands on a legal cell, then row and column get set and True is returned. But — and this is the important part 🔥 — if the (x, y) isn't over a cell at all, it returns False, and row and column are left with undefined values. Don't trust them. Don't read them. They're in their flop era 💀

---

XbaeMatrixGetNumSelected()

int XbaeMatrixGetNumSelected()
         Widget        w;

• w — an XbaeMatrix widget.

XbaeMatrixGetNumSelected() returns how many cells are currently selected in the given matrix. 👑 And here's the slay: the widget keeps an internal variable updated as cells get selected and deselected, so it avoids doing a whole complete traversal of the widget. Fast. Efficient. No notes. ⭐

---

XbaeMatrixGetRowHeight()

int XbaeMatrixGetRowHeight()
        Widget      w;
        int         row;

• w — an XbaeMatrix widget.
• row — the row whose height we query.

XbaeMatrixGetRowHeight() is a convenient way to query a row height. Matching set with XbaeMatrixGetColumnWidth(), we love symmetry 🎀

---

XbaeMatrixGetRowLabel()

String XbaeMatrixGetRowLabel()
        Widget        w;
        int           row;

• w — an XbaeMatrix widget.
• row — the row of the label that should be retrieved.

XbaeMatrixGetRowLabel() returns a pointer to the label of the given row. If no row labels exist, or the given row isn't a valid row — NULL. That's the whole vibe check 🦋

---

XbaeMatrixGetRowUserData()

XtPointer XbaeMatrixGetRowUserData()
          Widget          w;
          int             row;

• w — an XbaeMatrix widget.
• row — the row of the cell whose data should be retrieved.

XbaeMatrixGetRowUserData() returns a pointer to the data assigned to the given row — data that should've been set via XbaeMatrixSetRowUserData(). If no data is found associated with that particular row, NULL comes back to you. 🙈

---

XbaeMatrixGetXmColumnLabel()

XmString XbaeMatrixGetXmColumnLabel()
          Widget        w;
          int           column;

• w — an XbaeMatrix widget.
• column — the column of the xmLabel that should be retrieved.

XbaeMatrixGetXmColumnLabel() returns a pointer to the xmLabel of the given column. If no xmColumnLabels exist, or the given column isn't a valid column, it's NULL. And if no data is found associated with that particular column, also NULL. Three ways to get nothing, honestly so generous of it 😭

---

XbaeMatrixGetXmRowLabel()

XmString XbaeMatrixGetXmRowLabel()
          Widget        w;
          int           row;

• w — an XbaeMatrix widget.
• row — the row of the xmLabel that should be retrieved.

XbaeMatrixGetXmRowLabel() returns a pointer to the xmLabel of the given row. No xmRowLabels, or an invalid row → NULL. No data associated with that particular row → also NULL. Consistently consistent 💅

---

XbaeMatrixHighlightCell()

void XbaeMatrixHighlightCell()
       Widget       w;
       int          row;
       int          column;

• w — an XbaeMatrix widget.

💅 XbaeMatrixHighlightCell()

void XbaeMatrixHighlightCell()
        Widget       w;
        int          row;
        int          column;

• w — an XbaeMatrix widget, bestie. the one and only.
• row — the row of the cell you wanna highlight.
• column — the column of the cell you wanna highlight.

so XbaeMatrixHighlightCell() is your girl for highlighting a cell programmatically, no mouse required 🫶 it literally draws the highlight around the cell, and the matching unsigned char in the XmNhighlightedCells array gets its HighlightCell bit set. that's it. that's the whole vibe. ✨

---

🌸 XbaeMatrixHighlightColumn()

void XbaeMatrixHighlightColumn()
        Widget       w;
        int          column;

• w — an XbaeMatrix widget.
• column — the column to highlight.

XbaeMatrixHighlightColumn() lets you highlight a whole column programmatically 💖 and here's the lil plot twist: if XmNgridType is XmGRID_COLUMN_SHADOW it draws the highlight around the column itself, and otherwise it draws it around each cell in the column instead. either way the corresponding unsigned chars in the XmNhighlightedCells array get their HighlightColumn or HighlightOther bit set — which one depends on whether XmNgridType is XmGRID_COLUMN_SHADOW or not. no cap, that's the whole rule. 👑

---

🦋 XbaeMatrixHighlightRow()

void XbaeMatrixHighlightRow()
        Widget       w;
        int          row;

• w — an XbaeMatrix widget.
• row — the row to highlight.

same energy, different axis, bestie 🌈 XbaeMatrixHighlightRow() highlights a row programmatically. if XmNgridType is XmGRID_ROW_SHADOW the highlight goes around the row, otherwise it goes around each cell in the row. the matching unsigned chars in XmNhighlightedCells get HighlightRow or HighlightOther set, depending on whether XmNgridType is XmGRID_ROW_SHADOW or not. symmetry ate that, honestly. ⭐

---

🎀 XbaeMatrixIsCellSelected()

Boolean XbaeMatrixIsCellSelected()
         Widget       w;
         int          row;
         int          column;

• w — an XbaeMatrix widget.
• row — the row of the cell to check.
• column — the column of the cell to check.

the vibe check function 💀 XbaeMatrixIsCellSelected() tells you whether a particular cell is selected or not: returns True if it's selected, False otherwise. simple as. 🙈

---

🍓 XbaeMatrixIsCellVisible()

Boolean XbaeMatrixIsCellVisible()
        Widget        w;
        int           row;
        int           column;

• w — an XbaeMatrix widget.
• row — the row of the cell to check.
• column — the column of the cell to check.

XbaeMatrixIsCellVisible() tells you whether a particular cell is actually in the visible area of the XbaeMatrix widget rn 👀 returns True if it's visible, False if it's off living its truth somewhere in the scroll void. 💜

---

🧚 XbaeMatrixIsColumnSelected()

Boolean XbaeMatrixIsColumnSelected()
         Widget         w;
         int            column;

• w — an XbaeMatrix widget.
• column — the column of the matrix to check.

XbaeMatrixIsColumnSelected() answers "is this column selected?" — True if yes, False if no. ⚠️ but listen: a column has to be selected in its entirety for this to return True. like, the whole thing. all of it. no partial credit, bestie. 💅

---

🌺 XbaeMatrixIsColumnVisible()

Boolean XbaeMatrixIsColumnVisible()
         Widget        w;
         int           column;

• w — an XbaeMatrix widget.
• column — the column of the matrix to check.

XbaeMatrixIsColumnVisible() — is that column chillin' inside the visible area of the XbaeMatrix widget? True if yes, False otherwise. lowkey the most straightforward function on this whole page. 🎀

---

🔥 XbaeMatrixIsRowSelected()

Boolean XbaeMatrixIsRowSelected()
         Widget         w;
         int            row;

• w — an XbaeMatrix widget.
• row — the row of the matrix to check.

XbaeMatrixIsRowSelected() — is this row selected? True/False, you know the drill. and same caveat as her column sister: the row must be selected in its entirety for this to return True. partial selections don't count, fr fr. 😭

---

⭐ XbaeMatrixIsRowVisible()

Boolean XbaeMatrixIsRowVisible()
         Widget        w;
         int           row;

• w — an XbaeMatrix widget.
• row — the row of the matrix to check.

XbaeMatrixIsRowVisible() — is this row in the visible area of the XbaeMatrix widget? True if it's showing, False if it's not. 🦋

---

👑 XbaeMatrixMakeCellVisible()

int XbaeMatrixMakeCellVisible()
        Widget      w;
        int         row;
        int         column;

• w — an XbaeMatrix widget.
• row — the row to scroll into the visible area of the matrix.
• column — the column to scroll into the visible area of the matrix.

XbaeMatrixMakeCellVisible() scrolls a cell into the visible area of the XbaeMatrix widget, programmatically, on demand ✨ main character energy: the cell simply arrives. two things you gotta know tho:

heads up bestie — calling this function means XmNselectScrollVisible is ignored. like, straight up not consulted. 💀

and for a more accurate cell location after scrolling, the programmer should use the XmNleftColumn and XmNtopRow resources. iykyk. 🌈

---

🎀 XbaeMatrixNumRows()

int XbaeMatrixNumRows()
       Widget     w;

• w — an XbaeMatrix widget.

XbaeMatrixNumRows() returns the number of rows in the given matrix. that's it. that's the tweet. 💖

---

🦋 XbaeMatrixNumColumns()

int XbaeMatrixNumColumns()
        Widget      w;

• w — an XbaeMatrix widget.

XbaeMatrixNumColumns() returns the number of columns in the given matrix. count 'em. ⭐

---

💀 XbaeMatrixNumRows() (yes, again)

int XbaeMatrixNumRows()
       Widget     w;

• w — an XbaeMatrix widget.

XbaeMatrixNumRows() returns the number of rows in the given matrix. and yep — she's listed twice on this page, back to back-ish, same signature, same description. not a glitch on my end, bestie, the manpage really said it twice 💅 and honestly? iconic. consistent queen. we stan a function who knows exactly who she is. 🫶

---

🌸 XbaeMatrixRefresh()

void XbaeMatrixRefresh()
       Widget      w;

• w — an XbaeMatrix widget.

XbaeMatrixRefresh() forces the widget to redraw itself 🎨 and there's a genuinely useful scenario here: you know the widget's values changed, but the widget itself hasn't detected the change. the classic example — the quickest way to swap the values of 2 rows is to do an XtGetValues on XmNcells, swap the values of the 2 rows, then do an XtSetValues on XmNcells with the same StringTable variable. but because of the way the Intrinsics work, the widget won't see this change and will keep displaying the old values until a redraw happens from a resize or scroll event (assuming nothing else in the XtSetValues triggered a redraw). calling XbaeMatrixRefresh() makes the correct values get drawn and overcomes this limitation in the Intrinsics. 😭

ngl this function should rarely be needed — it's provided ``just in case''. the manpage said it, not me. 💀

---

🧚 XbaeMatrixRefreshCell()

void XbaeMatrixRefreshCell()
       Widget     w;
       int        row;
       int        column;

• w — an XbaeMatrix widget.
• row — the row of the cell to redraw.
• column — the column of the cell to redraw.

XbaeMatrixRefreshCell() redraws one specific cell of the matrix ✨ and she's particularly useful alongside the XbaeMatrixDrawCellCallback, because it lets you update the data without needing an explicit expose event. chef's kiss combo. 🤌

---

🍓 XbaeMatrixRefreshColumn()

void XbaeMatrixRefreshColumn()
       Widget       w;
       int          column;

• w — an XbaeMatrix widget.
• column — the column of the matrix to redraw.

XbaeMatrixRefreshColumn() redraws one specific column of the matrix — efficiently, thank you very much 💅 no wasted pixels in this house.

---

🌺 XbaeMatrixRefreshRow()

void XbaeMatrixRefreshRow()
       Widget       w;
       int          row;

• w — an XbaeMatrix widget.
• row — the row of the matrix to redraw.

XbaeMatrixRefreshRow() redraws one specific row of the matrix, and yes, efficiently 🌈 same energy as her column sister, just the other axis. periodt.

---

🔥 XbaeMatrixRowColToXY()

int XbaeMatrixRowColToXY()
      Widget     w;
      int        row;
      int        column;
      int        *x;
      int        *y;

• w — an XbaeMatrix widget.
• row — the row the of the cell in question.
• column — the column the of the cell in question.
• x — the x coordinate returned that represents the left coordinates of the given cell.
• y — the y coordinate returned that represents the upper coordinates of the given cell.

XbaeMatrixRowColToXY() figures out the coordinates of the upper left corner of a given cell 📍 super handy for drag and drop calculations.

⚠️ important: if the given widget isn't an XbaeMatrix widget, False is returned and the values of x and y are undefined. like, do not read them. do not pass go. undefined. 💀

---

⭐ XbaeMatrixSelectAll()

void XbaeMatrixSelectAll()
        Widget      w;

• w — an XbaeMatrix widget.

XbaeMatrixSelectAll() selects all the cells, programmatically, in one go 👑 it redraws the cells in reverse video, and every Boolean in the XmNselectedCells array gets set to True. all of them. the whole grid. select-all really said "i'll take everything". 🔥

---

💜 XbaeMatrixSelectCell()

void XbaeMatrixSelectCell()
      Widget      w;
      int         row;
      int         column;

• w — an XbaeMatrix widget.
• row — the row of the cell to select.
• column — the column of the cell to select.

...and then it draws the cell in reverse video (or in selectedForeground / selectedBackground if you've set those, bestie 💅). The matching Boolean in the XmNselectedCells array gets flipped to True.

XbaeMatrixSelectColumn()

              void XbaeMatrixSelectColumn()
                     Widget      w;
                     int         column;

• w — an XbaeMatrix widget ✨
• column — the column you wanna select

XbaeMatrixSelectColumn() lets you, the application developer, select a whole column programmatically. It first scrolls that column until it's actually visible on screen (no cap, it will find it), then draws the column in reverse video — or in selectedForeground / selectedBackground if you've set those. The corresponding Booleans in the XmNselectedCells array get set to True. Whole column, all the Trues, slay. 🎀

XbaeMatrixSelectRow()

              void XbaeMatrixSelectRow()
                     Widget      w;
                     int         row;

• w — an XbaeMatrix widget 🦋
• row — the row you wanna select

XbaeMatrixSelectRow() lets you select a row programmatically. Same little ritual: it scrolls the row until it's visible, then draws it in reverse video (or selectedForeground / selectedBackground if set). And yup — the corresponding Booleans in XmNselectedCells become True. Periodt. 💖

XbaeMatrixSetCell()

              void XbaeMatrixSetCell()
                  Widget   w;
                  int      row;
                  int      column;
                  const    String value;

• w — an XbaeMatrix widget 🌸
• row — the row of the cell whose value should be set
• column — the column of the cell whose value should be set
• value — the new value to set this cell to

XbaeMatrixSetCell() lets you set the value of one specific cell programmatically. Pro tip tho: if you're setting the values of many cells, it may be more efficient to just do an XtSetValues() on the XmNcells resource. Work smarter, not harder, iykyk. 💅

XbaeMatrixSetCellBackground()

              void XbaeMatrixSetCellBackground()
                       Widget       w;
                       int          row;
                       int          column;
                       Pixel        color;

• w — an XbaeMatrix widget 🧚
• row — the row of the cell whose background should be set
• column — the column of the cell whose background should be set
• color — the new color to which to set this cell's background

XbaeMatrixSetCellBackground() is the convenient lil way to specify and modify the XmNcellBackgrounds resource when you're changing the background of a single cell. Two vibes here:

• If XmNcellBackgrounds is NULL, then it will create a Pixel table initialized to XmNforeground — except for the cell you named in its arguments.
• If XmNcellBackgrounds is not NULL, then it changes the specified cell in that resource to the color you passed.

Either way, your cell is getting a glow-up. ✨

XbaeMatrixSetCellColor()

              void XbaeMatrixSetCellColor()
                     Widget      w;
                     int         row;
                     int         column;
                     Pixel       color;

• w — an XbaeMatrix widget 💜
• row — the row of the cell whose color should be set
• column — the column of the cell whose color should be set
• color — the new color to which to set this cell

XbaeMatrixSetCellColor() is the convenient way to specify and modify the XmNcolors resource when changing the color of a single cell. Same deal as its background twin:

• If XmNcolors is NULL, it creates a Pixel table initialized to XmNforeground except for the cell specified in its arguments.
• If XmNcolors is not NULL, it changes that specified cell in the resource to the color you gave it.

Text color, handled. 💅

XbaeMatrixSetCellPixmap()

              void XbaeMatrixSetCellPixmap()
                     Widget       w;
                     int          row;
                     int          column;
                     Pixmap       pixmap;
                     Pixmap       mask;

• w — a XbaeMatrix widget 🎀
• row — the row of the cell whose pixmap and mask should be set
• column — the column of the cell whose pixmap and mask should be set
• pixmap — the function will store the contents of this Pixmap variable
• mask — the function will store the contents of this variable as the pixmap mask

XbaeMatrixSetCellPixmap sets the pixmap and the associated mask of the indicated cell. Now listen: if the row or column are out of bounds, or the widget isn't an XbaeMatrix widget, then nothing is changed — this erroneous condition is silently ignored. No error, no drama, just vibes and no pixels. 💀

XbaeMatrixSetCellShadow()

              void XbaeMatrixSetCellShadow()
                  Widget          w;
                  int             row;
                  int             column;
                  unsigned char   shadow_type;

• w — an XbaeMatrix widget 🌈
• row — the row of the cell whose shadow should be set
• column — the column of the cell whose shadow should be set
• shadow_type — the value to which to set the cell's shadow

XbaeMatrixSetShadow() lets you programmatically set the shadow of a specified cell. Depth! Dimension! Main character energy for one single cell. ⭐

XbaeMatrixSetCellTag()

              void XbaeMatrixSetCellTag()
                   Widget        w;
                   int           row;
                   int           column;
                   XmStringTag   tag;

• w — an XbaeMatrix widget 🍓
• row — the row of the cell whose tag should be set
• column — the column of the cell whose tag should be set
• tag — the value to which to set the cell's tag

XbaeMatrixSetTag() lets you programmatically set the font tag of a specified cell. And heads up: this value is copied (quarkified). Not referenced, copied. 🫶

XbaeMatrixSetCellUserData()

              void XbaeMatrixSetCellUserData()
                     Widget         w;
                     int            row;
                     int            column;
                     XtPointer      data;

• w — an XbaeMatrix widget 🦋
• row — the row of the cell whose value should be set
• column — the column of the cell whose value should be set
• data — a pointer to a user defined data area

XbaeMatrixSetCellUserData() lets you programmatically set the user data of a specified cell. Same efficiency note as before: if you're setting the data value of lots of cells, it may be more efficient to do an XtSetValues() on the XmNcellUserData resource. And important — this resource is copied. 💜

XbaeMatrixSetCellWidget()

              void XbaeMatrixSetCellWidget(w, row, column, widget)
                             Widget              w;
                             int                 row;
                             int                 column;
                             Widget              widget;

XbaeMatrixSetCellWidget() is the function that attaches a widget to a matrix cell. You pick the cell by giving its row and column, and widget is the cell widget you want associated with that cell. XbaeMatrix will manage that cell widget's position and size so it's displayed inside the cell at all times — including when scrolling. Iconic behavior honestly.

Passing a NULL widget removes the link between a widget and its cell. Two rules, bestie: only one widget can be in a cell, and a widget should also be in only one cell at a time. No sharing, no polycule widgets. 🙈

XbaeMatrixSetCellWidget()

              void XbaeMatrixSetCellWidget(w, row, column, widget)
                             Widget              w;
                             int                 row;
                             int                 column;
                             Widget              widget;

Yes, it's here twice. The page said it twice, so I'm saying it twice. 💅

XbaeMatrixSetCellWidget() attaches a widget to a matrix cell. The cell is selected by specifying its row and column, and widget is the cell widget to be associated with that cell. XbaeMatrix manages the cell widget's position and size so it's displayed inside the cell at all times, including when scrolling.

Using a NULL widget removes the link between a widget and its cell. Only one widget can be in a cell, and a widget should also be in only one cell at a time. Same facts, same energy, take two. 🎬

XbaeMatrixSetColumnBackgrounds()

              void XbaeMatrixSetColumnBackgrounds()
                      Widget        w;
                      int           position;
                      Pixel         *colors;
                      int           num_colors;

• w — an XbaeMatrix widget 🌸
• position — the column position at which to begin applying the new backgrounds. Must be greater than or equal to zero, and (position + num_colors) must be less than or equal to XmNcolumns.
• colors — points to an array of Pixel. These specify the backgrounds for the cells in the specified columns. The colors array must have num_colors elements.
• num_colors — the number of colors in the colors array

XbaeMatrixSetColumnBackgrounds() is the convenient way to specify and modify the XmNcellBackgrounds resource when you're setting the background of an entire column (or several columns, we don't gatekeep 💅).

• If XmNcellBackgrounds is NULL, it creates a Pixel table initialized to XmNforeground except for the columns specified in its arguments.
• If XmNcellBackgrounds is not NULL, it changes the specified columns in that resource to the colors you handed over.

Watch the bounds, bestie: position ≥ zero, and position + num_colors ≤ XmNcolumns. Stay in range, stay blessed. ✨

XbaeMatrixSetColumnColors()

              void XbaeMatrixSetColumnColors()
                     Widget     w;
                     int        position;
                     Pixel      *colors;
                     int        num_colors;

• w — an XbaeMatrix widget 🌈
• position — the column position at which to begin applying the new colors. Must be greater than or equal to zero, and (position + num_colors) must be less than or equal to XmNcolumns.
• colors — points to an array of Pixel. These specify the colors for the cells in the specified columns. The colors array must have num_colors elements.
• num_colors — the number of colors in the colors array.

XbaeMatrixSetColumnColors() is the convenient way to specify and modify the XmNcolors resource when you're setting the color of a whole column (or columns, bestie, plural is fine 💅). If XmNcolors is NULL, then XbaeMatrixSetColumnColors() will create a Pixel table initialized to XmNforeground except for the columns specified in it's arguments. If XmNcolors is not NULL, then XbaeMatrixSetColumnColors() will changed the specified columns in that resource to the specified colors. ✨

XbaeMatrixSetColumnWidth()

void XbaeMatrixSetColumnWidth()
        Widget      w;
        int         column;
        int         width;

• w — an XbaeMatrix widget.
• column — the column whose width we'll be changing.
• width — the new width of this column. A column width can be 0 to hide a column. 🙈

XbaeMatrixSetColumnWidth() is a convenient way to change the width of a column without the need to allocate an array with column width numbers. Passing -1 as the new width will reset the column width to the default value. No cap, that's genuinely handy 🫶

XbaeMatrixSetColumnLabel()

void XbaeMatrixSetColumnLabel()
        Widget      w;
        int         column;
        String      value;

• w — an XbaeMatrix widget.
• column — the column of the label is to be set.
• value — the new value of the label.

XbaeMatrixSetColumnLabel() lets the application developer programmatically change the label of a specified column. Relabel eras, iconic behavior 🌸

XbaeMatrixSetColumnShadow()

void XbaeMatrixSetColumnShadow()
    Widget          w;
    int             column;
    unsidned char   shadow_type;

• w — an XbaeMatrix widget.
• column — the column for which the shadow to be set.
• shadow_type — the new value of the shadow.

okay so yes, unsidned is literally spelled like that in the source 💀 it's unsigned, she just woke up like this

XbaeMatrixSetColumnShadow() lets the application developer programmatically change the shadow of a specified column. Give that column some depth, bestie 💜

XbaeMatrixSetColumnUserData()

void XbaeMatrixSetColumnUserData()
        Widget         w;
        int            column;
        XtPointer      data;

• w — an XbaeMatrix widget.
• column — the column whose value should be set.
• data — a pointer to a user defined data area.

XbaeMatrixSetColumnUserData() lets the application developer programmatically associate user data for the specified column. Your data, your rules, your column 🎀

XbaeMatrixSetRowBackgrounds()

void XbaeMatrixSetRowBackgrounds()
       Widget       w;
       int          position;
       Pixel        *colors;
       int          num_colors;

• w — an XbaeMatrix widget.
• position — the row position at which to begin applying the new colors. Must be greater than or equal to zero, and (position + num_colors) must be less than or equal to XmNrows. ⚠️ do the math, bestie, she checks.
• colors — points to an array of Pixel. These specify the backgrounds for the cells in the specified rows. The colors array must have num_colors elements.
• num_colors — the number of colors in the colors array.

XbaeMatrixSetRowBackgrounds() is a convenient way to specify and modify the XmNcellBackgrounds resource when setting the background of an entire row or rows. If XmNcellBackgrounds is NULL, then XbaeMatrixSetRowBackgrounds() will create a Pixel table initialized to XmNforeground except for the rows specified in it's arguments. If XmNcellBackgrounds is not NULL, then XbaeMatrixSetRowBackgrounds() will changed the specified rows in that resource to the specified colors. Whole-row glow-ups, we love to see it 🌈

XbaeMatrixSetRowColors()

void XbaeMatrixSetRowColors()
      Widget    w;
      int       position;
      Pixel     *colors;
      int       num_colors;

• w — an XbaeMatrix widget.
• position — the row position at which to begin applying the new colors. Must be greater than or equal to zero, and (position + num_colors) must be less than or equal to XmNrows.
• colors — points to an array of Pixel. These specify the colors for the cells in the specified rows. The colors array must have num_colors elements.
• num_colors — the number of colors in the colors array.

XbaeMatrixSetRowColors() is a convenient way to specify and modify the XmNcolors resource when setting the color of an entire row or rows. If XmNcolors is NULL, then XbaeMatrixSetRowColors() will create a Pixel table initialized to XmNforeground except for the rows specified in it's arguments. If XmNcolors is not NULL, then XbaeMatrixSetRowColors() will changed the specified rows in that resource to the specified colors. ✨

XbaeMatrixSetRowHeight()

void XbaeMatrixSetRowHeight()
       Widget      w;
       int         row;
       int         height;

• w — an XbaeMatrix widget.
• row — the row whose height we'll be changing.
• height — the new height of this row. A row height can be 0 to hide a row. 🙈

XbaeMatrixSetRowHeight() is a convenient way to change the height of a row without the need to allocate an array with row height numbers. Passing -1 as the new height will reset the row's height to the default value. 🫶

XbaeMatrixSetRowLabel()

void XbaeMatrixSetRowLabel()
       Widget      w;
       int         row;
       String      value;

• w — an XbaeMatrix widget.
• row — the row of the label is to be set.
• value — the new value of the label.

XbaeMatrixSetRowLabel() lets the application developer programmatically change the label of the specified row. Main character row energy 👑

XbaeMatrixSetRowShadow()

void XbaeMatrixSetRowShadow()
    Widget          w;
    int             column;
    unsigned char   shadow_type;

• w — an XbaeMatrix widget.
• row — the row whose shadow should be set.
• shadow_type — the value of the new shadow.

ngl the signature up there names that int column even though the docs call it row — that's just how it's written, copy it as-is and don't come for me 💀

XbaeMatrixSetRowShadow() lets the application developer programmatically change the shadow for the specified row.

XbaeMatrixSetRowUserData()

void XbaeMatrixSetRowUserData()
       Widget        w;
       int           column;
       XtPointer     data;

• w — an XbaeMatrix widget.
• row — the row whose value should be set.
• data — a pointer to a user defined data area.

XbaeMatrixSetRowUserData() lets the application developer programmatically associate user data for the specified row. (Yes, same thing as above — the signature says column, the docs say row. It's giving chaos but it's canon 🌀)

XbaeMatrixSetXmColumnLabel()

void XbaeMatrixSetXmColumnLabel()
        Widget        w;
        int           column;
        XmString      value;

• w — an XbaeMatrix widget.
• column — the column of the xmLabel is to be set.
• value — the new value of the xmLabel.

XbaeMatrixSetXmColumnLabel() lets the application developer programmatically change the xmLabel of a specified column. XmString edition, for when plain String just isn't the vibe 🦋

XbaeMatrixSetXmRowLabel()

void XbaeMatrixSetXmRowLabel()
       Widget        w;
       int           row;
       XmString      value;

• w — an XbaeMatrix widget.
• row — the row of the xmLabel is to be set.
• value — the new value of the xmLabel.

XbaeMatrixSetXmRowLabel() lets the application developer programmatically change the xmLabel of a specified row. 💖

XbaeMatrixSortColumns()

void XbaeMatrixSortColumns()
    Widget   w;
    int      (*proc)(Widget, int, int, void *);
    void     *user_data;

• w — an XbaeMatrix widget.
• proc — a pointer to a function that can compare columns.
• user_data — a pointer the application can use for its own needs.

XbaeMatrixSortColumns allows you to sort the columns in the XbaeMatrix widget according to criteria determined by the proc function. The proc function should have the above signature and functionality as demanded by the qsort(3) function. It will be called with a the matrix being sorted, the indices of two columns to compare and the user_data pointer XbaeMatrixSortColumns was called with. It should return -1, 0, or 1 as appropriate. It is guaranteed that the matrix does not change while sorting and the necessary reordering will only take place after the last call to proc has been made. Sort it out, bestie, literally 🔥

XbaeMatrixSortRows()

void XbaeMatrixSortRows()
    Widget   w;
    int      (*proc)(Widget, int, int, void *);
    void     *user_data;

• w — an XbaeMatrix widget.
• proc — a pointer to a function that can compare rows.
• user_data — a pointer the application can use for its own needs.

XbaeMatrixSortRows allows you to sort the rows in the XbaeMatrix widget according to criteria determined by the proc function. The proc function should have the above signature and functionality as demanded by the qsort(3) function. It will be called with the matrix being sorted, the indices of two rows to compare and the user_data pointer XbaeMatrixSortRows was called with. It should return -1, 0, or 1 as appropriate. It is guaranteed that the matrix does not change while sorting and the necessary reordering will only take place after the last call to proc has been made. Same deal, different axis ⭐

XbaeMatrixUnhighlightAll()

void XbaeMatrixUnhighlightAll()
         Widget         w;

• w — an XbaeMatrix widget.

XbaeMatrixUnhighlightAll() — bestie, this is the “clear the whole glow-up board” button 💅. It lets you programmatically unhighlight all the cells, erasing the highlight from every single cell. Every unsigned char in the XmNhighlightedCells array gets set to HighlightNone. Periodt. ✨

XbaeMatrixUnhighlightCell()

void XbaeMatrixUnhighlightCell()
        Widget       w;
        int          row;
        int          column;

• w — an XbaeMatrix widget.
• row — the row of the cell to unhighlight.
• column — the column of the cell to unhighlight.

This one lets you programmatically unhighlight a single cell. It erases the highlight from that cell, and the corresponding unsigned char in the XmNhighlightedCells array will have its HighlightCell bit cleared. 🎀

XbaeMatrixUnhighlightColumn()

void XbaeMatrixUnhighlightColumn()
         Widget       w;
         int          column;

• w — an XbaeMatrix widget.
• column — the column to unhighlight.

XbaeMatrixUnhighlightColumn() lets you programmatically unhighlight a column. It erases the highlight from around the column if XmNgridType is XmGRID_COLUMN_SHADOW, or from around each cell in the column otherwise. The corresponding unsigned chars in the XmNhighlightedCells array will have their HighlightColumn or HighlightOther bit cleared, depending on whether XmNgridType is set to XmGRID_COLUMN_SHADOW or not. 🦋

XbaeMatrixUnhighlightRow()

void XbaeMatrixUnhighlightRow()
         Widget       w;
         int          row;

• w — an XbaeMatrix widget.
• row — the row to unhighlight.

XbaeMatrixUnhighlightRow() lets you programmatically unhighlight a row. It erases the highlight from around the row if XmNgridType is XmGRID_ROW_SHADOW, or from around each cell in the row otherwise. The corresponding unsigned chars in the XmNhighlightedCells array will have their HighlightRow or HighlightOther bit cleared, depending on whether XmNgridType is set to XmGRID_ROW_SHADOW or not. 🌸

XbaeMatrixVisibleCells()

int XbaeMatrixVisibleCells()
    Widget    w;
    int       *top_row;
    int       *bottom_row;
    int       *left_column;
    int       *right_column;

• w — an XbaeMatrix widget.
• top_row — the first row that is currently visible in the matrix.
• bottom_row — the last row that is currently visible in the matrix.
• left_column — the leftmost column that is currently visible in the matrix.
• right_column — the rightmost column that is currently visible in the matrix.

XbaeMatrixVisibleCells() lets you get the currently visible portion of the XbaeMatrix w. It’s giving “tell me what’s on screen right now” energy. 👀

XbaeMatrixVisibleColumns()

int XbaeMatrixVisibleColumns()
         Widget        w;

• w — an XbaeMatrix widget.

XbaeMatrixVisibleColumns() lets you programmatically check how many columns are currently displayed in the XbaeMatrix w. A partially visible column will be declared an entire column. No cap, that’s the rule. 💯

XbaeMatrixVisibleRows()

int XbaeMatrixVisibleRows()
        Widget       w;

• w — an XbaeMatrix widget.

XbaeMatrixVisibleRows() lets you programmatically check how many rows are currently displayed in the XbaeMatrix w. A partially visible row will be declared an entire row. Same energy, different axis. ⭐

XbaeGetVersionNum()

int XbaeGetVersionNum()

XbaeGetVersionNum() returns the numeric representation of the version of the Xbae library that your program is working with. This is the run-time version of the Xbae widgets, where XbaeVersion is a macro that represents the compile-time version. 🧚

The numeric representation is a simple calculation based on the major, minor, and pico numbers representing an Xbae widget release. E.g. version 4.8.1 would be represented as 40801.

Releases prior to 4.8.0 didn’t have this functionality. 🙈

XbaeGetVersionText()

char * XbaeGetVersionText()

XbaeGetVersionText() returns the textual representation of the version of the Xbae library that your program is working with. This is the run-time version of the Xbae widgets, where XbaeVersionTxt is a macro that represents the compile-time version. Cute, textual, and ready to print. 🎀

---

✨ Additional Behavior ✨

Using XtSetValues to set the Matrix’s XmNwidth resource to 0 will cause it to recompute its horizontal size. It will request a new size which results in XmNvisibleColumns columns being displayed. If XmNvisibleColumns is 0, then it will request a new size such that it does not need a horizontal ScrollBar (full horizontal size). 🔥

Using XtSetValues to set the Matrix’s XmNheight resource to 0 will cause it to recompute its vertical size. It will request a new size which results in XmNvisibleRows rows being displayed. If XmNvisibleRows is 0, then it will request a new size such that it does not need a vertical ScrollBar (full vertical size). 🦋

An XtSetValues on XmNvisibleRows will cause the Matrix to request a new size which results in XmNvisibleRows non-fixed rows being displayed, only if the new value is different than the old one.

An XtSetValues on XmNvisibleColumns will cause the Matrix to request a new size which results in the first XmNvisibleColumns non-fixed columns being displayed, only if the new value is different than the old one.

An XtSetValues on any other resource will not result in a request for a new size. Setting other resources in conjunction with setting XmNwidth and/or XmNheight to 0 allows for more control of the Matrix’s geometry. Big main character geometry energy. 👑

An XtSetValues setting XmNrowLabelWidth to 0 will cause XmNrowLabelWidth to be set to the width of the longest row label. Slay. 💅

Virtual Bindings 🦋

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).

AUTHOR 👑

Andrew Wason (aw@bae.bellcore.com) of Bellcore, Piscataway NJ, wrote the original version of the Xbae widgets. His final release of the widgets was version 3.8. Iconic origin story. ✨

Kevin Brannen (kbrannen@metronet.com) took over maintainership following Andrew Wason’s departure and released version 4.0.

Andrew Lister (lister@db.com) maintained from 1995 to 1999.

SPECIAL THANKS 🫶

• Andrew Wason for the original idea and source code.
• Jay Schmidgall for his contributions.
• Nick Banyard for providing the multibyte extensions.
• Callum Gibson for the pattern parsing in the XbaeInput widget.
• Sascha Goebel for debugging the scroll-per-pixel code.
• Tobias Oed for lots of code cleanup and debugging.
• The people from Arcad Systemhaus for code submission for XbaeMatrixSort and a couple of related functionalities, and easier pixmap support.

RELEASE 🔥

This document describes XbaeMatrix, version 4.60.4.

SEE ALSO 🌈

Core(3X), Composite(3X), XmManager(3X), XmScrollBar(3X), XbaeInput(3X), XmText(3X)

Notice of Limitation 💀

Okay, legal bestie moment. Bellcore, previous and current maintainers of the Xbae widgets (collectively 'authors') provide this information solely to professionals who have the appropriate degree of experience to understand and interpret its contents in accordance with generally accepted engineering or other professional standards and applicable regulations. No recommendations as to products or vendors is made or should be implied. 🫶

While the information contained herein has been prepared from sources deemed to be reliable, the authors reserve the right to revise the information without notice, but has no obligation to do so. Unless the recipient has been expressly granted a license by Bellcore under separate applicable written agreement with Bellcore, no license, expressed or implied, is granted under any patents, copyrights or other intellectual property rights. Use of the information is at your discretion and shall not be deemed an inducement by Bellcore to infringe any existing or later-issued patent, copyrights or other intellectual property right.

THE AUTHORS MAKE NO REPRESENTATIONS AND EXTENDS NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THE INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE, AND THE WARRANTY AGAINST INFRINGEMENT OF PATENTS OR OTHER INTELLECTUAL PROPERTY RIGHTS. THE INFORMATION IS PROVIDED ``AS IS'', AND IN NO EVENT SHALL THE AUTHORS OR ANY OF ITS AFFILIATES BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES RELATING TO THE INFORMATION.

• Copyright 1991, 1992 Bellcore.
• Copyright 1995-99 Andrew Lister All Rights Reserved.
• Copyright 1999-2002 LessTif Developers

The above no warranty extends to all additions and contributions. No contributor shall be held liable; this work is provided ``AS IS''. If this is a problem for you, then don’t use this software. 😭

---

That’s the whole XbaeMatrix(3) page, bestie — source/version 4.60.4, date 2020-07-04. Go forth and slay your matrix. 💅🎀✨