XMBULLETINBOARD(3)

XmBulletinBoard — The BulletinBoard widget class 💖

okay bestie, this is the library call page for XmBulletinBoard, and ngl it's kind of the blueprint for like… every dialog you've ever clicked on. let's go. 🎀

---

✨ SYNOPSIS ✨

#include <Xm/BulletinB.h>

---

💅 DESCRIPTION 💅

so BulletinBoard is a composite widget — meaning it's a parent, it has kids — and what it does is provide simple geometry management for those child widgets. it is not a control freak tho: it does not force positioning on its children. but! you can set it to reject geometry requests that result in overlapping children. your call, bestie. 💅

BulletinBoard is the base widget for most dialog widgets, and it's also used as a general container widget. so it's giving both main character and supportive-bestie energy. 🫶

now. modal and modeless dialogs? those are implemented as collections of widgets that include:

• a DialogShell
• a BulletinBoard (or a subclass of it) that's a child of the shell
• and various dialog components (buttons, labels, and so on) that are children of the BulletinBoard

BulletinBoard defines callbacks that are useful for dialogs — focus, map, unmap — and those are available for application use. no gatekeeping here. ✨

and here's a lil detail that lowkey matters: if its parent is a DialogShell, BulletinBoard passes title and input mode (based on dialog style) information up to the parent, and the parent is the one responsible for appropriate communication with the window manager. so BulletinBoard handles the vibes, DialogShell talks to the WM. iykyk. 🧚

the default value for XmNinitialFocus is the value of XmNdefaultButton. cute, right? 💖

BulletinBoard uses the XmQTtakesDefault trait, and it holds the XmQTdialogShellSavvy and XmQTspecifyRenderTable traits. 👑

---

🦋 Classes 🦋

BulletinBoard inherits behavior, resources, and traits from the Core, Composite, Constraint, and XmManager classes.

• the class pointer is xmBulletinBoardWidgetClass
• the class name is XmBulletinBoard

---

🌸 New Resources 🌸

so here's the tea: what follows is a set of widget resources that you the programmer use to specify data. you can also set the resource values for the inherited classes, if you wanna set attributes for this widget that way. ✨

pro tip for your .Xdefaults era: 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. and 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, doesn't matter, but include any underscores between words. ⭐

and about that access column? here's the decoder ring:

• 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

XmBulletinBoard Resource Set 🌈

here's every single one, zero skips, zero cuts. 💖

• 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 NULL, access SG
• XmNdefaultButton — class XmCWidget, type Widget, default NULL, 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

and bestie, that's only the resource table — we are so not done, there's more coming. 🔥

🎀 XmNallowOverlap

Okay so this one is the vibes police for overlapping children. If this resource is True, BulletinBoard is like "sure bestie, go off" and allows geometry requests that result in overlapping children. That's it. That's the whole personality.

✨ XmNautoUnmanage

The "does this dialog close itself after you click something" resource, and honestly it's giving main-character-exits-the-room energy.

• If this resource is True on initialization and the BulletinBoard's parent is a DialogShell, then BulletinBoard adds a callback to its button children (PushButtons, PushButtonGadgets, and DrawnButtons) that unmanages the BulletinBoard when a button is activated. Boom, poof, gone. 💨
• If this resource is False on initialization, or if the BulletinBoard's parent is not a DialogShell, the BulletinBoard is not automatically unmanaged.
• Little caveat for the subclasses out there: for BulletinBoard subclasses with Apply or Help buttons, activating those buttons does not automatically unmanage the BulletinBoard. Those buttons are built different, iykyk.

🦋 XmNbuttonFontList

Specifies the font list used for button descendants. Go peek at the XmNbuttonRenderTable resource for the whole story, bestie.

🌸 XmNbuttonRenderTable

Specifies the render table used for BulletinBoard's button descendants. Here's the lil scavenger hunt that happens if this value is NULL at initialization:

1. The parent hierarchy of the widget gets searched for an ancestor that holds the XmQTspecifyRenderTable trait.
2. If such an ancestor is found, the render table is initialized to the XmBUTTON_RENDER_TABLE value of that ancestor widget.
3. If no such ancestor is found, the default is implementation dependent.

