XMFILESELECTIONBOX(3)

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

🎀 NAME 🎀

XmFileSelectionBox — The FileSelectionBox widget class 💖

(hey bestie, this one lives in the library call section of the manual, so that's the whole vibe we're working with here)

✨ SYNOPSIS ✨

#include <Xm/FileSB.h>

🦋 DESCRIPTION 🦋

Okay so picture this: FileSelectionBox is the widget that literally walks through your directories, shows you the files and subdirectories chilling inside them, and then lets you pick a file. It's giving personal assistant energy. 👑

A FileSelectionBox has five main areas:

  • A text input field for displaying and editing a directory mask used to select the files to be displayed
  • An optional text input field for displaying and editing a filter mask used to select the files to be displayed.
  • A scrollable list of filenames
  • A scrollable list of subdirectories
  • A text input field for displaying and editing a filename
  • A group of PushButtons, labeled OK, Filter, Cancel, and Help. The layout direction of the buttons depends on the XmNlayoutDirection resource.

(yes bestie, that's six bullets under a "five main areas" heading, iykyk, that's literally what the page says and we do not argue with the page 🙈)

Additional children may be added to the FileSelectionBox after creation. FileSelectionBox inherits the layout functionality provided by SelectionBox for any additional children. To remove the list of filenames, the list of subdirectories, or both from the FileSelectionBox after creation, unmanage the appropriate widgets and their labels. The list and label widgets are obtained through a call to the XmFileSelectionBoxGetChild function. To remove either the directory list or the file list, unmanage the parent of the appropriate list widget and unmanage the corresponding label.

So the tea is: you can specify resources in a resource file for the automatically created widgets and gadgets of FileSelectionBox. Here's the list of the names of these widgets (or gadgets) and the FileSelectionBox areas they're attached to:

  • FilterLabel
    • FilterText
  • Filter Text
    • TextField
  • Directory List
    • DirList
  • Directory List Label
    • Dir
  • DirL — Label
  • DirText — TextField

Now for the actual mechanics, bestie, stay with me. 🧚

The directory mask is a string specifying the base directory to be examined and a search pattern. Ordinarily, the directory list displays the subdirectories of the base directory, as well as the base directory itself and its parent directory. The file list ordinarily displays all files and/or subdirectories in the base directory that match the search pattern.

Optionally, the search pattern mask and the base directory can be displayed in two separate text fields. This option is controlled by the XmNpathMode resource. Using this alternate display does not change the meaning of resources that control the content of these fields: XmNdirectory, XmNdirMask, XmNpattern. (no cap, the meaning stays exactly the same 💅)

A procedure specified by the XmNqualifySearchDataProc resource extracts the base directory and search pattern from the directory mask. If the directory specification is empty, the current working directory is used. If the search pattern is empty, a pattern that matches all files is used.

An application can supply its own XmNqualifySearchDataProc as well as its own procedures to search for subdirectories and files. The default XmNqualifySearchDataProc works as follows: The directory mask is a pathname that can contain zero or more wildcard characters in its directory portion, its file portion, or both. The directory components of the directory mask — up to, but not including, the first component with a wildcard character — specify the directory to be searched, relative to the current working directory. The remaining components specify the search pattern. If the directory mask is empty or if its first component contains a wildcard character, the current working directory is searched. If no component of the directory mask contains a wildcard character, the entire directory mask is the directory specification, and all files in that directory are matched.

So how does a user actually drive this thing? 🚗

The user can select a new directory to examine by scrolling through the list of directories and selecting the desired directory, or by editing the directory mask. Selecting a new directory from the directory list does not change the search pattern. A user can select a new search pattern by editing the directory mask or, when the FileSelectionBox has the optional XmNpathMode XmPATH_MODE_RELATIVE display, the filter text field. Double clicking or pressing KActivate on a directory in the directory list initiates a search for files and subdirectories in the new directory, using the current search pattern.

The user can select a file by scrolling through the list of filenames and selecting the desired file, or by entering the filename directly into the text edit area. Selecting a file from the list causes that filename to appear in the file selection text edit area.

The user may select a new file as many times as desired. The application is not notified until the user takes one of the following actions:

  • Selects the OK PushButton
  • Presses KActivate while the selection text edit area has the keyboard focus
  • Double clicks or presses KActivate on an item in the file list

