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

💖 XmToggleButton 💖

okay bestie, so this is the manual page for XmToggleButton — and yeah, it lives in the library call section of the manual, so if you were looking for the (3) version, you found it. sit down, grab a strawberry, we're learning about toggle buttons 🌸

✨ NAME ✨

XmToggleButton — the ToggleButton widget class 👑

🌈 SYNOPSIS 🌈

#include <Xm/ToggleB.h>

that's it, that's the whole vibe. one include and you're in 💅

🎀 DESCRIPTION 🎀

so like, ToggleButton's whole thing is setting nontransitory state data inside an application. iykyk. it's the "this is staying set until you say otherwise" girlie, not the flash-in-the-pan press-and-release type.

usually this widget is made of an indicator (square, diamond, or round 🟦 🔷 ⭕) with either text or a pixmap hanging out on one side of it. but lowkey? it can also be just text or just a pixmap, no indicator at all. she's flexible like that 💁

the toggle graphics display a 1-of-many, N-of-many, or 1-of-many-round selection state. here's the mapping, bestie, memorize it:

  • a square indicator → shows an N-of-many selection state
  • a diamond-shaped indicator → shows a 1-of-many selection state
  • a circle-shaped indicator → shows a 1-of-many-round selection state

ToggleButton implies a set or unset state. periodt. and if you've got a label plus an indicator:

  • an empty indicator (square, diamond, or round) = ToggleButton is unset
  • a filled indicator = it is set ✅

that fill can be a check mark, a cross, or the select color. and for a pixmap toggle? different story — different pixmaps get used to display the set/unset states. no cap.

ToggleButton can also indicate an indeterminate state (the "idk her" state 😭):

  • with a label and an indicator → indeterminate shows up as a stippled flat box
  • with a pixmap toggle → a different pixmap is used to display the indeterminate state

okay now the menu tea ☕ the default behavior of a ToggleButton inside a menu depends on the type of menu system it resides in. by default, <Btn1> controls the behavior of the ToggleButton. in addition, <Btn3> controls the behavior of the ToggleButton if it resides in a PopupMenu system. and the actual mouse button used? that's determined by its RowColumn parent. so don't come for the ToggleButton, come for the parent 💀

oh also — Label's resource XmNmarginLeft may be increased to accommodate the toggle indicator when it is created. just a lil heads up so your indicator isn't squished 🫶

and for the trait girlies: ToggleButton uses the XmQTmenuSystem and XmQTspecifyRenderTable traits. iconic behavior honestly ✨

🧚 Classes 🧚

ToggleButton inherits behavior, resources, and traits from Core, XmPrimitive, and XmLabel. it's giving nepo baby but in a cute way, she got it from her ancestors 💜

  • The class pointer is xmToggleButtonWidgetClass.
  • The class name is XmToggleButton.

🌟 New Resources 🌟

okay so this next part is a table that defines a set of widget resources used by the programmer to specify data. and bestie, you can also set the resource values for the inherited classes to set attributes for this widget. that's the family plan, we all share 🥰

here's the trick for your .Xdefaults file:

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

and the codes in the access column tell you what you're allowed to do with a given resource:

  • 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
lowkey important: those access codes are the whole vibe check for each resource, so keep an eye on the table when it shows up next 💅

and that's where this part wraps, bestie — the resource table itself is coming up next, so don't go anywhere 🌸

