XMCASCADEBUTTON(3)

💖 XmCascadeButton 💖 — the CascadeButton widget class

okay bestie, gather round, because this is the XmCascadeButton(library call) page and she is iconic 💅. This is the widget class doc, and yes it's a long one, so we're doing it in parts. Part 1 starts now 🫶

---

✨ SYNOPSIS ✨

#include <Xm/CascadeB.h>

---

🌸 DESCRIPTION 🌸

So what is a CascadeButton? Bestie, it links two menu panes together, or links a MenuBar to a menu pane. That's her whole job and she does it flawlessly ✨.

She lives in menu systems, and the way that she must have a RowColumn parent with its XmNrowColumnType resource set to XmMENU_BAR, XmMENU_POPUP or XmMENU_PULLDOWN — no cap, that's non-negotiable.

She is the only widget that can have a Pulldown menu pane attached to it as a submenu 👑. That submenu pops up when this widget is activated inside a MenuBar, a PopupMenu, or a PulldownMenu. Her visuals? Depends where she's at:

• when she's in a Popup or Pulldown menu pane, she can show a label or pixmap and a cascading indicator
• when she's in a MenuBar, she can show only a label or a pixmap

Where the PulldownMenu sits relative to the CascadeButton is up to the XmNlayoutDirection resource of the MenuShell. Slay.

The default behavior of a CascadeButton depends on what kind of menu system she's in. By default, BSelect controls her behavior. Also, BMenu controls her behavior if she resides in a PopupMenu system. The actual mouse button used is determined by her RowColumn parent. And BMenu also performs the BSelect actions in all types of menu systems, iykyk.

Her visuals differ from most other button gadgets, and honestly it's giving main character energy. When the button becomes armed, her visuals change from a 2-D to a 3-D look, and she displays the submenu attached to her. If no submenu is attached, she just changes her visuals and that's it 💀.

Now, when a CascadeButton in a Pulldown or Popup menu pane gets armed because the user moved the mouse pointer into the widget, she does not immediately display her submenu. Instead she waits a short amount of time to see if the arming was temporary (like, the user was just passing through the widget) or whether the user really wanted the submenu posted. That time delay is configurable using XmNmappingDelay. Patient queen 🎀.

CascadeButton gives you exactly one mechanism for activating the widget from the keyboard, and it's called a keyboard mnemonic. If a mnemonic has been specified for the widget, the user can activate the CascadeButton by simply typing the mnemonic while the CascadeButton is visible. If the CascadeButton is in a MenuBar and the MenuBar does not have the focus, the MAlt modifier must be pressed along with the mnemonic. Mnemonics are typically used to interact with a menu using the keyboard interface. Periodt.

One more thing: if the CascadeButton is in a Pulldown or Popup menu pane and there is a submenu attached, the XmNmarginBottom, XmNmarginLeft, XmNmarginRight, and XmNmarginTop resources may enlarge to accommodate XmNcascadePixmap. And XmNmarginWidth defaults to 6 if this resource is in a MenuBar; otherwise, it takes Label's default, which is 2. Noted 📝.

CascadeButton uses the XmQTmenuSystem and XmQTspecifyRenderTable traits. Obsessed with her.

---

🦋 Classes 🦋

CascadeButton inherits behavior, resources, and traits from the Core, XmPrimitive, and XmLabel classes. Family tree, we love to see it 🌈.

• The class pointer is xmCascadeButtonWidgetClass.
• The class name is XmCascadeButton.

---

💅 New Resources 💅

Okay so this next bit is a set of widget resources that the programmer uses to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. Here's the vibe:

• 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 tell you whether the resource can be:

• set at creation time (C)
• set by using XtSetValues (S)
• retrieved by using XtGetValues (G)
• or is not applicable (N/A)

🌟 XmCascadeButton Resource Set 🌟

• XmNactivateCallback — Class: XmCCallback; Type: XtCallbackList; Default: NULL; Access: C
• XmNcascadePixmap — Class: XmCPixmap; Type: Pixmap; Default: dynamic; Access: CSG
• XmNcascadingCallback — Class: XmCCallback; Type: XtCallbackList; Default: NULL; Access: C
• XmNmappingDelay — Class: XmCMappingDelay; Type: int; Default: 180 ms; Access: CSG
• XmNsubMenuId — Class: XmCMenuWidget; Type: Widget; Default: NULL; Access: CSG

---

🎀 The resources, one by one 🎀