FileSelectionBox initiates a directory and file search when any of the following occurs:

  • The FileSelectionBox is initialized
  • The function XtSetValues is used to change XmNdirMask, XmNdirectory, XmNpattern, or XmNfileTypeMask
  • The user activates the Filter PushButton
  • The user double clicks or presses KActivate on an item in the directory list
  • The application calls XmFileSelectionDoSearch
  • The user presses KActivate while the directory mask text edit area has the keyboard focus

When a file search is initiated, the FileSelectionBox takes the following actions:

  • Constructs an XmFileSelectionBoxCallbackStruct structure with values appropriate for the action that initiated the search
  • Calls the XmNqualifySearchDataProc with the callback structure as the data input argument
  • Sets XmNdirectoryValid and XmNlistUpdated to False
  • Calls the XmNdirSearchProc with the qualified data returned by the XmNqualifySearchDataProc

If XmNdirectoryValid is True, the FileSelectionBox takes the following additional actions:

  • Sets XmNlistUpdated to False
  • Calls the XmNfileSearchProc with the qualified data returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
  • If XmNlistUpdated is True and the file list is empty, displays the XmNnoMatchString in the file list and clears the selection text and XmNdirSpec
  • If XmNlistUpdated is True and the file list is not empty, sets the selection text and XmNdirSpec to the qualified dir returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
  • Sets the directory mask text and XmNdirMask to the qualified mask returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
  • Sets XmNdirectory to the qualified dir returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
  • Sets XmNpattern to the qualified pattern returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)

FileSelectionBox uses the XmQTactivatable trait. ⭐

🫶 Data Transfer Behavior 🫶

Child widgets of a FileSelectionBox support the data transfer operations and targets associated with their widget classes.

In addition, if the source of a data transfer is the directory list and if XmNdirSearchProc has its default value, the directory list supports the FILE and FILE_NAME targets.

If the source of a data transfer is the file list and if XmNfileSearchProc has its default value, the file list supports the FILE and FILE_NAME targets.

In either case, FileSelectionBox adds an XmNconvertCallback procedure to the appropriate list. This procedure adds FILE and FILE_NAME to the TARGETS returned by the list. It treats requests for conversion of a selection to FILE and FILE_NAME exactly like requests for conversion to TEXT.

If an application changes XmNdirSearchProc or XmNfileSearchProc and wants to support the FILE and FILE_NAME targets on the corresponding list, it must provide support itself by adding a procedure to the list's XmNconvertCallback list. No free rides, bestie. 💀

part 2 is coming, don't go anywhere 🦋

✨ Descendants ✨

Okay bestie, here's the tea: FileSelectionBox just births these descendants for you automatically, no assembly required 💅. You can grab any of them by name using XtNameToWidget, and honestly you can also use that name when you're setting resource values, so keep these names handy 🎀.

Here's the whole roster, no cap:

  • Apply — Class: XmPushButtonGadget — Identity: Apply button
  • Cancel — Class: XmPushButtonGadget — Identity: Cancel button
  • Dir — Class: XmLabelGadget — Identity: title above list of directories
  • DirList — Class: XmList — Identity: list of directories
  • DirListSW — Class: XmScrolledWindow — Identity: ScrolledWindow parent of DirList
  • FilterLabel — Class: XmLabelGadget — Identity: title above filter box
  • FilterText — Class: XmText or XmTextField — Identity: text within filter box
  • Help — Class: XmPushButtonGadget — Identity: Help button
  • Items — Class: XmLabelGadget — Identity: title above list of filenames
  • ItemsList — Class: XmList — Identity: list of filenames
  • ItemsListSW — Class: XmScrolledWindow — Identity: ScrolledWindow parent of ItemsList
  • OK — Class: XmPushButtonGadget — Identity: OK button
  • Selection — Class: XmLabelGadget — Identity: title above selection box
  • Separator — Class: XmSeparatorGadget — Identity: optional dividing line
  • Text — Class: XmText or XmTextField — Identity: text within selection box
Lowkey important: those two entries that say XmText or XmTextField? That's not me being indecisive, that's literally the deal — it can be either one, and which one you get depends on stuff. Pick the name, get the widget, slay 🦋.

💖 Classes 💖

FileSelectionBox is out here inheriting behavior, resources, and traits from its whole ancestry line, and honestly the family tree is giving royalty 👑:

  • Core
  • Composite
  • Constraint
  • XmManager
  • XmBulletinBoard
  • XmSelectionBox

And for the C girlies who need the actual identifiers:

  • The class pointer is xmFileSelectionBoxWidgetClass.
  • The class name is XmFileSelectionBox.

🌸 New Resources 🌸

