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

💖 XmPushButtonGadget 💖

okay bestie, so this is XmPushButtonGadget(library call) — yes, a whole library call manual page, and it's a long one, so buckle up. We're doing this in five parts and this is part one. Let's go 🫶

✨ NAME ✨

XmPushButtonGadget — The PushButtonGadget widget class

✨ SYNOPSIS ✨

#include <Xm/PushBG.h>

✨ DESCRIPTION ✨

So, PushButtonGadget issues commands within an application. That's the whole job. It's giving "one button, one destiny." 💅

It consists of a text label or pixmap surrounded by a border shadow. When PushButtonGadget is selected, the shadow changes to give the appearance that the PushButtonGadget has been pressed in. When PushButtonGadget is unselected, the shadow changes to give the appearance that the PushButtonGadget is out. literally just a visual glow-up and glow-down, no cap.

The default behavior associated with a PushButtonGadget in a menu depends on the type of menu system in which it resides. By default, <Btn1> controls the behavior of the PushButtonGadget. In addition, <Btn3> controls the behavior of the PushButtonGadget if it resides in a PopupMenu system. The actual mouse button used is determined by its RowColumn parent. so it's not really the button's call — it's the parent's vibe check. 👑

Thickness for a second shadow may be specified with the XmNshowAsDefault resource. If it has a nonzero value, the Label's XmNmarginLeft, XmNmarginRight, XmNmarginTop, and XmNmarginBottom resources may be modified to accommodate the second shadow. (yes, the second shadow is the main character here, and everyone else has to scooch over for it 🎀)

If an initial value is specified for XmNarmPixmap but not for XmNlabelPixmap, the XmNarmPixmap value is used for XmNlabelPixmap. cute little inheritance moment, honestly obsessed.

PushButtonGadget uses the XmQTmenuSystem and XmQTspecifyRenderTable traits, and holds the XmQactivatable, XmQTmenuSavvy, and XmQTtakesDefault traits. traits = the personality it brings to every room it walks into, fr fr.

🌸 Classes 🌸

PushButtonGadget inherits behavior, resources, and traits from Object, RectObj, XmGadget and XmLabelGadget. four ancestors, one iconic gadget.

The class pointer is xmPushButtonGadgetClass.

The class name is XmPushButtonGadget.

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

📋 the resource set, aka the receipts. Name / Class / Type / Default / Access, one bullet each, because we do not do tables in this house 💖

💫 XmPushButtonGadget Resource Set

  • XmNactivateCallback — Class: XmCCallback · Type: XtCallbackList · Default: NULL · Access: C
  • XmNarmCallback — Class: XmCCallback · Type: XtCallbackList · Default: NULL · Access: C
  • XmNarmColor — Class: XmCArmColor · Type: Pixel · Default: dynamic · Access: CSG
  • XmNarmPixmap — Class: XmCArmPixmap · Type: Pixmap · Default: XmUNSPECIFIED_PIXMAP · Access: CSG
  • XmNdefaultButtonShadowThickness — Class: XmCdefaultButtonShadowThickness · Type: Dimension · Default: dynamic · Access: CSG
  • XmNdisarmCallback — Class: XmCCallback · Type: XtCallbackList · Default: NULL · Access: C
  • XmNfillOnArm — Class: XmCFillOnArm · Type: Boolean · Default: True · Access: CSG
  • XmNmultiClick — Class: XmCMultiClick · Type: unsigned char · Default: dynamic · Access: CSG
  • XmNshowAsDefault — Class: XmCShowAsDefault · Type: Dimension · Default: 0 · Access: CSG