Refer to XmRenderTable(3) for more info on creating and structuring a render table. 👑

💜 XmNcancelButton

Specifies the widget ID of the Cancel button. BulletinBoard's subclasses that define a Cancel button are the ones who set this resource. And here's the tea: BulletinBoard does not directly provide any behavior for that button. It's just holding the ID, not doing the work. Not me expecting the base class to do everything 😭

🔥 XmNdefaultButton

Specifies the widget ID of the default button. Some BulletinBoard subclasses that define a default button set this resource.

BulletinBoard itself does the cool part: it defines translations and installs accelerators that activate that button when KActivate is pressed and the keyboard focus is not in another button. So like, hit the key, get the button. Periodt.

🌈 XmNdefaultPosition

Controls the positioning of a DialogShell managing a BulletinBoard. Lowkey important context: if the BulletinBoard is not being managed by a DialogShell, this resource has no effect. Nothing. Nada.

• If XmNdefaultPosition is True, the DialogShell will center itself at the center of its own parent. For example, if the parent of the DialogShell is an ApplicationShell, then the center of the DialogShell will be at the same coordinates as the center of the ApplicationShell. Math girlies rise 🫶
• If the DialogShell becomes unmapped (but stays managed) and then remapped, this resource has no influence on the DialogShell's position. Sorry babe, that ship has sailed.
• If this resource is False, the DialogShell does not automatically center itself.

👑 XmNdialogStyle

Indicates the dialog style associated with the BulletinBoard.

• If the parent of the BulletinBoard is a DialogShell, the parent's XmNmwmInputMode is set according to the value of this resource.
• This resource can be set only if the BulletinBoard is unmanaged. Read that again. 📢

Possible values for this resource include the following:

• XmDIALOG_SYSTEM_MODAL — Used for dialogs that must be responded to before any other interaction in any application.
• XmDIALOG_PRIMARY_APPLICATION_MODAL — Used for dialogs that must be responded to before some other interactions in ancestors of the widget.
• XmDIALOG_APPLICATION_MODAL — Used for dialogs that must be responded to before some other interactions in ancestors of the widget. This value is the same as XmDIALOG_PRIMARY_APPLICATION_MODAL, and remains for compatibility. (Legacy icon behavior, we respect it 💅)
• XmDIALOG_FULL_APPLICATION_MODAL — Used for dialogs that must be responded to before some other interactions in the same application.
• XmDIALOG_MODELESS — Used for dialogs that do not interrupt interaction of any application. This is the default when the parent of the BulletinBoard is a DialogShell.
• XmDIALOG_WORK_AREA — Used for BulletinBoard widgets whose parents are not DialogShells. XmNdialogStyle is forced to have this value when the parent of the BulletinBoard is not a DialogShell.

⚠️ Okay serious moment, no cap: posting a modal dialog in response to a button down or key down event (via translation actions or callbacks) can cause the corresponding button up or key up event to be lost. For example, posting a modal dialog from an XmNincrementCallback of XmScrollBar will cause the loss of the button up event, causing the XmScrollBar to auto-increment indefinitely. It's giving runaway scrollbar. Do not do this. 🙈

🍓 XmNdialogTitle

Specifies the dialog title. If this resource is not NULL, and the parent of the BulletinBoard is a subclass of WMShell, BulletinBoard sets the XmNtitle and XmNtitleEncoding of its parent.

Now the encoding detective work:

• If the only character set in XmNdialogTitle is ISO8859-1, XmNtitle is set to the string of the title, and XmNtitleEncoding is set to STRING.
• If XmNdialogTitle contains character sets other than ISO8859-1, XmNtitle is set to the string of the title converted to a compound text string, and XmNtitleEncoding is set to COMPOUND_TEXT.

The direction of the title is based on the XmNlayoutDirection resource of the widget. Global girly behavior ✨

🧚 XmNfocusCallback

Specifies the list of callbacks that is called when the BulletinBoard widget or one of its descendants accepts the input focus. The callback reason is XmCR_FOCUS. So not just the main character — the whole friend group counts.