Alright, this next bit is where you get to be the main character and tell the widget exactly what data it should have. The table below defines a set of widget resources that us programmers use to specify data ✨.

And like, you're not limited to just the new stuff — you can also set resource values on the inherited classes to tweak attributes for this widget. Inheritance is a gift, fr fr 💜.

Now, for the .Xdefaults girlies, here's the naming hack you need:

  • To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and just use the remaining letters.
  • To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters — either lowercase or uppercase is fine, just include any underscores between words, okay? Don't skip those 🙈.
About the access column: those little codes tell you what you're allowed to do with the resource. Here's the decoder ring, memorize it iykyk 🔥: - C — can be set at creation time - S — can be set by using XtSetValues - G — can be retrieved by using XtGetValues - N/A — not applicable

Periodt. 💅

okay so before we get into the ✨lore✨ of each individual resource, here's the whole guest list — every resource name, its class, its type, its default, and who's allowed to touch it. Bookmark this, bestie, you will be scrolling back:

  • XmNdirectory — class XmCDirectory, type XmString, default dynamic, access CSG
  • XmNdirectoryValid — class XmCDirectoryValid, type Boolean, default dynamic, access SG
  • XmNdirListItems — class XmCDirListItems, type XmStringTable, default dynamic, access SG
  • XmNdirListItemCount — class XmCDirListItemCount, type int, default dynamic, access SG
  • XmNdirListLabelString — class XmCDirListLabelString, type XmString, default dynamic, access CSG
  • XmNdirMask — class XmCDirMask, type XmString, default dynamic, access CSG
  • XmNdirSearchProc — class XmCDirSearchProc, type XmSearchProc, default default procedure, access CSG
  • XmNdirSpec — class XmCDirSpec, type XmString, default dynamic, access CSG
  • XmNdirTextLabelString — class XmCDirTextLabelString, type XmString, default NULL, access C
  • XmNfileFilterStyle — class XmCFileFilterStyle, type XtEnum, default XmFILTER_NONE, access C
  • XmNfileListItems — class XmCItems, type XmStringTable, default dynamic, access SG
  • XmNfileListItemCount — class XmCItemCount, type int, default dynamic, access SG
  • XmNfileListLabelString — class XmCFileListLabelString, type XmString, default dynamic, access CSG
  • XmNfileSearchProc — class XmCFileSearchProc, type XmSearchProc, default default procedure, access CSG
  • XmNfileTypeMask — class XmCFileTypeMask, type unsigned char, default XmFILE_REGULAR, access CSG
  • XmNfilterLabelString — class XmCFilterLabelString, type XmString, default dynamic, access CSG
  • XmNlistUpdated — class XmCListUpdated, type Boolean, default dynamic, access SG
  • XmNnoMatchString — class XmCNoMatchString, type XmString, default " [ ] ", access CSG
  • XmNpathMode — class XmCPathMode, type XtEnum, default XmPATH_MODE_FULL, access C
  • XmNpattern — class XmCPattern, type XmString, default dynamic, access CSG
  • XmNqualifySearchDataProc — class XmCQualifySearchDataProc, type XmQualifyProc, default default procedure, access CSG

XmNdirectory 🎀

This is the base directory, periodt. It gets combined with XmNpattern to figure out which files and directories end up on screen. Its default isn't just sitting there — it's determined by the XmNqualifySearchDataProc, and it depends on whatever the initial values of XmNdirMask, XmNdirectory, and XmNpattern happen to be. And if that default comes out as NULL or empty? Then it just uses the current working directory. No notes. 🦋

XmNdirectoryValid

ngl this one's a little special — it's an attribute that gets set only by the directory search procedure. Nobody else touches it, fr fr. Its value is set to True if the directory that got passed to the directory search procedure can actually be searched. And if it's False? Then the file search procedure does not get called, and XmNdirMask, XmNdirectory, and XmNpattern are not changed. Like, nothing moves. Iconic behavior honestly. 💅

XmNdirListItems ✨

This specifies the items in the directory list. Big warning though, bestie, listen up: when you do XtGetValues for this resource, you get back the list items themselves — not a copy of the list items. So the application must not free the returned items. Do not. I'm serious. 😭

XmNdirListItemCount

The number of items in the directory list. That's it. That's the resource. Oh and — the value must not be negative. Be so fr. 💀

XmNdirListLabelString 🎀

The label string of the directory list. Its default depends on the locale — so it's giving "depends where you are." In the C locale, the default is Directories. Cute, consistent, no cap. 🌸

