XMMESSAGEBOX(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 💖

XmMessageBox — The MessageBox widget class. This is the XmMessageBox(library call) page, bestie, and we're about to get into it. ✨

✨ SYNOPSIS ✨

#include <Xm/MessageB.h>

🌸 DESCRIPTION 🌸

Okay so MessageBox is a dialog class, and its whole vibe is creating simple message dialogs. There are convenience dialogs built on top of MessageBox for several common interaction tasks, which include giving information, asking questions, and reporting errors. 💅

A MessageBox dialog is typically transient in nature — displayed for the duration of a single interaction. MessageBox is a subclass of BulletinBoard and depends on it for much of its general dialog behavior. 🦋

The default value for XmNinitialFocus is the value of XmNdefaultButton.

A typical MessageBox contains a message symbol, a message, and up to three standard default PushButtons: OK, Cancel, and Help. It is laid out with the symbol and message on top and the PushButtons on the bottom. The Help button is positioned to the side of the other push buttons. You can localize the default symbols and button labels for MessageBox convenience dialogs. 👑

The user can specify resources in a resource file for the gadgets created automatically that contain the MessageBox symbol pixmap and separator. The gadget names are Symbol and Separator.

A MessageBox can also be customized by creating and managing new children that are added to the MessageBox children created automatically by the convenience dialogs. In the case of TemplateDialog, only the separator child is created by default. If the callback, string, or pixmap symbol resources are specified, the appropriate child will be created. 🫶

Additional children are laid out in the following manner:

  • The first MenuBar child is placed at the top of the window. The XmQTmenuSystem trait is used to check that it is the first MenuBar child.
  • All widgets or gadgets are placed after the OK button in the order of their creation (this order is checked using the XmQTactivatable trait).
  • A child that is not in the above categories is placed above the row of buttons. If a message label exists, the child is placed below the label. If a message pixmap exists, but a message label is absent, the child is placed on the same row as the pixmap. The child behaves as a work area and grows or shrinks to fill the space above the row of buttons. The layout of multiple work area children is undefined. 😭

At initialization, MessageBox looks for the following bitmap files:

  • xm_error
  • xm_information
  • xm_question
  • xm_working
  • xm_warning

See XmGetPixmap(3) for a list of the paths that are searched for these files. 🔥

MessageBox uses the XmQTactivatable and XmQTmenuSystem traits.

🦋 Descendants 🦋

MessageBox automatically creates the descendants shown in the following table. 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. ✨

  • Named Descendant: Cancel — Class: XmPushButtonGadget — Identity: Cancel button
  • Named Descendant: Help — Class: XmPushButtonGadget — Identity: Help button
  • Named Descendant: Message — Class: XmLabelGadget — Identity: displayed message
  • Named Descendant: OK — Class: XmPushButtonGadget — Identity: OK button
  • Named Descendant: Separator — Class: XmSeparatorGadget — Identity: dividing line between message and buttons
  • Named Descendant: Symbol — Class: XmLabelGadget — Identity: icon symbolizing message type

👑 Classes 👑

MessageBox inherits behavior, resources, and traits from Core, Composite, Constraint, XmManager, and XmBulletinBoard. 💜

The class pointer is xmMessageBoxWidgetClass.

The class name is XmMessageBox.

🎀 New Resources 🎀

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 💖

✨ XmMessageBox Resource Set ✨

okay bestie, here's the whole roster of resources this widget brings to the party 🎀 every single one, with its class, type, default, and access level, because we do NOT skip rows in this house 💅

  • XmNcancelCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNcancelLabelString — class XmCCancelLabelString, type XmString, default dynamic, access CSG
  • XmNdefaultButtonType — class XmCDefaultButtonType, type unsigned char, default XmDIALOG_OK_BUTTON, access CSG
  • XmNdialogType — class XmCDialogType, type unsigned char, default XmDIALOG_MESSAGE, access CSG
  • XmNhelpLabelString — class XmCHelpLabelString, type XmString, default dynamic, access CSG
  • XmNmessageAlignment — class XmCAlignment, type unsigned char, default XmALIGNMENT_BEGINNING, access CSG
  • XmNmessageString — class XmCMessageString, type XmString, default "", access CSG
  • XmNminimizeButtons — class XmCMinimizeButtons, type Boolean, default False, access CSG
  • XmNokCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNokLabelString — class XmCOkLabelString, type XmString, default dynamic, access CSG
  • XmNsymbolPixmap — class XmCPixmap, type Pixmap, default dynamic, access CSG

💖 XmNcancelCallback

tells the widget which list of callbacks to fire when somebody clicks the cancel button 🫶 the reason that gets sent along with the callback is XmCR_CANCEL.

🌸 XmNcancelLabelString

this one is the string label sitting pretty on the cancel button ✨ and here's the thing — the default for it depends on the locale you're in. in the C locale, the default is Cancel.

now that some default localized label strings are handed out 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 gotta use. iykyk.

👑 XmNdefaultButtonType

picks which PushButton gets to be the default one 💅 if you hand it a value of XmDIALOG_NONE, that means there should be no default PushButton at all, periodt. these are the valid types:

  • XmDIALOG_CANCEL_BUTTON
  • XmDIALOG_OK_BUTTON
  • XmDIALOG_HELP_BUTTON
  • XmDIALOG_NONE

🦋 XmNdialogType

sets the type of MessageBox dialog, which is what decides the default message symbol 🎀 these are the possible values for this resource:

  • XmDIALOG_ERROR — indicates an ErrorDialog.
  • XmDIALOG_INFORMATION — indicates an InformationDialog.
  • XmDIALOG_MESSAGE — indicates a MessageDialog. this is the default MessageBox dialog type, and it does not have an associated message symbol.
  • XmDIALOG_QUESTION — indicates a QuestionDialog.
  • XmDIALOG_TEMPLATE — indicates a TemplateDialog. the TemplateDialog contains only a separator child. it does not have an associated message symbol.
  • XmDIALOG_WARNING — indicates a WarningDialog.
  • XmDIALOG_WORKING — indicates a WorkingDialog.
heads up bestie: if this resource gets changed with XtSetValues, the symbol bitmap gets modified to the new XmNdialogType bitmap — unless XmNsymbolPixmap is also being set in that same call to XtSetValues. and if the dialog type doesn't have an associated message symbol, then no bitmap will be displayed at all 🙈

🧚 XmNhelpLabelString

the string label for the help button, obviously 💜 and yeah, the default for this resource depends on the locale. in the C locale the default is Help.

same saga as before, bestie: now that some default localized label strings are provided 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 must be used. iconic behavior tbh.

🌈 XmNmessageAlignment

controls the alignment of the message Label 📐 possible values include:

  • XmALIGNMENT_BEGINNING (the default)
  • XmALIGNMENT_CENTER
  • XmALIGNMENT_END

for the full explanation of what these values even mean, go look at the description of XmNalignment in the XmLabel reference page 👑

🍓 XmNmessageString

specifies the string to be used as the message. that's it, that's the resource 💖

💅 XmNminimizeButtons

if this is False, it sets the buttons to the width of the widest button and the height of the tallest button. if this resource is True, then button width and height are set to the preferred size of each button. little buttons, individual vibes ✨

🎀 XmNokCallback

specifies the list of callbacks that gets called when the user clicks on the OK button 🫶 the reason sent by the callback is XmCR_OK.

⭐ XmNokLabelString

the string label for the OK button 💜 the default depends on the locale, and in the C locale the default is OK.

and yes, bestie, it's the same message-catalog situation again: now that some default localized label strings are provided 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 must be used. no cap.

🔥 XmNsymbolPixmap

specifies the pixmap label to be used as the message symbol 🌟

💜 Inherited Resources

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

🌸 XmBulletinBoard Resource Set 🌸

okay bestie, this is the big one — the whole XmBulletinBoard resource roster. 🫶 These are the inherited ones, and they show up here with the same five columns the table had: Name, Class, Type, Default, and Access. I'm keeping every single one exactly as-is, no cap. 💅

  • XmNallowOverlap — class XmCAllowOverlap, type Boolean, default True, access CSG
  • XmNautoUnmanage — class XmCAutoUnmanage, type Boolean, default True, 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 dynamic, 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
that's all 22 of them, fr fr — literally nothing dropped, nothing merged, every class and default copied character for character 💖

and yeah, notice how many of these are dynamic for the default — that's a whole thing and it comes up again later, so hold that thought bestie 🦋

✨ XmManager Resource Set ✨

okay bestie, here's the whole resource set this widget inherits from XmManager — every name, class, type, default and access mode, no skips 💖

  • 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

✨ Composite Resource Set ✨

and these are the ones it gets from Composite — tiny little set, but they matter 🫶

  • 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

✨ Core Resource Set ✨

bestie. sit down. hydrate. we're doing the whole resource table and I am not skipping a single line of it 💖 Every resource name, its class, its type, its default and its access code are all right here — copy them exactly, because X is that picky.

  • 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

Every callback you register gets handed a pointer to this lil struct, and it's giving "small but mighty":

typedef struct
{
        int reason;
        XEvent *event;
} XmAnyCallbackStruct;
  • reason — the whole reason the callback got summoned in the first place. it literally tells you why you're here 🫶
  • event — points at the XEvent that triggered the callback. the receipts, basically.

🌸 Translations

XmMessageBox includes the translations from XmManager. that's it, that's the whole tea. inherited, no cap.

🔥 Additional Behavior

The XmMessageBox widget has some extra moves up its sleeve, and honestly? iconic behavior only:

  • <Key><osfCancel> — calls the activate callbacks for the cancel button, but only if it's sensitive.
  • <Key><osfActivate> — calls the activate callbacks for whichever button has the keyboard focus. And if no button has the keyboard focus? it calls the activate callbacks for the default button instead, again only if it's sensitive.
  • <Ok Button Activated> — calls the callbacks for XmNokCallback.
  • <Cancel Button Activated> — calls the callbacks for XmNcancelCallback.
  • <Help Button Activated> — calls the callbacks for XmNhelpCallback.
  • <FocusIn> — calls the callbacks for XmNfocusCallback.
  • <Map> — calls the callbacks for XmNmapCallback if the parent is a DialogShell.
  • <Unmap> — calls the callbacks for XmNunmapCallback if the parent is a DialogShell.
heads up bestie: those last two are conditional. parent's gotta be a DialogShell or the callbacks are simply not happening 💅

🦋 Virtual Bindings 🦋

Okay bestie, listen up, this part is important: the bindings for virtual keys are vendor specific. Like, every vendor does their own lil thing, no universal answer, no cap. 💅

So if you wanna know the tea about the bindings for virtual buttons and keys, go check out VirtualBindings(3) — she has the whole scoop. 🫶

Runway walk, here's the whole friend group, all of them icons: 🌈

And that's the whole page, bestie!! You made it all the way to the end, main character energy fr fr. 👑 This was XmMessageBox(library call) — a library call page, so it's giving "programmer's reference, but make it cute." Go forth and build those message boxes, you absolute legend. 🎀✨

Mwah, thanks for reading, ily, bye!! 💖🦋🌸

📦 where this page comes from