💖 XmNlabelFontList

Specifies the font list used for label descendants. See the XmNlabelRenderTable resource, bestie.

🌟 XmNlabelRenderTable

Specifies the render table used for BulletinBoard's label descendants. Same lil scavenger hunt as the button one:

1. If this value is NULL at initialization, the parent hierarchy of the widget is searched for an ancestor that holds the XmQTspecifyRenderTable trait.
2. If such an ancestor is found, the render table is initialized to the XmLABEL_RENDER_TABLE value of that ancestor widget.
3. If no such ancestor is found, the default is implementation dependent.

Refer to XmRenderTable(3) for more info on the creation and structure of a render table. 👑

🌈 XmNmapCallback

Specifies the list of callbacks that is called only when the parent of the BulletinBoard is a DialogShell. In this case, this callback list is invoked when the BulletinBoard widget is mapped. The callback reason is XmCR_MAP.

Fun fact for the lore: DialogShells are usually mapped when the DialogShell is managed. The way that's a whole dependency chain 💀

🎀 XmNmarginHeight

Specifies the minimum spacing in pixels between the top or bottom edge of BulletinBoard and any child widget. Personal space, but for widgets. Respected. 🫶

🎀 XmNmarginWidth

Specifies the minimum spacing in pixels between the left or right edge of BulletinBoard and any child widget. The horizontal twin of XmNmarginHeight. Matching set, iconic.

🦋 XmNnoResize

Controls whether or not resize controls are included in the window manager frame around the BulletinBoard's parent.

• If this resource is set to True, mwm does not include resize controls in the window manager frame containing the parent of the BulletinBoard, if the parent is a subclass of VendorShell.
• If this resource is set to False, the window manager frame does include resize controls.

Other controls provided by mwm can be included or excluded through the mwm resources provided by VendorShell. So like, this one's just about resize specifically, don't come for the others 💅

✨ XmNresizePolicy

Controls the policy for resizing BulletinBoard widgets. Possible values include:

• XmRESIZE_NONE — Fixed size. Immovable. Unbothered. Locked in.
• XmRESIZE_ANY — Shrink or grow as needed. Flexible queen.
• XmRESIZE_GROW — Grow only. Never shrink. Boundaries are healthy.

🔥 XmNshadowType

Describes the shadow drawing style for BulletinBoard. This resource can have the following values:

• XmSHADOW_IN — Draws the BulletinBoard shadow so that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed. Sneaky lil flip.
• XmSHADOW_OUT — Draws the BulletinBoard shadow so that it appears outset.
• XmSHADOW_ETCHED_IN — Draws the BulletinBoard shadow using a double line, giving the effect of a line etched into the window, similar to the Separator widget.
• XmSHADOW_ETCHED_OUT — Draws the BulletinBoard shadow using a double line, giving the effect of a line coming out of the window, similar to the Separator widget.

💜 XmNtextFontList

Specifies the font list used for text descendants. See the XmNtextRenderTable resource. You know the drill by now, bestie.

🌸 XmNtextRenderTable

Specifies the render table used for BulletinBoard's text descendants. One more time for the people in the back:

1. If this value is NULL at initialization, the parent hierarchy of the widget is searched for an ancestor that holds the XmQTspecifyRenderTable trait.
2. If such an ancestor is found, the render table is initialized to the XmTEXT_RENDER_TABLE value of that ancestor widget.
3. If no such ancestor is found, the default is implementation dependent.

Refer to XmRenderTable(3) for more info on the creation and structure of a render table. 👑

🧚 XmNtextTranslations

It adds translations to any Text widget or Text widget subclass that is added as a child of BulletinBoard. Tiny resource, huge glow-up for your text children. ✨

• XmNunmapCallback — okay so this one is so specific bestie. It's the list of callbacks that only fires when the parent of the BulletinBoard is a DialogShell. Like, only then. When that's the case, this callback list gets invoked the moment the BulletinBoard widget is unmapped. The callback reason is XmCR_UNMAP. And lowkey a fun fact: DialogShells are usually unmapped when the DialogShell is unmanaged. iykyk 💅