So, real talk: because default localized label strings now come through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. 😭 Instead, the resource provided at the parent level is the one you've gotta use. That's the whole vibe. Moving on bestie 💅

  • XmNdirMask — the directory mask that decides which files and directories get displayed. 🗂️ The default value is determined by XmNqualifySearchDataProc, and it depends on the initial values of XmNdirMask, XmNdirectory, and XmNpattern.
  • XmNdirSearchProc — lets you plug in a whole custom directory search procedure to replace the default one. 🔍 FileSelectionBox's default directory search procedure does what most apps need, but since it's literally impossible to cover every application's requirements, you're allowed to swap in your own.

The directory search procedure gets called with two arguments: the FileSelectionBox widget and a pointer to an XmFileSelectionBoxCallbackStruct structure. That callback structure is generated by the XmNqualifySearchDataProc and holds everything you need to run a directory search — the directory mask, plus a qualified base directory and search pattern. Once it's called, it's on the search routine to generate a new list of directories and update the FileSelectionBox widget using XtSetValues.

The search procedure must set XmNdirectoryValid and XmNlistUpdated. If it generates a new list of directories, it must also set XmNdirListItems and XmNdirListItemCount.

If the search procedure can't search the specified directory, it must warn the user and set XmNdirectoryValid and XmNlistUpdated to False — unless it prompts and subsequently obtains a valid directory. 🫣 And if the directory is valid but is the same as the current XmNdirectory, the search procedure must set XmNdirectoryValid to True, but it may elect not to generate a new list of directories. In that case, it must set XmNlistUpdated to False.

If the search procedure generates a new list of directories, it must set XmNdirListItems to the new list of directories and XmNdirListItemCount to the number of items in the list. If there are no directories, it sets XmNdirListItems to NULL and XmNdirListItemCount to 0 (zero). Either way, it must set XmNdirectoryValid and XmNlistUpdated to True.

Ordinarily the search procedure should not change the callback structure. But if the original directory isn't valid, the search procedure may grab a new directory from the user. In that case, it should set the dir member of the callback structure to the new directory, call the XmNqualifySearchDataProc with the callback struct as the input argument, and copy the qualified data returned by the XmNqualifySearchDataProc into the callback struct. 🎀

  • XmNdirSpec — the full file path specification. 📁 This is the XmNtextString resource in SelectionBox, renamed for FileSelectionBox. The default value is determined by the FileSelectionBox after it conducts the initial directory and file search.
  • XmNdirTextLabelString — uses the specified XmString as the label above the TextField directory. ✨ This resource only takes effect when the XmNpathMode resource has a value of XmPATH_MODE_RELATIVE. It gets ignored when XmNpathMode has a value of XmPATH_MODE_FULL.

And again, because default localized label strings now come through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files — the resource provided at the parent level is the one to use.

  • XmNfileFilterStyle — decides whether or not the "hidden" files (the ones whose names begin with . (period) on POSIX systems) get listed in the file and directory scrolling lists — that's where the default directory search procedure is used. 👀 The possible values are:
    • XmFILTER_NONE — does not filter hidden files.
    • XmFILTER_HIDDEN_FILES — restricts the list of possible file names, such as those beginning with . (period).
  • XmNfileListItems — the items in the file list. 📋 This is the XmNlistItems resource in SelectionBox, renamed for FileSelectionBox. Heads up: XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. 🚫
  • XmNfileListItemCount — the number of items in the file list. 🔢 This is the XmNlistItemCount resource in SelectionBox, renamed for FileSelectionBox. The value must not be negative.
  • XmNfileListLabelString — the label string of the file list. 🏷️ This is the XmNlistLabelString resource in SelectionBox, renamed for FileSelectionBox. The default for this resource depends on the locale — in the C locale the default is Files.

And yep, because default localized label strings now come through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Use the resource provided at the parent level instead. 💖

  • XmNfileSearchProc — lets you swap in your own file search procedure to replace the default one. 🔎 FileSelectionBox's default file search procedure fulfills the needs of most applications, but since it's impossible to cover the requirements of all applications, you can replace the default search procedure.

The file search procedure is called with two arguments: the FileSelectionBox widget and a pointer to an XmFileSelectionBoxCallbackStruct structure. That callback structure is generated by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc). It contains all information required to conduct a file search, including the directory mask and a qualified base directory and search pattern. Once this procedure is called, it is up to the search routine to generate a new list of files and update the FileSelectionBox widget by using XtSetValues.

The search procedure must set XmNlistUpdated. If it generates a new list of files, it must also set XmNfileListItems and XmNfileListItemCount.