• XmNactivateCallback — Specifies the list of callbacks that is called when the user activates the CascadeButton widget and there is no submenu attached to pop up. The activation occurs when a mouse button is released or when the mnemonic associated with the widget is typed. The specific mouse button depends on information in the RowColumn parent. The reason sent by the callback is XmCR_ACTIVATE.
• XmNcascadePixmap — Specifies the cascade pixmap displayed on one end of the widget when a CascadeButton is used within a Popup or Pulldown menu pane and a submenu is attached. The Label class resources XmNmarginBottom, XmNmarginLeft, XmNmarginRight, and XmNmarginTop may be modified to ensure that room is left for the cascade pixmap. The default cascade pixmap is an arrow pointing to the side of the menu where the submenu will appear. The positioning of the cascade pixmap to either the left or the right of the widget, and the direction of the arrow, depend on the XmNlayoutDirection resource of the MenuShell.
• XmNcascadingCallback — Specifies the list of callbacks that is called just prior to the mapping of the submenu associated with CascadeButton. The reason sent by the callback is XmCR_CASCADING.
• XmNmappingDelay — Specifies the amount of time, in milliseconds, between when a CascadeButton becomes armed and when it maps its submenu. This delay is used only when the widget is within a Popup or Pulldown menu pane. The value must not be negative.

🚨 bestie listen: that value must not be negative. Do not test her on this.

• XmNsubMenuId — Specifies the widget ID for the Pulldown menu pane to be associated with this CascadeButton. The specified menu pane is displayed when the CascadeButton becomes armed. The menu pane must have been created with the appropriate parentage depending on the type of menu used. See XmCreateMenuBar(3), XmCreatePulldownMenu(3), and XmCreatePopupMenu(3) for more information on the menu systems.

---

🌈 Inherited Resources 🌈

CascadeButton 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. (The tables are coming, bestie — keep scrolling 👀)

✨ XmLabel Resource Set ✨

okay so XmCascadeButton is a whole XmLabel underneath the glitter, which means it inherits the entire XmLabel resource set. Every row here has a Name, a Class, a Type, a Default, and an Access — and I'm listing every single one, no skipping, bestie. 💖

• 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 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 0, 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 dynamic, access CSG.
• XmNmnemonic — class XmCMnemonic, type KeySym, default NULL, access CSG.
• XmNmnemonicCharSet — class XmCMnemonicCharSet, type String, default XmFONTLIST_DEFAULT_TAG, 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.

---

quick vibe check on that table: most of these are CSG access, which is the classic "set it whenever, get it whenever, and it plays nice with the rest of the resource gang" energy. 🫶 The two N/A rows up top are XmNaccelerator and XmNacceleratorText — that's literally what the Access column says, so don't come for me. And a whole bunch of the defaults say dynamic, which is Motif's way of going "it depends, babe, we'll figure it out at runtime" ✨

more coming, don't go anywhere 💅

🌸 XmPrimitive Resource Set 🌸

okay bestie, this is the whole resource roster for <pink>XmPrimitive</pink> — every name, class, type, default and access code, laid out for you 💖 so you don't have to squint at a giant table. here we go:

• 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 0, 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 dynamic, access G 💅
• XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG 🍓
• XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG 💜

---

fr fr bestie, notice how some defaults literally say dynamic instead of a fixed value? that's not me being vague, that's the actual default. and the access column is C, CSG, CG or G — keep those exactly as they are, don't go freestyling them 💀

and yes, every single one of these has its Name / Class / Type / Default / Access preserved exactly as the original table had it. no cap. 🫶

✨ Core Resource Set ✨

ok so here's the whole resource lineup for XmCascadeButton, bestie 💖 every single one, name + class + type + default + access, 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

---

💌 Callback Information

every callback gets handed a pointer to this lil struct right here, no cap:

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