okay bestie, so here's the whole XmToggleButton Resource Set table, but we're doing it as a list because tables are not the vibe 💅. Every single resource, with its class, type, default, and access — no cap, all of them:

  • XmNarmCallback — Class: XmCArmCallback, Type: XtCallbackList, Default: NULL, Access: C
  • XmNdetailShadowThickness — Class: XmCDetailShadowThickness, Type: Dimension, Default: 2, Access: CSG
  • XmNdisarmCallback — Class: XmCDisarmCallback, Type: XtCallbackList, Default: NULL, Access: C
  • XmNfillOnSelect — Class: XmCFillOnSelect, Type: Boolean, Default: dynamic, Access: CSG
  • XmNindeterminatePixmap — Class: XmCIndeterminatePixmap, Type: Pixmap, Default: XmUNSPECIFIED_PIXMAP, Access: CSG
  • XmNindicatorOn — Class: XmCIndicatorOn, Type: unsigned char, Default: XmINDICATOR_FILL, Access: CSG
  • XmNindicatorSize — Class: XmCIndicatorSize, Type: Dimension, Default: dynamic, Access: CSG
  • XmNindicatorType — Class: XmCIndicatorType, Type: unsigned char, Default: dynamic, Access: CSG
  • XmNselectColor — Class: XmCSelectColor, Type: Pixel, Default: dynamic, Access: CSG
  • XmNselectInsensitivePixmap — Class: XmCSelectInsensitivePixmap, Type: Pixmap, Default: XmUNSPECIFIED_PIXMAP, Access: CSG
  • XmNselectPixmap — Class: XmCSelectPixmap, Type: Pixmap, Default: XmUNSPECIFIED_PIXMAP, Access: CSG
  • XmNset — Class: XmCSet, Type: unsigned char, Default: XmUNSET, Access: CSG
  • XmNspacing — Class: XmCSpacing, Type: Dimension, Default: 4, Access: CSG
  • XmNtoggleMode — Class: XmCToggleMode, Type: unsigned char, Default: XmTOGGLE_BOOLEAN, Access: CSG
  • XmNunselectColor — Class: XmCUnselectColor, Type: Pixel, Default: dynamic, Access: CSG
  • XmNvalueChangedCallback — Class: XmCValueChangedCallback, Type: XtCallbackList, Default: NULL, Access: C
  • XmNvisibleWhenOff — Class: XmCVisibleWhenOff, Type: Boolean, Default: dynamic, Access: CSG

now for the deets on some of these, bestie:

XmNarmCallback 🎀

okay so this is the list of callbacks that get called when the ToggleButton is armed. To arm this widget, you press the active mouse button while your pointer is inside the ToggleButton. The reason for this callback is XmCR_ARM.

XmNdetailShadowThickness ✨

This one sets the thickness of the indicator shadow. The default thickness is 2 pixels, periodt. 💅

XmNdisarmCallback 💅

This is the list of callbacks that fire when ToggleButton is disarmed. To disarm it, you press and release the active mouse button while your pointer is inside the ToggleButton. This widget also gets disarmed when the user moves out of the widget and releases the mouse button while the pointer is outside the widget. The reason for this callback is XmCR_DISARM.

XmNfillOnSelect 🦋

Okay so when this is set to True, it fills the indicator with the color specified in XmNselectColor and switches the top and bottom shadow colors. If it's unset, it fills the indicator with the unselect color. If it's indeterminate, it fills the indicator with half select color and half unselect color. Otherwise, it switches only the top and bottom shadow colors. The default is True only if a box type of indicator (such as a check box) is specified, or if the XmNindicatorType is a 1-of type and a toggle indicator is drawn.

If XmNfillOnSelect is True, XmNset is XmSET, and XmNindicatorOn is XmINDICATOR_NONE, then the ToggleButton's background is set to XmNselectColor. For the other XmNindicatorOn values, only the indicator is filled with XmNselectColor. 🔥

XmNindeterminateInsensitivePixmap 🌸

This specifies the pixmap to be displayed as the button face when the Label XmNlableType resource is XmPIXMAP or XmPIXMAP_AND_STRING, the ToggleButton XmNset resource is XmINDETERMINATE, and the Core XmNsensitive resource is False.

XmNindeterminatePixmap 💖

And this one specifies the pixmap to be displayed as the button face when the Label XmNlableType resource is XmPIXMAP or XmPIXMAP_AND_STRING, the ToggleButton XmNset resource is XmINDETERMINATE, and the Core XmNsensitive resource is True. 👑

  • XmNindicatorOn — okay so if a toggle indicator is gonna get drawn at all, this says it gets drawn over to one side of the toggle text or pixmap, and which side depends on the widget's XmNlayoutDirection resource. The default value is XmINDICATOR_FILL. Toggles accept the following values, bestie:
    • XmINDICATOR_NONE — no space is allocated for the indicator and it is not displayed. Any shadows around the entire widget are switched when the toggle is selected or unselected. ✨
    • XmINDICATOR_BOX — the toggle indicator is in the shape of a shadowed box. 🎀
    • XmINDICATOR_FILL — if the value of the XmDisplay XmNenableToggleVisual resource is True, the visuals are those of XmINDICATOR_CHECK_BOX; if False, the indicator visuals are those of XmINDICATOR_BOX.
    • XmINDICATOR_CHECK — the toggle indicator is in the shape of a checkmark in the foreground color. ✅
    • XmINDICATOR_CHECK_BOX — the toggle indicator is in the shape of a checkmark enclosed in a box. This is the default if the XmDisplay XmNenableToggleVisual resource is set.
    • XmINDICATOR_CROSS_BOX — the toggle indicator is in the shape of a cross enclosed in a box.
    • XmINDICATOR_CROSS — the toggle indicator is in the shape of a cross.