It is recommended that the search procedure always generate a new list of files. If the mask member of the callback structure is the same as the mask member of the callback struct in the preceding call to the search procedure, the procedure may elect not to generate a new list of files. In this case it must set XmNlistUpdated to False.

If the search procedure generates a new list of files, it must set XmNfileListItems to the new list of files and XmNfileListItemCount to the number of items in the list. If there are no files, it sets XmNfileListItems to NULL and XmNfileListItemCount to 0 (zero). In either case it must set XmNlistUpdated to True.

When constructing the list of files, the search procedure should include only files of the types specified by the widget's XmNfileTypeMask. 🌈

Setting XmNdirSpec is optional, but recommended. Set this attribute to the full file specification of the directory searched. The directory specification is displayed below the directory and file lists.

  • XmNfileTypeMask — the type of files listed in the file list. 🗃️ The possible values are:
    • XmFILE_REGULAR — restricts the file list to contain only regular files.
    • XmFILE_DIRECTORY — restricts the file list to contain only directories.
    • XmFILE_ANY_TYPE — allows the list to contain all file types including directories.
  • XmNfilterLabelString — the label string for the text entry field for the directory mask. 🎯 The default for this resource depends on the locale — in the C locale the default is Filter.

And, as always: because default localized label strings now come through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Use the resource provided at the parent level. 🫶

  • XmNlistUpdated — an attribute that is set only by the directory and file search procedures. 👑 This resource is set to True if the search procedure updated the directory or file list.
  • XmNnoMatchString — a string to be displayed in the file list if the list of files is empty. 😭
  • XmNpattern — the search pattern used in combination with XmNdirectory to determine the files and directories to be displayed. 🦋 The default value is determined by XmNqualifySearchDataProc and depends on the initial values of XmNdirMask, XmNdirectory, and XmNpattern. If the default is NULL or empty, a pattern that matches all files is used.
  • XmNpathMode — whether or not an additional text field will be used to display and edit the filter. 🪄 The possible values are:
    • XmPATH_MODE_FULL — specifies that no additional text field will be used to display the filter. There will just be a single text field to display XmNdirMask.
  • XmPATH_MODE_RELATIVE — okay so this one gives you two text fields bestie, not one: one of them displays the XmNdirectory and the other one displays the XmNpattern. And in this mode, XmNfilterLabelString is the label for the text field holding XmNpattern, while XmNdirTextLabelString is the label for the text field holding XmNdirectory. Two fields, two labels, no confusion 💅
  • XmNqualifySearchDataProc — this one lets you swap in your own search data qualification procedure and boot the default one out. The default data qualification procedure that FileSelectionBox ships with does the job for most applications, fr fr. But since it's literally impossible to cover what every application out there needs, you're allowed to replace the default procedure. Slay.

So what does this procedure actually do? It gets called to generate a qualified directory mask, base directory, and search pattern, all for the directory and file search procedures to use. It's called with three arguments: the FileSelectionBox widget, plus pointers to two XmFileSelectionBoxCallbackStruct structures. The first callback structure carries the input data. The second one carries the output data, and it's your procedure's job to fill it in.

Here's the rundown, no cap:

  • If the input dir and pattern members are not NULL, the procedure must copy them to the corresponding members of the output callback structure.
  • If the input dir is NULL, the procedure builds the output dir like this: if the input mask member is NULL, it uses the widget's XmNdirectory as the output dir; otherwise it extracts the output dir from the input mask. And if the resulting output dir ends up empty, it uses the current working directory instead. 🫶
  • If the input pattern is NULL, the procedure builds the output pattern like this: if the input mask member is NULL, it uses the widget's XmNpattern as the output pattern; otherwise it extracts the output pattern from the input mask. And if the resulting output pattern is empty, it uses a pattern that matches all files instead.
  • The data qualification procedure constructs the output mask from the output dir and pattern. And it must make sure that the output dir, pattern, and mask are all fully qualified.
  • If the input value member is not NULL, the procedure must copy it to the output value member; otherwise, the procedure must copy the widget's XmNdirSpec to the output value.
  • The data qualification procedure must calculate the lengths of the output value, mask, dir, and pattern members, and it must fill in the corresponding length members of the output callback struct.
  • The data qualification procedure must copy the input reason and event members to the corresponding output members.
like, yes, there are a lot of "must"s in there. That's not me being dramatic, that's literally the contract. Skip one and things get weird 💀