🌟 The resources, explained with love 🌟

  • XmNactivateCallback — Specifies the list of callbacks that is called when the PushButtonGadget is activated. It is activated when the user presses and releases the active mouse button while the pointer is inside the PushButtonGadget. Activating PushButtonGadget also disarms it. For this callback, the reason is XmCR_ACTIVATE. This callback uses the XmQTactivatable trait. the moment the button goes "✨ and I oop, consider it done ✨".
  • XmNarmCallback — Specifies the list of callbacks that is called when PushButtonGadget is armed. It is armed when the user presses the active mouse button while the pointer is inside the PushButtonGadget. For this callback, the reason is XmCR_ARM. armed = cocked and loaded, the pre-game, the inhale before the scream. 🫶
  • XmNarmColor — Specifies the color with which to fill the armed button. XmNfillOnArm must be set to True for this resource to have an effect. The default for a color display is a color between the background and the bottom shadow color. For a monochrome display, the default is set to the foreground color, and any text in the label appears in the background color when the button is armed. yes, on monochrome it does the full swap — text goes background-colored, no cap, that's just the deal.
  • XmNarmPixmap — Specifies the pixmap to be used as the button face if XmNlabeltype is XmPIXMAP or XmPIXMAP_AND_STRING and PushButtonGadget is armed. This resource is disabled when the PushButtonGadget is in a menu. 💀 sorry bestie, in a menu it simply does not get to participate.
  • XmNdefaultButtonShadowThickness — This resource specifies the width of the default button indicator shadow. If this resource is 0 (zero), the width of the shadow comes from the value of the XmNshowAsDefault resource. If this resource is greater than zero, the XmNshowAsDefault resource is only used to specify whether this button is the default. The default value is the initial value of XmNshowAsDefault. so it's giving "who's in charge of the shadow width" and the answer changes depending on whether this is zero. stay woke. 👑
  • XmNdisarmCallback — Specifies the list of callbacks that is called when the PushButtonGadget is disarmed. PushButtonGadget is disarmed when the user presses and releases the active mouse button while the pointer is inside that gadget. For this callback, the reason is XmCR_DISARM. the "jk jk, we're chill again" callback 😭
  • XmNfillOnArm — Forces the PushButtonGadget to fill the background of the button with the color specified by XmNarmColor when the button is armed and when this resource is set to True. If it is False, only the top and bottom shadow colors are switched. When the PushButtonGadget is in a menu, this resource is ignored and assumed to be False. > 🚨 important: in a menu, whatever you set here gets ignored and treated as False. periodt.

okay that's part one bestie, don't go anywhere, more parts are coming 💖✨

✨ XmNmultiClick ✨

okay so bestie, imagine someone's out here mashing the button like it owes them money 💀 — here's the tea:

  • If a button click gets followed by another button click within the time span the display's multiclick time says, and this resource is set to XmMULTICLICK_DISCARD, then that second click just… does not get processed. it's giving "we're not doing that today."
  • But if this resource is set to XmMULTICLICK_KEEP, then the event does get processed, and click_count gets incremented in the callback structure. slay. 💅
  • Defaults? When the button is in a menu, the default is XmMULTICLICK_DISCARD. Otherwise, for a button not in a menu, the default is XmMULTICLICK_KEEP. 🫶

💖 XmNshowAsDefault 💖

this one's the "notice me, I'm the special one" resource, no cap:

  • If XmNdefaultButtonShadowThickness is greater than 0 (zero), then any value greater than zero in this resource tells the world to mark this button as the default button.
  • If XmNdefaultButtonShadowThickness is 0, then a value greater than 0 in this resource tells the world to mark this button as the default button with the shadow thickness specified by this resource.
  • The space between the shadow and the default shadow is equal to the sum of both shadows. math is mathing ✨
  • The default value is 0.
  • When the Display resource XmNdefaultButtonEmphasis has a value of XmEXTERNAL_HIGHLIGHT (which is the default, iykyk), PushButton draws the location cursor outside of the outer shadow.
  • When this resource has a value of XmINTERNAL_HIGHLIGHT, the highlight gets drawn between the inner and outer shadows. iconic behavior.
  • When this value is not 0, the Label XmNmarginLeft, XmNmarginRight, XmNmarginTop, and XmNmarginBottom resources may get modified to accommodate that second shadow. they're just making room bestie, let them live 🎀
  • 🚨 and heads up: this resource is disabled when the PushButton is in a menu. periodt.

🌈 Inherited Resources 🌈

PushButtonGadget inherits behavior and resources from the superclasses described in the tables that follow. For the full deets on each and every resource, go check the reference page for that superclass — it's all there, fr fr. 💜

✨ XmLabelGadget Resource Set ✨

okay so bestie, this is literally the whole entire resource set for XmLabelGadget, and I am not skipping a single one because that would be disrespectful to the craft 💅 The original was a big fancy table with columns Name, Class, Type, Default, and Access, but we're doing it list-style because tables are giving ✨ boomer energy ✨ and we are not that.