All ToggleButton checks and crosses should be drawn in the foreground color. periodt.

If this resource is not XmINDICATOR_NONE, it will control the appearance of the toggle visual. If XmNset is XmINDETERMINATE and XmNindicatorOn is not XmINDICATOR_NONE, this resource shows a stippled flat box. If XmNset is XmINDETERMINATE, XmNindicatorOn is XmINDICATOR_NONE, and XmNtoggleMode is XmTOGGLE_INDETERMINATE, the label and the ToggleButton are stippled with a combination of the XmNselectColor and the XmNunselectColor color, and the border is flat. 💅

  • XmNindicatorSize — sets the size of the indicator. If no value is specified, the size of the indicator is based on the size of the label string or pixmap. If the label string or pixmap changes, the size of the indicator is recomputed based on the size of the label string or pixmap. Once a value has been specified for XmNindicatorSize, the indicator has that size, regardless of the size of the label string or pixmap, until a new value is specified. The size of indicators inside menus may differ from those outside of menus. Note that a change in this resource may also cause a change in the values of the inherited resources XmNmarginTop, XmNmarginBottom, and XmNmarginLeft. 🦋
  • XmNindicatorType — specifies if the indicator is a 1-of or N-of indicator. For the 1-of indicator, the value can be XmONE_OF_MANY, XmONE_OF_MANY_ROUND, or XmONE_OF_MANY_DIAMOND. For the N-of indicator, the value is XmN_OF_MANY. This value specifies only the visuals and does not enforce the behavior. When the ToggleButton is in a radio box, the default is XmONE_OF_MANY; otherwise, the default is XmN_OF_MANY. Legal values are:
    • XmONE_OF_MANY — when the Display XmNenableToggleVisual resource is set, indicators are drawn with the same appearance as XmONE_OF_MANY_ROUND; otherwise, they appear the same as XmONE_OF_MANY_DIAMOND.
    • XmN_OF_MANY — the indicators are drawn as specified by the XmNindicatorOn resource.
    • XmONE_OF_MANY_ROUND — a shadowed circle. ⭕
    • XmONE_OF_MANY_DIAMOND — a shadowed diamond. 💎
  • XmNselectColor — lets the application specify what color fills the center of the square, diamond-shaped, or round indicator when it is set. If this color is the same as either the top or the bottom shadow color of the indicator, a one-pixel-wide margin is left between the shadows and the fill; otherwise, it is filled completely. The results of this resource depend on the value of the Display resource XmNenableToggleColor. A value of True causes the fill color to use the XmHIGHLIGHT_COLOR color by default. A value of False causes the fill color to use the background color. This resource's 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. To set the background of the button to XmNselectColor when XmNindicatorOn is XmINDICATOR_NONE, the value of XmNfillOnSelect must be explicitly set to True.

This resource is also used as the background color when all of the following conditions are met: the button is armed in a menu, the XmNenableEtchedInMenu resource is True, the XmNindicatorOn resource is False, and the XmNfillOnSelect resource is True.