The values of the XmNdirSearchProc and XmNfileSearchProc are procedure pointers of type XmSearchProc, and it's defined like this:

void (* XmSearchProc) (w, search_data)
        Widget w;
        XtPointer search_data;
  • w — the FileSelectionBox widget 🌸
  • search_data — a pointer to an XmFileSelectionBoxCallbackStruct that's holding the info for conducting a search

And the value of the XmNqualifySearchDataProc resource is a procedure pointer of type XmQualifyProc, defined like this:

void (* XmQualifyProc) (w, input_data, output_data)
        Widget w;
        XtPointer input_data;
        XtPointer output_data;
  • w — the FileSelectionBox widget ✨
  • input_data — a pointer to an XmFileSelectionBoxCallbackStruct holding the input data that needs to be qualified
  • output_data — a pointer to an XmFileSelectionBoxCallbackStruct holding the output data, which the qualification procedure is responsible for filling in

🦋 Inherited Resources 🦋

FileSelectionBox inherits behavior and resources from the superclasses described in the following tables. For a complete description of each resource, go check the reference page for that superclass, bestie — that's where the full tea lives. 💖

🎀 XmSelectionBox Resource Set 🎀

okay bestie, here's the full resource table for XmSelectionBox — every name, class, type, default, and access code, laid out so you can actually read it. no cap, it's a lot, but we're doing it together 💖

  • XmNapplyCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNapplyLabelString — class XmCApplyLabelString, type XmString, default dynamic, access CSG
  • XmNcancelCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNcancelLabelString — class XmCCancelLabelString, type XmString, default dynamic, access CSG
  • XmNchildPlacement — class XmCChildPlacement, type unsigned char, default XmPLACE_ABOVE_SELECTION, access CSG
  • XmNdialogType — class XmCDialogType, type unsigned char, default XmDIALOG_FILE_SELECTION, access G
  • XmNhelpLabelString — class XmCHelpLabelString, type XmString, default dynamic, access CSG
  • XmNlistItemCount — class XmCItemCount, type int, default dynamic, access CSG
  • XmNlistItems — class XmCItems, type XmStringTable, default dynamic, access CSG
  • XmNlistLabelString — class XmCListLabelString, type XmString, default dynamic, access CSG
  • XmNlistVisibleItemCount — class XmCVisibleItemCount, type int, default dynamic, access CSG
  • XmNminimizeButtons — class XmCMinimizeButtons, type Boolean, default False, access CSG
  • XmNmustMatch — class XmCMustMatch, type Boolean, default False, access CSG
  • XmNnoMatchCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNokCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNokLabelString — class XmCOkLabelString, type XmString, default dynamic, access CSG
  • XmNselectionLabelString — class XmCSelectionLabelString, type XmString, default dynamic, access CSG
  • XmNtextAccelerators — class XmCTextAccelerators, type XtAccelerators, default default, access C
  • XmNtextColumns — class XmCColumns, type short, default dynamic, access CSG
  • XmNtextString — class XmCTextString, type XmString, default dynamic, access CSG

like… twenty resources, all accounted for, nothing skipped 💅 the dynamic defaults are lowkey doing the most (they get computed at runtime, not set in stone), and those access codes are your vibe check on when you can touch each one. keep scrolling bestie, there's more coming 🌸🦋

🎀 XmBulletinBoard Resource Set 🎀

okay bestie, this is the full roster of resources the XmBulletinBoard is serving. every single one, no skips, no cuts — name, class, type, default, and access, all of it 💅

  • XmNallowOverlap — class XmCAllowOverlap, type Boolean, default True, access CSG
  • XmNautoUnmanage — class XmCAutoUnmanage, type Boolean, default False, access CG
  • XmNbuttonFontList — class XmCButtonFontList, type XmFontList, default dynamic, access CSG
  • XmNbuttonRenderTable — class XmCButtonRenderTable, type XmRenderTable, default dynamic, access CSG
  • XmNcancelButton — class XmCWidget, type Widget, default Cancel button, access SG
  • XmNdefaultButton — class XmCWidget, type Widget, default OK button, access SG
  • XmNdefaultPosition — class XmCDefaultPosition, type Boolean, default True, access CSG
  • XmNdialogStyle — class XmCDialogStyle, type unsigned char, default dynamic, access CSG
  • XmNdialogTitle — class XmCDialogTitle, type XmString, default NULL, access CSG
  • XmNfocusCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNlabelFontList — class XmCLabelFontList, type XmFontList, default dynamic, access CSG
  • XmNlabelRenderTable — class XmCLabelRenderTable, type XmRenderTable, default dynamic, access CSG
  • XmNmapCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNmarginHeight — class XmCMarginHeight, type Dimension, default 10, access CSG
  • XmNmarginWidth — class XmCMarginWidth, type Dimension, default 10, access CSG
  • XmNnoResize — class XmCNoResize, type Boolean, default False, access CSG
  • XmNresizePolicy — class XmCResizePolicy, type unsigned char, default XmRESIZE_ANY, access CSG
  • XmNshadowType — class XmCShadowType, type unsigned char, default XmSHADOW_OUT, access CSG
  • XmNtextFontList — class XmCTextFontList, type XmFontList, default dynamic, access CSG
  • XmNtextRenderTable — class XmCTextRenderTable, type XmRenderTable, default dynamic, access CSG
  • XmNtextTranslations — class XmCTranslations, type XtTranslations, default NULL, access C
  • XmNunmapCallback — class XmCCallback, type XtCallbackList, default NULL, access C