every single row below is exactly as it appears in the manual, no cap. Class, type, default, access — all of it. 🫶
  • XmNaccelerator — Class: XmCAccelerator; Type: String; Default: NULL; Access: CSG
  • XmNacceleratorText — Class: XmCAcceleratorText; Type: XmString; Default: NULL; Access: CSG
  • 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: dynamic; Access: CSG
  • XmNlabelString — Class: XmCXmString; Type: XmString; Default: dynamic; Access: CSG
  • XmNlabelType — Class: XmCLabelType; Type: unsigned char; Default: XmSTRING; Access: CSG
  • XmNmarginBottom — Class: XmCMarginBottom; Type: Dimension; Default: dynamic; Access: CSG
  • XmNmarginHeight — Class: XmCMarginHeight; Type: Dimension; Default: 2; Access: CSG
  • XmNmarginLeft — Class: XmCMarginLeft; Type: Dimension; Default: dynamic; Access: CSG
  • XmNmarginRight — Class: XmCMarginRight; Type: Dimension; Default: dynamic; Access: CSG
  • XmNmarginTop — Class: XmCMarginTop; Type: Dimension; Default: dynamic; Access: CSG
  • XmNmarginWidth — Class: XmCMarginWidth; Type: Dimension; Default: 2; Access: CSG
  • XmNmnemonic — Class: XmCMnemonic; Type: KeySym; Default: NULL; Access: CSG
  • XmNpixmapPlacement — Class: XmCPixmapPlacement; Type: unsigned int; Default: XmPIXMAP_LEFT; Access: CSG
  • XmNpixmapTextPadding — Class: XmCSpace; Type: Dimension; Default: 2; Access: CSG
  • XmNmnemonicCharSet — Class: XmCMnemonicCharSet; Type: String; Default: dynamic; Access: CSG
  • 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

🌈 XmGadget Resource Set 🌈

ok so these are the resources our girl gets handed down from her XmGadget ancestor — the whole entire list, nothing skipped, we do not gatekeep here 💖 The OG table's columns are Name, Class, Type, Default, and Access, so that's exactly what every bullet below is serving you.

  • XmNbackground — class XmCBackground, type Pixel, default dynamic, access CSG
  • XmNbackgroundPixmap — class XmCPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default dynamic, access CSG
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG
  • 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 XmNCLayoutDirection, type XmDirection, default dynamic, access CG
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmNONE, access CSG
  • 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

that's eighteen, count them, all of them, periodt 💅

🦋 RectObj Resource Set 🦋

and then there's the RectObj set — even further up the family tree, the rectangle ancestor that everyone shares 🫶 same deal, same columns, every row:

  • XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access G
  • XmNborderWidth — class XmCBorderWidth, type Dimension, default 0, access N/A
  • XmNheight — class XmCHeight, type Dimension, default dynamic, access CSG
  • XmNsensitive — class XmCSensitive, type Boolean, default True, 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

ngl the way these two tables are just quietly doing the most important work and never getting credit... main character energy in the background fr 💀

keep scrolling bestie, there's more of this family tree to unfold 👀

🎀 Object Resource Set 🎀

Here's the whole resource lineup for this gadget, bestie. One entry, but she's important:

  • XmNdestroyCallback — Class: XmCCallback · Type: XtCallbackList · Default: NULL · Access: C

💖 Callback Information 💖

Every time a callback fires, it gets handed a pointer to this lil struct, fr fr:

typedef struct
{
        int reason;
        XEvent * event;
        int click_count;
} XmPushButtonCallbackStruct;
  • reason — tells you why the callback got invoked in the first place. 👀
  • event — points at the XEvent that triggered the callback.
  • click_count — only valid when reason is XmCR_ACTIVATE. It holds the number of clicks in the last multiclick sequence if the XmNmultiClick resource is set to XmMULTICLICK_KEEP; otherwise it just says 1. And heads up: the activate callback gets invoked for each click when XmNmultiClick is set to XmMULTICLICK_KEEP.

🔥 Behavior 🔥

XmPushButtonGadget picks up behavior from XmGadget, and it also gets menu traversal behavior from XmLabelGadget. Everything extra it does is right here:

  • <Btn2Down> — drags the contents of a PushButtonGadget label, which gets identified the moment <Btn2> is pressed.
This action is undefined for PushButtonGadgets used in a menu system. Don't do it. 💀
  • <Btn1Down> — arms the PushButtonGadget. Iconic.

In a menu, this action unposts any menus posted by the PushButtonGadget's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state. Unless the button is already armed, it calls the XmNarmCallback callbacks.