---

✨ Inherited Resources ✨

BulletinBoard is literally that girl who inherited everything from her superclasses 🫶 — it picks up behavior and resources from the superclasses listed in the tables below. And if you want the full tea on any single resource, go read the reference page for that superclass, bestie.

💖 XmManager Resource Set 💖

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

• 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

ngl bestie, notice the access codes do NOT all match — some are CSG, some are CG, some are just C or G. That's not a typo, that's canon. 💀

🦋 Core Resource Set 🦋

okay bestie, here's the whole glow-up menu of resources this widget inherits-slash-rocks. Every single one, no skipping, we don't do that here 💅

• 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

that's nineteen resources, count them, they're all there, we're so thorough it's giving studious 📚✨

---

🎀 Callback Information 🎀

so when a callback fires, this lil pointer gets handed to it. it's the same struct every time, no cap:

typedef struct
{
        int reason;
        XEvent * event;
} XmAnyCallbackStruct;

• reason — spills the tea on why the callback got invoked in the first place 🫖
• event — points at the XEvent that triggered the callback, the whole origin story

---

🌸 Translations 🌸

XmBulletinBoard includes the translations from XmManager. that's it, that's the sentence, it's a hand-me-down situation and honestly? iconic. inheritance slay

---

🔥 Additional Behavior 🔥

the XmBulletinBoard widget has some extra moves of its own, and here's the full list bestie:

• <Key><osfCancel>: Calls the activate callbacks for the cancel button if it is sensitive. And if there's literally no cancel button and the parent of the BulletinBoard is a manager? Then it passes the event up to the parent. passing the buck, respectfully
• <Key><osfActivate>: Calls the activate callbacks for the button with the keyboard focus. But if no button has the keyboard focus, it calls the activate callbacks for the default button if it is sensitive. And here's the sneaky detail — in a List widget or a single-line Text widget, the List or Text action associated with <Key><osfActivate> gets called before the BulletinBoard actions associated with <Key><osfActivate>. order matters, no cutting the line 🚫

ngl the List/Text precedence thing is exactly the kind of fine print that'll have you staring at a stack trace at 2am wondering why your default button did nothing. it's not a bug, it's documented behavior, bestie 😭

• <Key><osfActivate> (inside a multiline Text widget) — okay so any <Key><osfActivate> event except <Key><Enter> does a whole little relay race: it calls the Text action associated with <Key><osfActivate>, and then it calls the BulletinBoard actions associated with <Key><osfActivate>. And if no button has the focus, and there's no default button, and the parent of the BulletinBoard is a manager? It hands the event off to the parent. Passing the aux cord, respectfully. 🎧
• <FocusIn> — calls the callbacks for XmNfocusCallback. When the focus policy is XmPOINTER, those callbacks fire when the pointer enters the window. When the focus policy is XmEXPLICIT, they fire when the user traverses to the widget. Two doors, same glow-up. ✨
• <Map> — calls the callbacks for XmNmapCallback. 💖
• <Unmap> — calls the callbacks for XmNunmapCallback. 💔

---

🦋 Virtual Bindings 🦋

Bestie, listen — the bindings for virtual keys are vendor specific. No universal lore, it's giving "every platform wrote its own fanfic." 📖

For the info on bindings for virtual buttons and keys, go see VirtualBindings(3). That's the source of truth, iykyk. 👑

---

🌈 RELATED 🌈

The whole friend group, in alphabetical-ish order:

• Composite(3)
• Constraint(3)
• Core(3)
• XmCreateBulletinBoard(3)
• XmCreateBulletinBoardDialog(3)
• XmDialogShell(3)
• XmManager(3)
• XmVaCreateBulletinBoard(3)
• and XmVaCreateManagedBulletinBoard(3)

---

and that's the whole page, bestie!! 🫶 you made it to the end of XmBulletinBoard(library call) — yes it's a library call, that's the source/version tea, and this is where the page signs off. no date on this one, just the vibe. go build something iconic with it, mwah 💅🎀🌸