like, that's the whole lineup ✨ and yeah, some of these defaults are literally the word dynamic, that's not me being vague, that's just what the page says fr fr 🦋

💖 XmManager Resource Set 💖

okay bestie, this is the big one — everything your widget inherits from XmManager. Same four-column tea as always (Name / Class / Type / Default / Access), just laid out as bullets so it actually fits on your screen. 💅

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG
  • XmNinitialFocus — class XmCInitialFocus, type Widget, default dynamic, access CSG
  • XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG
  • XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default dynamic, access CSG
  • XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG
  • XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG
  • XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG
ngl the way so many of these say dynamic instead of a real default? that's on purpose, bestie — the toolkit figures it out from the widget's context. don't come for me, come for the source. 🫶

🦋 Composite Resource Set 🦋

and here's the lil baby set that comes with Composite — only three rows, she's lowkey iconic for it. ✨

  • XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G
  • XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG
  • XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G
notice XmNchildren and XmNnumChildren are access G only — read-only, bestie. look with your eyes, not with your XtSetArg. 💀

the table format was giving ✨ spreadsheet energy ✨ so I flipped it into bullets, but every single Name, Class, Type, Default and Access value is still there, character for character. no cap. 🎀

more coming, keep scrolling 🧚

okay bestie, here comes the receipts table 📋 — every single resource this widget inherits, with its class, type, default, and who's allowed to touch it (that Access column is C = create-only, G = get, S = set, so CSG means all three, no cap).

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

💌 Callback Information 💌

so when the callback fires, this is the lil envelope of info it hands you 🎀 — a pointer to the structure below gets passed to each callback:

typedef struct
{
        int reason;
        XEvent * event;
        XmString value;
        int length;
        XmString mask;
        int mask_length;
        XmString dir;
        int dir_length;
        XmString pattern;
        int pattern_length;
} XmFileSelectionBoxCallbackStruct;

let's break down every field, one by one, no skipping ✨

  • reason — tells you why the callback got invoked, like the receipts for what just happened 👀
  • event — points at the XEvent that triggered the callback, the actual moment that set it off 🫶
  • value — the current value of XmNdirSpec, fr fr
  • length — the number of bytes in value. Heads up bestie: this member is obsolete and only hangs around for compatibility with earlier releases 💀
  • mask — the current value of XmNdirMask
  • mask_length — the number of bytes in mask. Yeah this one's obsolete too, kept for compatibility with earlier releases 🙈
  • dir — the current base directory
  • dir_length — the number of bytes in dir. Also obsolete, also just there for compatibility with earlier releases 😭
  • pattern — the current search pattern

pattern_length

okay so pattern_length is the number of bytes in pattern. BUT — and this is important, bestie — this member is obsolete and only still exists for compatibility with earlier releases. she's a legacy icon, we love her, we do not build new things on her 💅

✨ Translations ✨

XmFileSelectionBox inherits translations from XmSelectionBox. that's the whole tea — she's just borrowing her big sister's choreography 🎀

✨ Accelerators ✨

The XmNtextAccelerators from XmSelectionBox get added to the selection and directory mask (filter) Text descendants of XmFileSelectionBox. so the text widgets lowkey get the same shortcuts as the selection box ones ✨

✨ Action Routines ✨

