XMCOMMAND(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

💖 XmCommand 💖

okay so bestie, gather round — this is the manual page for XmCommand, straight out of the library call section of the manual (yes, that XmCommand(library call) header you saw at the top, that's this). It's a whole widget class and she is iconic. Let's get into it 🎀

✨ NAME ✨

XmCommand — the Command widget class. that's it, that's the name, she's that girl 💅

🌸 SYNOPSIS 🌸

#include <Xm/Command.h>

that's literally the whole vibe check. include the header and you're in 🦋

💫 DESCRIPTION 💫

okay so here's the tea: Command is a special-purpose composite widget for command entry, and she comes with a built-in command-history mechanism. no cap. she's not just a text box, she's a whole experience. ✨

Command includes, all in one gorgeous package:

  • a command-line text-input field 📝
  • a command-line prompt 💬
  • and a command-history list region 📜

One additional WorkArea child may be added to the Command after creation. just the one. she has boundaries, and honestly? respect. 💅

Whenever a command is entered, it is automatically added to the end of the command-history list and made visible. 🔥 This does not change the selected item in the list, if there is one. so if you had something highlighted, she's not gonna yank that from you, she's polite like that 🫶

Also, quick heads-up bestie: many of the new resources specified for Command are actually SelectionBox resources that have been renamed for clarity and ease of use. so if something feels familiar... it is. she just got a glow-up and a new name 😌

🌈 Descendants 🌈

Command automatically creates the descendants shown in the following list. An application can use XtNameToWidget to gain access to the named descendant. In addition, a user or an application can use the named descendant when specifying resource values. 🧚

  • ItemsList — class XmList — the command-history list region 📜
  • ItemsListSW — class XmScrolledWindow — the ScrolledWindow parent of ItemsList 🪟
  • Selection — class XmLabelGadget — the command-line prompt 💬
  • Text — class XmTextField — the command-line text-input field ✍️

👑 Classes 👑

Command inherits behavior, resources, and traits from Core, Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox. yeah, she comes from a long line of legends, main character energy runs in the family 👑

The class pointer is xmCommandWidgetClass.

The class name is XmCommand.

🌸 New Resources 🌸

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

The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).

  • XmNcommand — class XmCTextString, type XmString, default "", access CSG
  • XmNcommandChangedCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNcommandEnteredCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNhistoryItems — class XmCItems, type XmStringTable, default NULL, access CSG
  • XmNhistoryItemCount — class XmCItemCount, type int, default 0, access CSG
  • XmNhistoryMaxItems — class XmCMaxItems, type int, default 100, access CSG
  • XmNhistoryVisibleItemCount — class XmCVisibleItemCount, type int, default dynamic, access CSG
  • XmNpromptString — class XmCPromptString, type XmString, default dynamic, access CSG

now let's break each one down, bestie, because the details matter 💖

XmNcommand Contains the current command-line text. This is the XmNtextString resource in SelectionBox, renamed for Command. This resource can also be modified with XmCommandSetValue and XmCommandAppendValue functions. The command area is a Text widget. ✍️

XmNcommandChangedCallback Specifies the list of callbacks that is called after each time the value of the command changes. The callback reason is XmCR_COMMAND_CHANGED. This is equivalent to the XmNvalueChangedCallback of the Text widget, except that a pointer to an XmCommandCallbackStructure is passed, and the structure's value member contains the XmString. 🔔

XmNcommandEnteredCallback Specifies the list of callbacks that is called when a command is entered in the Command. The callback reason is XmCR_COMMAND_ENTERED. A pointer to an XmCommandCallback structure is passed. 🚀

XmNhistoryItems Lists XmString items that make up the contents of the history list. This is the XmNlistItems resource in SelectionBox, renamed for Command.

⚠️ okay important: XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. don't do it bestie, she will notice 💀

XmNhistoryItemCount Specifies the number of XmStrings in XmNhistoryItems. This is the XmNlistItemCount resource in SelectionBox, renamed for Command.

The value must not be negative. 🚫

XmNhistoryMaxItems Specifies the maximum number of items allowed in the history list. Once this number is reached, an existing list item must be removed before a new item can be added to the list. For each command entered, the first list item is removed from the list, so the new command can be added to the list.

The value must be greater than 0 (zero). 🚫

XmNhistoryVisibleItemCount Specifies the number of items in the history list that should be visible at one time. In effect, it sets the height (in lines) of the history list window. This is the XmNlistVisibleItemCount resource in SelectionBox, renamed for Command.

The value must be greater than 0 (zero). The default is dynamic, based on the height of the list. 🌊

XmNpromptString Specifies a prompt for the command line. This is the XmNselectionLabelString resource in SelectionBox, renamed for Command. The default may vary depending on the value of the XmNlayoutDirection resource and the locale. In the C locale the default is > (right angle bracket). 💬

Okay so real talk, bestie — now that some default localized label strings are being handed out through message catalogs for the children of composite widgets, you cannot set the labelString resources on the child through default resource files anymore. Nope. Not happening. 🙅‍♀️ Instead, you have to use the resource that's provided at the parent level. That's the move. That's the whole vibe. 💅

✨ Inherited Resources ✨

Command inherits behavior and resources from the superclasses listed in the tables below. For a complete description of each resource, go read the reference page for that superclass — it's giving ✨required reading✨, iykyk.

🌸 XmSelectionBox Resource Set 🌸

Every row is <pink>Name</pink> → <purple>Class</purple> → <cyan>Type</cyan> → <mint>Default</mint> → <peach>Access</peach>, in that order. No skipping, no cap. 👑

  • XmNapplyCallback — class XmCCallback, type XtCallbackList, default NULL, access N/A
  • XmNapplyLabelString — class XmCApplyLabelString, type XmString, default dynamic, access N/A
  • XmNcancelCallback — class XmCCallback, type XtCallbackList, default NULL, access N/A
  • XmNcancelLabelString — class XmCCancelLabelString, type XmString, default dynamic, access N/A
  • XmNchildPlacement — class XmCChildPlacement, type unsigned char, default XmPLACE_ABOVE_SELECTION, access CSG
  • XmNdialogType — class XmCDialogType, type unsigned char, default XmDIALOG_COMMAND, access G
  • XmNhelpLabelString — class XmCHelpLabelString, type XmString, default dynamic, access N/A
  • XmNlistItemCount — class XmCItemCount, type int, default 0, access CSG
  • XmNlistItems — class XmCItems, type XmStringTable, default NULL, access CSG
  • XmNlistLabelString — class XmCListLabelString, type XmString, default NULL, access N/A
  • XmNlistVisibleItemCount — class XmCVisibleItemCount, type int, default dynamic, access CSG
  • XmNminimizeButtons — class XmCMinimizeButtons, type Boolean, default False, access N/A
  • XmNmustMatch — class XmCMustMatch, type Boolean, default False, access N/A
  • XmNnoMatchCallback — class XmCCallback, type XtCallbackList, default NULL, access N/A
  • XmNokCallback — class XmCCallback, type XtCallbackList, default NULL, access N/A
  • XmNokLabelString — class XmCOkLabelString, type XmString, default dynamic, access N/A
  • 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 "", access CSG
🫶 Pro bestie tip: those dynamic defaults are literally just doing the most, so don't hardcode assumptions about them, okay? Read the superclass page. ✨

✨ XmBulletinBoard Resource Set ✨

okay bestie, welcome to the resource set for XmBulletinBoard 💖 this is literally the master list of every property you can set on a bulletin board widget, and it's giving very organized. the columns are Name, Class, Type, Default, and Access — no cap. here's every single one, in order, so you don't miss a thing:

  • XmNallowOverlap — Class: XmCAllowOverlap, Type: Boolean, Default: True, Access: CSG ✨
  • XmNautoUnmanage — Class: XmCAutoUnmanage, Type: Boolean, Default: False, Access: N/A 🎀
  • XmNbuttonFontList — Class: XmCButtonFontList, Type: XmFontList, Default: dynamic, Access: N/A 💅
  • XmNbuttonRenderTable — Class: XmCButtonRenderTable, Type: XmRenderTable, Default: dynamic, Access: CSG 🦋
  • XmNcancelButton — Class: XmCWidget, Type: Widget, Default: NULL, Access: N/A 🌸
  • XmNdefaultButton — Class: XmCWidget, Type: Widget, Default: NULL, Access: N/A 🌈
  • XmNdefaultPosition — Class: XmCDefaultPosition, Type: Boolean, Default: False, 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_NONE, 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 🦋

🫶 The XmManager Resource Set 🫶

okay bestie, here's the whole menu of resources that XmManager brings to the table, no cap. name, class, type, default, access — all of it, exactly as it is:

  • 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 💅

🌟 The Composite Resource Set 🌟

and then Composite rolls up with its own lil trio of resources, periodt:

  • 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 💜
  • 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 🫶

bestie a pointer to the following structure gets handed to every single callback, no exceptions:

typedef struct
{
        int reason;
        XEvent * event;
        XmString value;
        int length;
} XmCommandCallbackStruct;
  • reason — tells you why the callback got invoked, like the lore drop of the moment 💅
  • event — points to the XEvent that triggered the callback, the whole origin story fr
  • value — the XmString sitting in the CommandArea, i.e. the actual text
  • length — the size in bytes of the XmString value. and listen, this member is obsolete — it's just hanging around for compatibility with earlier releases, like a legacy fit we keep in the back of the closet 🙈

🌸 Translations 🌸

XmCommand inherits translations from XmSelectionBox. it's giving family resemblance, it's giving inherited genes 💜

⭐ Accelerators ⭐

The XmNtextAccelerators from XmSelectionBox are added to the Text descendant of XmCommand. so the Text widget down the family tree gets them too, iconic behaviour honestly

👑 Action Routines 👑

the XmCommand action routines are, drumroll please:

  • SelectionBoxUpOrDown(Previous|Next|First|Last) — the main character of this section, and here's exactly what it does:
    • When called with an argument of Previous, or 0 (zero) for compatibility, it selects the previous item in the history list and replaces the text with that item. lowkey time travel, going back a step 🕰️
    • When called with an argument of Next, or 1 for compatibility, it selects the next item in the history list and replaces the text with that item. forward momentum, slay 🔥

okay bestie, picking up right where we left off in the action list 💅

  • when you call it with an argument of First, or 2 for compatibility, it selects the first item in the history list and replaces the text with that item. periodt.
  • when you call it with an argument of Last, or 3 for compatibility, it selects the last item in the history list and replaces the text with that item. she’s consistent.
  • calls the callbacks for XmNcommandChangedCallback. not me being the messenger of callback tea ✨

Additional Behavior 🎀

the Command widget also has this extra behavior, no cap:

  • <Key><osfCancel> — if the parent of the Command is a manager, the event is passed to the parent. lowkey passing the vibe along.
  • <Key><osfActivate> in Text — calls the Text widget's XmNactivateCallback callbacks. if the text is empty, this action then returns. otherwise, if the history list has XmNhistoryMaxItems items, it removes the first item in the list. it adds the text to the history list as the last item, clears the text, and calls the XmNcommandEnteredCallback callbacks. iconic behavior fr fr.
  • <Key> in Text — when any change is made to the text edit widget, this action calls the callbacks for XmNcommandChangedCallback. it's literally always watching 👀.
  • <BtnDown>(2+) or <Key><osfActivate> in List — calls the List widget's XmNdefaultActionCallback callbacks. if the history list has XmNhistoryMaxItems items, this action removes the first item in the list. it adds the selected List item to the history list as the last item, clears the text, and calls the XmNcommandEnteredCallback callbacks. slay.
  • <FocusIn> — calls the callbacks for XmNfocusCallback. focus queen 👑.
  • <MapWindow> — when a Command that is the child of a DialogShell is mapped, this action calls the callbacks for XmNmapCallback. mapping = main character energy.
  • <UnmapWindow> — when a Command that is the child of a DialogShell is unmapped, this action calls the callbacks for XmNunmapCallback. unmapped but still valid 💅.

Virtual Bindings 🦋

the bindings for virtual keys are vendor specific. for information about bindings for virtual buttons and keys, see VirtualBindings(3). iykyk.

kisses, this was the XmCommand(library call) manual page, no date because she’s timeless 💋

📦 where this page comes from