• reason — spills the tea on why the callback got invoked 👀
• event — points at the XEvent that triggered the callback, OR it's NULL if this callback wasn't triggered by an XEvent at all. (not every callback is an event girlie, and that's fine 🫶)

---

🦋 Translations

XmCascadeButton comes with translations inherited from XmPrimitive, periodt. And it also picks up the menu traversal translations from XmLabel. it's giving family reunion 💅

🚨 undefined behavior alert, bestie!! altering translations in #override or #augment mode is undefined. do not do it. i am begging. 😭

ok so here's the translations tea for a CascadeButton chillin inside a MenuBar. the key names below are written in the X standard key event translation table syntax — that's the format Motif uses to say which widget actions match up with a given key. there's a lil overview of the format over in VirtualBindings(3), and if you want the full description, go read the X Toolkit Instrinsics Documentation. iykyk 📚✨

<EnterWindow>Normal:
          MenuBarEnter()

<LeaveWindow>Normal:
          MenuBarLeave()

<Btn2Down>:
          ProcessDrag()

c<BtnDown>:
          MenuButtonTakeFocusUp()

c<BtnUp>: MenuButtonTakeFocusUp()

okay so picking up right where we left off, the translation list goes:

• ∼c<BtnDown>: → MenuBarSelect() 💅
• ∼c<BtnUp>: → DoSelect() ✨
• :<Key><osfSelect>: → KeySelect() 🎀
• :<Key><osfActivate>: → KeySelect() 🦋
• :<Key><osfHelp>: → Help() 🌸
• :<Key><osfCancel>: → CleanupMenuBar() 💅
• ∼s<Key>Return: → KeySelect() 🫶
• ∼s<Key>space: → KeySelect() 😭

So this next list is the translations for a CascadeButton when it's in a PullDown or Popup MenuPane. And in a Popup menu system, <Btn3> also does the <Btn1> actions, periodt. 🔥

• <EnterWindow>: → DelayedArm() 🧚
• <LeaveWindow>: → CheckDisarm() 💜
• <Btn2Down>: → ProcessDrag() 🍓
• c<BtnDown>: → MenuButtonTakeFocus() 👑
• c<BtnUp>: → MenuButtonTakeFocusUp() 🌈
• ∼c<BtnDown>: → StartDrag() ⭐
• ∼c<BtnUp>: → DoSelect() ✨
• :<Key><osfSelect>: → KeySelect() 🎀
• :<Key><osfActivate>: → KeySelect() 🦋
• :<Key><osfHelp>: → Help() 🌸
• :<Key><osfCancel>: → CleanupMenuBar() 💅
• ∼s<Key>Return: → KeySelect() 🫶
• ∼s<Key>space: → KeySelect() 😭

---

✨ Action Routines ✨

The XmCascadeButton action routines are literally the moment. Here's every single one, no skips:

• CleanupMenuBar() — bestie, this one is the menu cleanup queen 👑. Here's the tea:
  • In a MenuBar, it disarms the CascadeButton and the menu and, when the shell's keyboard focus policy is XmEXPLICIT, restores keyboard focus to the widget that had the focus before the menu was entered.
  • In a toplevel Pulldown MenuPane from a MenuBar, it unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is XmEXPLICIT, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, it unposts the menu.
  • In a Popup MenuPane, it unposts the menu and, when the shell's keyboard focus policy is XmEXPLICIT, restores keyboard focus to the widget from which the menu was posted.
• DoSelect() — Calls the callbacks in XmNcascadingCallback, posts the submenu attached to the CascadeButton, and enables keyboard traversal within the menu. If the CascadeButton does not have a submenu attached, this action calls the callbacks in XmNactivateCallback, activates the CascadeButton, and unposts all posted menus in the cascade. slay. 💅
• Help() — Unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is XmEXPLICIT, 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. helpful icon behavior fr fr. 🙈
• KeySelect() — Calls the callbacks in XmNcascadingCallback, and posts the submenu attached to the CascadeButton if keyboard traversal is enabled in the menu. If the CascadeButton does not have a submenu attached, this action calls the callbacks in XmNactivateCallback, activates the CascadeButton, and unposts all posted menus in the cascade. keyboard girlies stay winning. ⌨️
• MenuBarSelect() — Unposts any menus posted by the parent menu. Arms both the CascadeButton and the MenuBar, posts the associated submenu, and enables mouse traversal. If the menu is already active, this event disables keyboard traversal for the menu and returns the menu to mouse traversal mode. mouse mode vs keyboard mode, the eternal vibe check. 🐭
• StartDrag() — Arms the CascadeButton, posts the associated submenu, and enables mouse traversal. If the menu is already active, this event disables keyboard traversal for the menu and returns the menu to mouse traversal mode. drag energy activated. 🔥

---

💫 Additional Behavior 💫

Posting a submenu calls the XmNcascadingCallback callbacks. This widget has the following additional behavior:

• <EnterWindow>: — If keyboard traversal is enabled, does nothing. Otherwise, in a MenuBar that is armed, unposts any MenuPanes associated with another MenuBar entry, arms the CascadeButton, and posts the associated submenu. In other menus, arms the CascadeButton and posts the associated submenu after the delay specified by XmNmappingDelay. the mapping delay is lowkey the drama timer. ⏳
• <LeaveWindow>: — If keyboard traversal is enabled does nothing. Otherwise, in a MenuBar that is armed, disarms the CascadeButton if the submenu associated with the CascadeButton is not currently posted or if there is no submenu associated with the CascadeButton. In other menus, if the pointer moves anywhere except into a submenu associated with the CascadeButton, the CascadeButton is disarmed and its submenu is unposted. leave the window, lose the arm. simple as that. 💅

---

🦋 Virtual Bindings 🦋

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3). vendor specific means it's giving "ask your distro," bestie. 🌈

---

🌈 RELATED 🌈

• Core(3)
• XmCascadeButtonHighlight(3)
• XmCreateCascadeButton(3)
• XmCreateMenuBar(3)
• XmCreatePulldownMenu(3)
• XmCreatePopupMenu(3)
• XmLabel(3)
• XmPrimitive(3)
• XmRowColumn(3)
• XmVaCreateCascadeButton(3)
• XmVaCreateManagedCascadeButton(3)

---

xoxo from the XmCascadeButton(library call) bestie 💖 that's the whole vibe, and you ate. 👑✨