The XmFileSelectionBox action routines are iconic, all of them:

  • SelectionBoxUpOrDown(Previous|Next|First|Last) — the up/down navigation queen 👑
    • If neither the selection text nor the directory mask (filter) text has the focus, this action does nothing. vibe check failed, no notes, we move on 💀
    • If the selection text has the focus, the term list in the description below means the file list, and the term text means the selection text. If the directory mask text has the focus, list means the directory list, and text means the directory mask text.
    • When called with an argument of Previous, or 0 (zero) for compatibility, this action selects the previous item in the list and replaces the text with that item.
    • When called with an argument of Next, or 1 for compatibility, this action selects the next item in the list and replaces the text with that item.
    • When called with an argument of First, or 2 for compatibility, this action selects the first item in the list and replaces the text with that item.
    • When called with an argument of Last, or 3 for compatibility, this action selects the last item in the list and replaces the text with that item.
  • SelectionBoxRestore() — the "undo my mess" button 🫶
    • If neither the selection text nor the directory mask (filter) text has the focus, this action does nothing. again. nothing. she said what she said 😭
    • If the selection text has the focus, this action replaces the selection text with the selected item in the file list. If no item in the file list is selected, it clears the selection text.
    • If the directory mask text has the focus, this action replaces the directory mask text with a new directory mask constructed from the XmNdirectory and XmNpattern resources.

✨ Additional Behavior ✨

The FileSelectionBox widget has the following additional behavior (this is the good part, get comfy bestie 🍓):

  • <Key><osfCancel> — Calls the activate callbacks for the cancel button if it is sensitive. If no cancel button exists and the parent of the FileSelectionBox is a manager, it passes the event to the parent. she's like "not my problem, take it upstairs" 💅
  • <Key><osfActivate> in Selection Text — Calls the selection text widget's XmNactivateCallback callbacks. If XmNmustMatch is True and the selection text does not match an item in the file list, it calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, it calls the XmNokCallback callbacks with reason XmCR_OK.
  • <Key><osfActivate> in Directory Mask Text — Calls the directory mask text widget's XmNactivateCallback callbacks, initiates a directory and file search, and calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
  • <Btn1Down>(2+) or <Key><osfActivate> in Directory List — Calls the directory list widget's XmNdefaultActionCallback callbacks, initiates a directory and file search, and calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
  • <Btn1Down>(2+) or <Key><osfActivate> in File List — Calls the file list widget's XmNdefaultActionCallback callbacks and calls the XmNokCallback callbacks with reason XmCR_OK.
  • <Key><osfSelect> in Directory List — Generates a new directory mask, using the selected list item as the directory and the pattern extracted from the current directory mask text as the search pattern. If the search pattern is empty, it uses a pattern that matches all files in the directory. Replaces the directory mask text with the new directory mask. she built a whole new mask from scratch, no cap ✨
  • <Key><osfSelect> in File List — Replaces the selection text with the selected list item. simple. clean. slay.
  • <Btn2Down> in File List — Drags the content of one or more selected list items using the drag and drop facility. If <Btn2Down is pressed on an unselected item, drags only that item, excluding any other selected items.
    • This action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures of the file list, possibly multiple times, for the _MOTIF_DROP selection.
  • <Btn2Down> in Directory List — Drags the content of one or more selected list items using the drag and drop facility. If <Btn2Down is pressed on an unselected item, it drags only that item, excluding any other selected items.
    • This action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures of the directory list, possibly multiple times, for the _MOTIF_DROP selection.
  • <Apply Button Activated> — Initiates a directory and file search. Calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
  • <OK Button Activated> — If XmNmustMatch is True and the selection text does not match an item in the file list, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK. main character energy fr fr 👑
  • <Cancel Button Activated> — Calls the XmNcancelCallback callbacks with reason XmCR_CANCEL.
  • <Help Button Activated> — Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
  • <Key><osfActivate> — If no button, list widget, or text widget has the keyboard focus, if XmNmustMatch is True and the selection text does not match an item in the file list, it calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, it calls the XmNokCallback callbacks with reason XmCR_OK.
heads up bestie: that <Btn2Down up there is missing its closing > in the original — I'm keeping it exactly as written because we do not edit the source, we respect the source 💅

✨ Virtual Bindings ✨

The bindings for virtual keys are vendor specific. everyone's got their own little rules, iykyk 🦋 For info about bindings for virtual buttons and keys, go read VirtualBindings(3).

the whole friend group, in no particular order:

and that's a wrap on the whole page, bestie!! you read every single resource, every action routine, every binding, and you ATE 💅✨ the footer tags this one as XmFileSelectionBox(library call) — no date on it, she's timeless, she's eternal, she's a library call 🎀 go forth and file-select responsibly, ily 🫶💖

📦 where this page comes from