This resource can take the following values:

  • XmDEFAULT_SELECT_COLOR — is the same as the current dynamic default, which is a color between the background and the bottom shadow color.
  • XmREVERSED_GROUND_COLORS — forces the select color to the foreground color and causes the default color of any text rendered over the select color to be in the background color.
  • XmHIGHLIGHT_COLOR — forces the fill color to use the highlight color.
  • XmNselectInsensitivePixmap — specifies a pixmap used as the button face when the ToggleButton is selected, the button is insensitive, and the Label resource XmNlabelType is set to XmPIXMAP or XmPIXMAP_AND_STRING. If the ToggleButton is unselected and the button is insensitive, the pixmap in XmNlabelInsensitivePixmap is used as the button face. If no value is specified for XmNlabelInsensitivePixmap, that resource is set to the value specified for XmNselectInsensitivePixmap. 🖼️
  • XmNselectPixmap — specifies the pixmap to be used as the button face when XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, and the ToggleButton is selected. When the ToggleButton is unselected, the pixmap specified in the Label's XmNlabelPixmap is used. If no value is specified for XmNlabelPixmap, that resource is set to the value specified for XmNselectPixmap.
  • XmNset — represents the state of the ToggleButton. A value of XmUNSET indicates that the ToggleButton is not set. A value of XmSET indicates that the ToggleButton is set. A value of XmINDETERMINATE indicates that the ToggleButton is in an indeterminate state (neither set nor unset). The ToggleButton states cycle through in the order of XmSET, XmINDETERMINATE (if XmNtoggleMode is set to XmTOGGLE_INDETERMINATE), and XmUNSET, and then back around to XmSET. If XmNtoggleMode is set to XmTOGGLE_BOOLEAN, then the ToggleButton states cycle through in the order of XmSET, then XmUNSET, and then back around to XmSET. Setting this resource sets the state of the ToggleButton. 🔁
  • XmNspacing — specifies the amount of spacing between the toggle indicator and the toggle label (text or pixmap). ✨
  • XmNtoggleMode — specifies the mode of the ToggleButton as either XmTOGGLE_BOOLEAN or XmTOGGLE_INDETERMINATE. The XmTOGGLE_INDETERMINATE value allows the XmNset resource to be able to accept the values XmINDETERMINATE, XmSET, and XmUNSET. The XmNtoggleMode resource is forced to XmTOGGLE_BOOLEAN if the toggle is in an XmRowColumn widget whose radio behavior is XmONE_OF_MANY. In XmTOGGLE_BOOLEAN mode, the XmNset resource can only accept XmSET and XmUNSET.
  • XmNunselectColor — lets the application specify what color fills the center of the square, diamond-shaped, or round indicator when it is not set. If this color is the same as either the top or the bottom shadow color of the indicator, a one-pixel-wide margin is left between the shadows and the fill; otherwise, it is filled completely. This resource's default for a color display is XmNbackground. For a monochrome display, the default is set to the background color. To set the background of the button to XmNunselectColor when XmNindicatorOn is XmINDICATOR_NONE, the value of XmNfillOnSelect must be explicitly set to True. This resource acts like the XmNselectColor resource, but for the case when XmNset is XmUNSET.
  • XmNvalueChangedCallback — specifies the list of callbacks called when the ToggleButton value is changed. To change the value, press and release the active mouse button while the pointer is inside the ToggleButton. This action also causes this widget to be disarmed. For this callback, the reason is XmCR_VALUE_CHANGED. 📣
  • XmNvisibleWhenOff — indicates that the toggle indicator is visible in the unselected state when the Boolean value is True. When the ToggleButton is in a menu, the default value is False. When the ToggleButton is in a RadioBox, the default value is True. 👀

🧬 Inherited Resources 🧬

ToggleButton 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 💖

XmLabel Resource Set 🎀

okay bestie, real talk — before we get to the toggle-specific stuff, your widget is walking in with a whole inherited wardrobe from XmLabel. Every single resource in the set, no skips, no cap. They're listed as Name, Class, Type, Default, and Access, and every last one of them has access CSG 💅

  • 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 XmUNSPECIFIED_PIXMAP, 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 0, 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 ⌨️
  • XmNmnemonicCharSet — class XmCMnemonicCharSet, type String, default XmFONTLIST_DEFAULT_TAG, access CSG 🌈
  • XmNpixmapPlacement — class XmCPixmapPlacement, type unsigned int, default XmPIXMAP_LEFT, access CSG 🌸
  • XmNpixmapTextPadding — class XmCSpace, type Dimension, default 2, 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 🦋

and that's the entire XmLabel resource set, every last one, accounted for ⭐ no sneaky extras hiding in the margins, iykyk 👀