If the button is not in a menu, this action draws the shadow in the armed state. If XmNfillOnArm is set to True, it fills the button with the color specified by XmNarmColor. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNarmPixmap is used for the button face. It calls the XmNarmCallback callbacks.

  • <Btn1>(2+) — if XmNmultiClick is XmMULTICLICK_DISCARD, this action does absolutely nothing. Ghosted. 🫥

If XmNmultiClick is XmMULTICLICK_KEEP, this action draws the shadow in the armed state. If the button is not in a menu and if XmNfillOnArm is set to True, it fills the button with the color specified by XmNarmColor. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNarmPixmap is used for the button face. This action calls the XmNarmCallback callbacks.

  • <Btn1Up> — in a menu, this action unposts all menus in the menu hierarchy and activates the PushButtonGadget. It calls the XmNactivateCallback callbacks and then the XmNdisarmCallback callbacks.

If the PushButtonGadget is not in a menu, this action draws the shadow in the unarmed state. If XmNfillOnArm is set to True, the background color reverts to the unarmed color. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNlabelPixmap is used for the button face. If the pointer is still within the button, this action calls the callbacks for XmNactivateCallback and XmNdisarmCallback.

  • <Btn1Up>(2+) — if XmNmultiClick is XmMULTICLICK_DISCARD, this action does nothing. Again. 🤷

If XmNmultiClick is XmMULTICLICK_KEEP, this action increments click_count in the callback structure and draws the shadow in the unarmed state. If the button is not in a menu and if XmNfillOnArm is set to True, the background color reverts to the unarmed color. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, XmNlabelPixmap is used for the button face. If the pointer is within the PushButtonGadget, this action calls the callbacks for XmNactivateCallback and XmNdisarmCallback.

  • <Key><osfActivate> — in a menu, this action unposts all menus in the menu hierarchy, unless the button is already armed, and calls the XmNarmCallback callbacks, the XmNactivateCallback and the XmNdisarmCallback callbacks. Outside a menu, KActivate has no effect. For PushButtonGadgets outside of a menu, if the parent is a manager, this action passes the event to the parent.
  • <Key><osfSelect> — in a menu, this action unposts all menus in the menu hierarchy, unless the button is already armed, and calls the XmNarmCallback callbacks. This action calls the XmNactivateCallback and XmNdisarmCallback callbacks.

Outside a menu, this action draws the shadow in the armed state and, if XmNfillOnArm is set to True, fills the button with the color specified by XmNarmColor. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, XmNarmPixmap is used for the button face. This action calls the XmNarmCallback callbacks.

Outside a menu, this action also arranges for the following to happen, either immediately or at a later time: the shadow is drawn in the unarmed state and, if XmNfillOnArm is set to True, the background color reverts to the unarmed color. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNlabelPixmap is used for the button face. The XmNactivateCallback and XmNdisarmCallback callbacks are called.

  • <Key><osfHelp> — in a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and restores keyboard focus to the widget that had the focus before the menu system was entered. This action calls the callbacks for XmNhelpCallback if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. (Finding your nearest ancestor who can help = the realest thing ever. 🫶)
  • <Key><osfCancel> — in a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu.

In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. For a PushButtonGadget outside of a menu, if the parent is a manager, this action passes the event to the parent.

  • <Enter> — in a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the XmNarmCallback callbacks.

If the PushButtonGadget is not in a menu and the cursor leaves and then reenters the PushButtonGadget while the button is pressed, this action draws the shadow in the armed state. If XmNfillOnArm is set to True, it also fills the button with the color specified by XmNarmColor. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNarmPixmap is used for the button face.

  • <Leave> — in a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the XmNdisarmCallback callbacks.

If the PushButtonGadget is not in a menu and the cursor leaves the PushButtonGadget while the button is pressed, this action draws the shadow in the unarmed state. If XmNfillOnArm is set to True, the background color reverts to the unarmed color. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNlabelPixmap is used for the button face.

🌈 Virtual Bindings 🌈

The bindings for virtual keys are vendor specific — so like, ask your vendor, not me. For information about bindings for virtual buttons and keys, go read VirtualBindings(3).

Besties you should also go read, no cap:

That's the whole page, babe! 💖 This was the XmPushButtonGadget(library call) manual page — library call section, that's the source and the version, and the date field on it is empty so there's literally nothing to stamp. Go arm some buttons and slay. 💅✨

📦 where this page comes from