XMDRAWNBUTTON(3)

💖 XmDrawnButton 💖

okay bestie, welcome to the XmDrawnButton page — it's a library call, and it's genuinely one of the cutest little widgets in the whole Motif family. let's get into it. 🎀

---

✨ NAME ✨

XmDrawnButton — The DrawnButton widget class

---

✨ SYNOPSIS ✨

#include <Xm/DrawnB.h>

---

✨ DESCRIPTION ✨

so like. picture this. the DrawnButton widget is literally an empty widget window that's surrounded by a shadow border. that's it. that's the whole vibe. it hands the application developer a graphics area — a little canvas, a blank stage, a moment of silence before the art — and that area gets PushButton input semantics. so you draw whatever you want in there, and it still behaves like a button. iconic behavior honestly. 👑

callback types are defined for widget exposure and widget resize, so your app can redraw or reposition its graphics whenever it needs to. slay.

⚠️ important one, bestie: if the DrawnButton widget has a highlight and shadow thickness, the application should not draw in that area. periodt.

and the way to avoid drawing in the highlight and shadow area? create the graphics context with a clipping rectangle for drawing in the widget. the clipping rectangle should take into account the size of the widget's highlight thickness and shadow. that's the move. 🫶

DrawnButton uses the XmQTmenuSystem and XmQTspecifyRenderTable traits, and holds the XmQTactivatable trait.

---

🌸 Classes 🌸

DrawnButton inherits behavior, resources, and traits from the Core, Primitive, and XmLabel classes. (yes, it's a whole family tree and DrawnButton is the main character at the bottom of it.)

The class pointer is xmDrawnButtonWidgetClass.

The class name is XmDrawnButton.

---

🌈 New Resources 🌈

okay so here's the resource table, but make it group chat. the following set of widget resources is 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 — yes, the underscores stay, don't come for them).

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).

💅 XmDrawnButton Resource Set 💅

• XmNactivateCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNarmCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNdisarmCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNexposeCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNmultiClick — class XmCMultiClick, type unsigned char, default dynamic, access CSG
• XmNpushButtonEnabled — class XmCPushButtonEnabled, type Boolean, default False, access CSG
• XmNresizeCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNshadowType — class XmCShadowType, type unsigned char, default XmSHADOW_ETCHED_IN, access CSG

---

🦋 and here's what each one actually does 🦋