okay bestie, here's the XmPrimitive resource set in full — every single one, no skipping, no gatekeeping 💅 these are the ones that come along for the ride no matter which widget you're building on top of it.

  • XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG. the lil 3D shadow on the bottom edge, and yeah it figures itself out dynamically by default ✨
  • XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG. shadow-as-a-pixmap instead of a color, and it starts out literally unspecified 🙈
  • XmNconvertCallback — class XmCCallback, type XtCallbackList, default NULL, access C. the callback squad for conversions, NULL until you say otherwise
  • XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG. the main character color of the whole widget, dynamic by default 👑
  • XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C. where your help requests land, NULL by default
  • XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG. the color of the highlight, and yes, dynamic ✨
  • XmNhighlightOnEnter — class XmCHighlightOnEnter, type Boolean, default False, access CSG. highlight when the pointer enters? default says nah, False 💀
  • XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG. pixmap version of the highlight, dynamic default
  • XmNhighlightThickness — class XmCHighlightThickness, type Dimension, default 2, access CSG. how chunky the highlight is, default 2 fr fr
  • XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG. which way everything flows, dynamic default — and bestie, notice the access is CG, not CSG?? it's the odd one out, iconic honestly 💅
  • XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmNONE, access CSG. how this thing plays with keyboard traversal, defaults to XmNONE
  • XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C. the popup handler callback list, NULL until you fill it 🫶
  • XmNshadowThickness — class XmCShadowThickness, type Dimension, default dynamic, access CSG. how thick the shadow drama is, dynamic default
  • XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG. the top-edge shadow color, dynamic as always ✨
  • XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG. top shadow but as a pixmap, dynamic default
  • XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG. is this widget reachable by traversal? default True, periodt ✅
  • XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG. the unit type, typed as unsigned char, dynamic default — yeah, unsigned char, we love a chaotic type choice 🌈
  • XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG. your personal little pointer to stash whatever you want, NULL by default 🎀

and that's the whole XmPrimitive table, no crumbs left behind 🍓 keep going, there's more where this came from 💖

✨ Core Resource Set ✨

okay bestie, this is the inherited core stuff every widget gets — XmToggleButton didn't invent these, she just showed up and collected them like the icon she is 💅. Here's the whole roster, no skips:

  • 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's the whole set, every single one, no crumbs left behind 🫶

🌸 Callback Information 🌸

so when a callback fires, she hands you a pointer to this lil struct, and it's giving very informative:

typedef struct
{
        int reason;
        XEvent * event;
        int set;
} XmToggleButtonCallbackStruct;
  • reason — spill the tea, why did the callback even get invoked
  • event — points to the XEvent that triggered the callback, so you know what went down
  • set — reflects the ToggleButton's state, and it's one of XmSET (selected), XmUNSET (unselected), or XmINDETERMINATE (neither). and here's the gag bestie: the state reported is the state the ToggleButton is in after the event has been processed, not before. like, imagine a user clicks the ToggleButton to flip it from unselected to selected — in that case the ToggleButton changes the value of set from XmUNSET to XmSET before it ever calls the callback. so you're always seeing the post-glow version, periodt ✨

🦋 Translations 🦋

XmToggleButton comes with translations inherited from Primitive, because of course she does 💅. on top of that, there are extra XmToggleButton translations for buttons that are not in a menu system — those get listed below.

⚠️ real talk though: altering translations in #override or #augment mode is undefined. do not do it. no cap. undefined means undefined and she will not be held responsible for the chaos 🙈

Okay so these key names? They're written in the X standard key event translation table syntax — which is literally the exact format Motif uses to say "this key → these widget actions". You get a lil overview of the format over in VirtualBindings(3), and if you want the whole thing, the X Toolkit Instrinsics Documentation is your girl. 💅

c<Btn1Down>:
          ButtonTakeFocus()

∼c<Btn1Down>:
          Arm()

∼c<Btn1Up>:
          Select() Disarm()

<Btn2Down>:
          ProcessDrag()

:<Key><osfActivate>:
          PrimitiveParentActivate()

:<Key><osfCancel>:
          PrimitiveParentCancel()

:<Key><osfSelect>:
          ArmAndActivate()

:<Key><osfHelp>:
          Help()

∼s ∼m ∼a <Key>Return:
          PrimitiveParentActivate()

∼s ∼m ∼a <Key>space:
          ArmAndActivate()

XmToggleButton also inherits its menu traversal translations from XmLabel, bestie, no cap. And there's a whole extra batch of XmToggleButton translations for ToggleButtons that live in a menu system — they're listed right here. Oh and heads up: in a Popup menu system, <Btn3> does the <Btn1> actions too. Slay. ✨

<Btn2Down>:
          ProcessDrag()

c<Btn1Down>:
          MenuButtonTakeFocus()

c<Btn1Up>:
          MenuButtonTakeFocusUp()

∼c<BtnDown>:
          BtnDown()

∼c<BtnUp>:
          BtnUp()

:<Key><osfSelect>:
          ArmAndActivate()

:<Key><osfActivate>:
          ArmAndActivate()

:<Key><osfHelp>:
          Help()

:<Key><osfCancel>:
          MenuEscape()

∼s ∼m ∼a <Key>Return:
          ArmAndActivate()

∼s ∼m ∼a <Key>space:
          ArmAndActivate()

🎬 Action Routines 🎬

The XmToggleButton action routines are, in no particular order because they're already alphabetical and I'm not gonna mess with that:

  • Arm() — If the button was previously unset, this action does the following: if XmNindicatorOn is True, it draws the indicator shadow so that the indicator looks pressed; if XmNfillOnSelect is True, it fills the indicator with the color specified by XmNselectColor. If XmNindicatorOn is False, it draws the button shadow so that the button looks pressed. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNselectPixmap is used as the button face. This action calls the XmNarmCallback callbacks.

And if the button was previously set, this action does the following: if both XmNindicatorOn and XmNvisibleWhenOff are True, it draws the indicator shadow so that the indicator looks raised; if XmNfillOnSelect is True, it fills the indicator with the background color. If XmNindicatorOn is False, it draws the button shadow so that the button looks raised. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNlabelPixmap is used as the button face. This action calls the XmNarmCallback callbacks.

  • ArmAndActivate() — If the ToggleButton was previously set, unsets it; if the ToggleButton was previously unset, sets it. Iconic little toggle moment, honestly.

In a menu, this action unposts all menus in the menu hierarchy. Unless the button is already armed, it calls the XmNarmCallback callbacks. This action calls the XmNvalueChangedCallback and XmNdisarmCallback callbacks.

Outside a menu, if the button was previously unset, this action does the following: if XmNindicatorOn is True, it draws the indicator shadow so that the indicator looks pressed; if XmNfillOnSelect is True, it fills the indicator with the color specified by XmNselectColor. If XmNindicatorOn is False, it draws the button shadow so that the button looks pressed. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNselectPixmap is used as the button face. This action calls the XmNarmCallback, XmNvalueChangedCallback, and XmNdisarmCallback callbacks.

Outside a menu, if the button was previously set, this action does the following: if both XmNindicatorOn and XmNvisibleWhenOff are True, it draws the indicator shadow so that the indicator looks raised; if XmNfillOnSelect is True, it fills the indicator with the background color. If XmNindicatorOn is False, it draws the button shadow so that the button looks raised. If XmNlabelType is XmPIXMAP or XmPIXMAP_AND_STRING, the XmNlabelPixmap is used as the button face. This action calls the XmNarmCallback, XmNvalueChangedCallback, and XmNdisarmCallback callbacks.

  • BtnDown() — This action unposts any menus posted by the ToggleButton's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state and, unless the button is already armed, calls the XmNarmCallback callbacks.
  • BtnUp() — This action unposts all menus in the menu hierarchy. If the ToggleButton was previously set, unsets it; if the ToggleButton was previously unset, sets it. It calls the XmNvalueChangedCallback callbacks and then the XmNdisarmCallback callbacks.
  • ButtonTakeFocus() — Causes the ToggleButton to take keyboard focus when Ctrl<Btn1Down> is pressed, without activating the widget. Just a lil focus grab, no commitment. 🫶
  • Disarm() — Calls the callbacks for XmNdisarmCallback.
  • Help() — 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. 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.
  • MenuShellPopdownOne() — 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.

  • ProcessDrag() — Drags the contents of a ToggleButton label, identified when BTransfer is pressed. This action sets the XmNconvertProc of the DragContext to a function that calls the XmNconvertCallback procedures, possibly multiple times, for the _MOTIF_DROP selection. This action is undefined for ToggleButtons used in a menu system. 💀 So like, don't.
  • Select() — If the pointer is within the button, takes the following actions: If the button was previously unset, sets it; if the button was previously set, unsets it. This action calls the XmNvalueChangedCallback callbacks.

🌸 Additional Behavior 🌸

This widget has the following additional behavior, and it's giving main character energy:

  • <EnterWindow> — 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 ToggleButton is not in a menu and the cursor leaves and then reenters the ToggleButton's window while the button is pressed, this action restores the button's armed appearance.

  • <LeaveWindow> — 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 ToggleButton is not in a menu and the cursor leaves the ToggleButton's window while the button is pressed, this action restores the button's unarmed appearance.

🦋 Virtual Bindings 🦋

Okay so the bindings for virtual keys are vendor specific — meaning every vendor does their own lil thing and we can't promise you anything. For information about bindings for virtual buttons and keys, go see VirtualBindings(3). iykyk. ✨

Your reading list, bestie, go click around:

and that's the whole page, periodt 💖 This one lives in the XmToggleButton(library call) section — a library call page, your classic Motif reference-manual situation. Go forth and toggle, gorgeous. 🎀🦋💅

📦 where this page comes from