• XmNactivateCallback — Specifies the list of callbacks that is called when the widget becomes selected. The reason sent by the callback is XmCR_ACTIVATE. This callback uses the XmQTactivatable trait. ✨
• XmNarmCallback — Specifies the list of callbacks that is called when the widget becomes armed. The reason sent by the callback is XmCR_ARM. 🔥
• XmNdisarmCallback — Specifies the list of callbacks that is called when the widget becomes disarmed. The reason sent by the callback is XmCR_DISARM.
• XmNexposeCallback — Specifies the list of callbacks that is called when the widget receives an exposure event. The reason sent by the callback is XmCR_EXPOSE. 👀
• XmNmultiClick — okay so this one is about double clicks, and the vibes are specific. If a button click is followed by another button click within the time span specified by the display's multiclick time, and this resource is set to XmMULTICLICK_DISCARD, the second click is not processed. If this resource is set to XmMULTICLICK_KEEP, the event is processed and click_count is incremented in the callback structure. When the button is not in a menu, the default value is XmMULTICLICK_KEEP.
• XmNpushButtonEnabled — Enables or disables the 3-dimensional shadow drawing as in PushButton. that's literally it, it's the 3D toggle. 💅
• XmNresizeCallback — Specifies the list of callbacks that is called when the widget receives a resize event. The reason sent by the callback is XmCR_RESIZE. The event returned for this callback is NULL. (yeah, NULL. it's giving "no event for you." 🙈)
• XmNshadowType — Describes the drawing style for the DrawnButton. This resource can have the following values:
  • XmSHADOW_IN — Draws the DrawnButton so that the shadow appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed.
  • XmSHADOW_OUT — Draws the DrawnButton so that the shadow appears outset.
  • XmSHADOW_ETCHED_IN — Draws the DrawnButton using a double line. This gives the effect of a line etched into the window. The thickness of the double line is equal to the value of XmNshadowThickness.
  • XmSHADOW_ETCHED_OUT — Draws the DrawnButton using a double line. This gives the effect of a line coming out of the window. The thickness of the double line is equal to the value of XmNshadowThickness.

---

🎀 Inherited Resources 🎀

DrawnButton 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. (iykyk — we're going up the family tree from here. 🌳)

🎀 XmLabel Resource Set 🎀

okay bestie, this is the full roster — every single resource this widget's label machinery knows about. name, class, type, default, and whether you can actually reach it through the standard access calls (that's the Access column, and N/A means not applicable, CSG means it's fair game for the usual get/set/whatever crowd). no skips, no "and so on", all nineteen of them, in order, periodt. 💖

• XmNaccelerator — class XmCAccelerator, type String, default NULL, access N/A.
• XmNacceleratorText — class XmCAcceleratorText, type XmString, default NULL, access N/A.
• XmNalignment — class XmCAlignment, type unsigned char, default dynamic, access CSG.
• XmNfontList — class XmCFontList, type XmFontList, default dynamic, access CSG.
• XmNlabelInsensitivePixmap — class XmCLabelInsensitivePixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG.
• XmNlabelPixmap — class XmCLabelPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG.
• XmNlabelString — class XmCXmString, type XmString, default "\0", access CSG.
• XmNlabelType — class XmCLabelType, type unsigned char, default XmSTRING, access CSG.
• XmNmarginBottom — class XmCMarginBottom, type Dimension, default 0, access CSG.
• XmNmarginHeight — class XmCMarginHeight, type Dimension, default 2, access CSG.
• XmNmarginLeft — class XmCMarginLeft, type Dimension, default 0, access CSG.
• XmNmarginRight — class XmCMarginRight, type Dimension, default 0, access CSG.
• XmNmarginTop — class XmCMarginTop, type Dimension, default 0, access CSG.
• XmNmarginWidth — class XmCMarginWidth, type Dimension, default 2, access CSG.
• XmNmnemonic — class XmCMnemonic, type KeySym, default NULL, access N/A.
• XmNmnemonicCharSet — class XmCMnemonicCharSet, type String, default XmFONTLIST_DEFAULT_TAG, access N/A.
• XmNrecomputeSize — class XmCRecomputeSize, type Boolean, default True, access CSG.
• XmNrenderTable — class XmCRenderTable, type XmRenderTable, default dynamic, access CSG.
• XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CSG.

---

a lil vibe check on that list ✨ — see how the margins are just vibing at 0 and 2, and three whole resources said "my default is dynamic, figure it out"? that's not me being vague, that's literally what the table says, and I refuse to elaborate further because I do not make the rules. 😭

and yes, XmNlabelString defaults to the extremely dramatic "\0" — an empty string, a blank canvas, a girl with nothing to say yet. character development pending. 💅

heads up: the N/A in that Access column is doing real work, bestie — don't come for me later saying I didn't warn you that not every one of these is a normal read/write situation. 🫶

also XmFONTLIST_DEFAULT_TAG for XmNmnemonicCharSet and XmUNSPECIFIED_PIXMAP for both the pixmap resources — those aren't typos, that's genuinely the documented default, copy it exactly or the compiler will simply not. no cap. 💀

next up, the fun stuff continues — don't go anywhere, we're so not done here 🦋

🎀 XmPrimitive Resource Set 🎀

okay bestie, deep breath, because this is the big one — the full resource table for XmPrimitive, which XmDrawnButton inherits from like it's family money 💅. Five columns, eighteen rows, no skips, no shortcuts. Here's how to read each line: the resource Name comes first, then its Class, then the Type, then the Default, and finally the Access column (which is literally just C, CSG, or CG — that's what's written, that's what you get 🫶).

---

• XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG 🌸
• XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG ✨
• XmNconvertCallback — class XmCCallback, type XtCallbackList, default NULL, access C 💖
• 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 💜
• XmNhighlightOnEnter — class XmCHighlightOnEnter, type Boolean, default False, access CSG 👑
• XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG 🎀
• XmNhighlightThickness — class XmCHighlightThickness, type Dimension, default 2, access CSG ⭐
• XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG 🧚
• XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmNONE, access CSG 🍓
• XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C 🔥
• XmNshadowThickness — class XmCShadowThickness, type Dimension, default 2, access CSG 💅
• 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 🦋

not me counting them to make sure all eighteen made it 💀 bestie there are literally eighteen and every single one is up there, defaults and access codes and all, no cap 🔥

and yes, the <pink>dynamic</pink> defaults stay written as dynamic because that's exactly what the table says — don't come for me, I'm just the messenger 🫶

💅 Core Resource Set 💅

Okay bestie, here's the whole squad of core resources this widget rolls with. Same energy as every other widget in the fam, but here's the receipt anyway. For each one you get its name, its class, its type, its default, and its access — and yes, every single one is below, no skipping, no "you get the idea" nonsense. 💖

• XmNaccelerators — class XmCAccelerators, type XtAccelerators, default dynamic, access CSG
• XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access G
• XmNbackground — class XmCBackground, type Pixel, default dynamic, access CSG
• XmNbackgroundPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
• XmNborderColor — class XmCBorderColor, type Pixel, default XtDefaultForeground, access CSG
• XmNborderPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
• XmNborderWidth — class XmCBorderWidth, type Dimension, default 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 access column? CSG, CG, C, G — literally what the table says, and I am not about to start guessing at extra lore for you. It's giving "look it up in the Intrinsics docs," bestie. 🙈

---

📞 Callback Information 📞

When a callback fires, it gets handed a pointer to this little struct right here. Here's the exact shape of it, no notes:

typedef struct
{
        int reason;
        XEvent * event;
        Window window;
        int click_count;
} XmDrawnButtonCallbackStruct;

And here's what each field is actually doing:

• reason — tells you why the callback got invoked in the first place. The whole plot, basically. 💅
• event — points at the XEvent that triggered the callback. Heads up though: this one is NULL for XmNresizeCallback. Yes, NULL. Don't come for me, that's just how it is. 😭
• window — set to the window ID where the event went down.
• click_count — holds the number of clicks in the last multiclick sequence if the XmNmultiClick resource is set to XmMULTICLICK_KEEP. Otherwise? It just contains 1. And the activate callback gets invoked for each click if XmNmultiClick is set to XmMULTICLICK_KEEP. So like, either you're getting the real count or you're getting a very confident 1. 🤷

---

⌨️ Translations ⌨️

XmDrawnButton pulls in translations from Primitive, and then it's got some extra XmDrawnButton translations of its own, all listed below. The key names here are written in the X standard key event translation table syntax — that's the format Motif uses to say which widget actions line up with which key. 🎀

If you want the quick-and-dirty overview of that format, go peek at VirtualBindings(3). Want the complete breakdown? That's the X Toolkit Instrinsics Documentation, bestie. Go read it, it's all there. 📚

c<Btn1Down>: ButtonTakeFocus()

okay bestie we're picking up right where we left off, no re-intros, let's go 💖 here's the rest of the bindings:

• ∼c<Btn1Down>: → Arm()
• ∼c<Btn1Down>,∼c<Btn1Up>: → Activate() Disarm()
• ∼c<Btn1Down>(2+): → MultiArm()
• ∼c<Btn1Up>(2+): → MultiActivate()
• ∼c<Btn1Up>: → Activate() Disarm()
• :<Key><osfActivate>: → PrimitiveParentActivate()
• :<Key><osfCancel>: → PrimitiveParentCancel()
• :<Key><osfSelect>: → ArmAndActivate()
• :<Key><osfHelp>: → Help()
• ∼s ∼m ∼a <Key>Return: → PrimitiveParentActivate()
• ∼s ∼m ∼a <Key>space: → ArmAndActivate()

---

🎬 Action Routines 🎬

The XmDrawnButton action routines are right here, babes:

• Activate() — if XmNpushButtonEnabled is True, it redraws the shadow in the unselected state; otherwise it redraws the shadow according to XmNshadowType. And if the pointer is within the DrawnButton, it calls the XmNactivateCallback callbacks. slay ✨
• Arm() — if XmNpushButtonEnabled is True, it redraws the shadow in the selected state; otherwise it redraws the shadow according to XmNshadowType. Then it calls the callbacks for XmNarmCallback.
• ArmAndActivate() — if XmNpushButtonEnabled is True, it redraws the shadow in the selected state; otherwise it redraws the shadow according to XmNshadowType. Then it calls the callbacks for XmNarmCallback.

If XmNpushButtonEnabled is True, the shadow is redrawn in the unselected state; otherwise the shadow is redrawn according to XmNshadowType. The callbacks for XmNactivateCallback and XmNdisarmCallback are called. And bestie, listen — these actions happen either immediately or at a later time. both. it's giving mysterious 💅

• ButtonTakeFocus() — causes the PushButton to take keyboard focus when Ctrl<Btn1Down> is pressed, without activating the widget. focus only, no clicking, we're just looking respectfully 👀
• Disarm() — marks the DrawnButton as unselected and calls the callbacks for XmNdisarmCallback.
• Help() — calls the callbacks for XmNhelpCallback if any exist. And if there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. it goes up the family tree, iconic 🫶
• MultiActivate() — if XmNmultiClick is XmMULTICLICK_DISCARD, this action does nothing. periodt.

If XmNmultiClick is XmMULTICLICK_KEEP, this action increments click_count in the callback structure. If XmNpushButtonEnabled is True, this action redraws the shadow in the unselected state; otherwise it redraws the shadow according to XmNshadowType. And if the pointer is within the DrawnButton, this action calls the XmNactivateCallback callbacks and calls the callbacks for XmNdisarmCallback.

• MultiArm() — if XmNmultiClick is XmMULTICLICK_DISCARD, this action does nothing.

If XmNmultiClick is XmMULTICLICK_KEEP and if XmNpushButtonEnabled is True, this action redraws the shadow in the selected state; otherwise it redraws the shadow according to XmNshadowType and calls the callbacks for XmNarmCallback.

---

✨ Additional Behavior ✨

This widget has the following additional behavior, no cap:

• <EnterWindow> — draws the shadow in its selected state if XmNpushButtonEnabled is True and if the cursor leaves and re-enters the window while BSelect is pressed. 😭 she remembered you
• <LeaveWindow> — draws the shadow in its unselected state if XmNpushButtonEnabled is True and if the cursor leaves the window while BSelect is pressed.

---

🌈 Virtual Bindings 🌈

The bindings for virtual keys are vendor specific — like, everyone's doing their own thing, iykyk. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

---

🔗 RELATED 🔗

the whole friend group, fr fr 💜

• Core(3)
• XmCreateDrawnButton
• XmLabel(3)
• XmPrimitive(3)
• XmPushButton
• XmSeparator(3)
• XmVaCreateDrawnButton
• XmVaCreateManagedDrawnButton

---

and that's the whole page, bestie, we ate and left no crumbs 🎀 this one's the XmDrawnButton(library call) manpage — that's the footer, that's the credit, that's the whole vibe. go forth and draw those buttons, my little main character 👑💅