XMDROPDOWN(3)

💖 XmDropDown 💖

okay bestie, welcome to XmDropDown(3) — library call energy, DropDown widget class realness, and honestly? she's a whole vibe. this is part 1 of 5 so buckle up, we're not even close to done 🎀

---

✨ NAME ✨

XmDropDown — the DropDown widget class. no cap, that's literally the whole name section. iconic of her 💅

---

✨ SYNOPSIS ✨

#include <Xm/DropDown.h>

that's it. that's the whole synopsis. one include, and you're in 🦋

---

✨ DESCRIPTION ✨

okay so picture this: the DropDown widget lets the user pick stuff out of a list of choices, and type their own little custom values into a text widget. she's versatile like that 💁♀️

but here's the space-saving slay: to conserve screen space, the list of choices is only shown when the user taps the down arrow button. then the choices can be selected from that list. lowkey genius.

• if the list widget is in Browse Select mode (which is the default, bestie) or Single Select mode, the list gets automatically removed the second the user selects an item in it. gone. poof. ✨
• when the list is in other modes, multiple items may be selected, and the list may be popped down by either:
  • another click on the arrow button,
  • a click outside the list, or
  • double-clicking an item.

now for the keyboard traversal girlies ⌨️ — the list may be popped down by selecting the arrow button or Alt - down arrow, and popped back up by typing either the osfActivate key, a carriage return, or Alt - up arrow. periodt.

in any case, when the list is removed, the item or items that were selected will be placed in the text widget separated by commas. so like, a, b, c energy 🍓

typing the escape key when the list is up cancels the list popup, restoring the DropDown widget to the state it was in before the list was popped up. it's giving "undo my curiosity" 😭

and if the text field area is non-editable? clicking anywhere in the text field — the list will also pop down. sneaky little shortcut, we love her 🙈

---

resources are available to change:

• the margin sizes,
• the location of the left edge of the popup list,
• whether or not the label is shown,
• whether the text field widget may be edited, and
• whether or not the text in the list is verified against the choices available in the list.

and by setting resources that occur in the children of the DropDown widget, you can set or dynamically change:

• the contents of the list,
• the number of items visible in the list,
• the initial value of the text field, and
• the value of the label.

💜 if a developer wishes the popup list's shell to be resizable, they should set allowShellResize to True at creation time. creation time only, bestie, don't come crying to me later.

---

🌸 Classes 🌸

XmDropDown inherits behavior, resources, and traits from Core, Composite, and XmManager classes.

• the class pointer is xmDropDownWidgetClass.
• the class name is XmDropDown.

family tree moment 👑

---

🎀 New Resources 🎀

okay so here's the table of widget resources the programmer uses to specify data. the programmer can also set the resource values for the inherited classes to set attributes for this widget. keep up 💫

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 mean:

• 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

---

💅 XmDropDown Resource Set 💅

every single one, in order, no skipping:

• XmNcustomizedCombinationBox — class XmCBoolean, type Boolean, default False, access CSG
• XmNeditable — class XmCBoolean, type Boolean, default True, access CSG
• XmNhorizontalMargin — class XmCMargin, type Dimension, default 2, access CSG
• XmNitemCount — class list, type int, default 0, access CSG
• XmNitems — class list, type XmStringTable, default NULL, access CSG
• XmNlabelString — class label, type XmString, default "label", access CSG
• XmNpopupCursor — class XmCCursor, type Cursor, default left_ptr, access CSG
• XmNpopupOffset — class MxCPopupOffset, type int, default 15, access CSG
• XmNpopupShellWidget — class XmCWidget, type Widget, default NULL, access CSG
• XmNshowLabel — class XmCBoolean, type Boolean, default True, access CSG
• XmNupdateShellCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
• XmNupdateTextCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
• XmNuseTextField — class XmCUseTextField, type Boolean, default True, access CSG
• XmNvalue — class text, type String, default "", access CSG
• XmNverify — class XmCVerify, type Boolean, default True, access CSG
• XmNverifyTextCallback — class XmCCallback, type XtCallbackList, default NULL, access CSG
• XmNverticalMargin — class XmCMargin, type Dimension, default 2, access CSG
• XmNvisibleItemCount — class XmCVisibleItemCount, type int, default 0, access CSG

that's eighteen resources and every single one of them said CSG, we stay consistent 💖

---

🌈 and that's the end of part 1! more parts incoming, don't go anywhere bestie 🫶

• XmNcustomizedCombinationBox — bestie, if you set this to True, the widget will NOT go make a popup shell and list widget for you on its own ✨. The name is literally the whole vibe: it's for when you wanna build a custom combination box that has something other than a list inside it. And if this resource is true, you must hand the DropDown widget a shell via the popupShellWidget resource, okay? Just before the shell pops up, updateShellCallback gets called. Just after the shell pops down, updateTextCallback gets called. And if verify is true, then verifyTextCallback gets called whenever the combo box needs to check the contents of the text widget against the allowable values in the custom shell. 👑
• XmNeditable — a boolean that decides whether the user is even allowed to type into the TextField widget of the DropDown widget. And listen: if this value is False, then selecting the text field will popup the combo box list instead. it's giving "no typing for you, only choosing" 💅
• XmNhorizontalMargin — this one specifies the horizontal spacing between the child widgets and the boundary of the DropDown widget. the breathing room, if you will 🌸
• XmNverticalMargin — same energy but vertical: the vertical spacing between the child widgets and the boundary of the DropDown widget.
• XmNitemCount — literally just the number of items in the popup list. that's it, that's the resource 🎀
• XmNitems — the list of all choices that will be displayed in the popup list.
• XmNlabelString — the string displayed as the label of the DropDown widget. the little name tag, iconic ✨
• XmNpopupCursor — the cursor to show the user when the DropDown's list is popped up. For your choices, go see X Window System, Robert Scheiffler et al., Appendix B. 🦋
• XmNpopupOffset — the amount of space in pixels between the left edge of the Text widget and the left edge of the list when the list is displayed. Positive values mean the text's left edge is farther to the left; negative values mean the list's edge is farther to the left. And heads up: if this is a non-custom DropDown widget, the right edge of the text and the right edge of the arrow button will always line up. no cap.
• XmNpopupShellWidget — the widget identifier for the shell that pops up when the arrow is clicked. If customizedCombinationBox is False, then this widget is automatically created by the DropDown widget. so convenient fr fr 🫶
• XmNshowLabel — a boolean that says whether or not to display the DropDown Label widget. show it or don't, your call bestie 💖
• XmNupdateShellCallback — (yes, the original just lists it right here, no separate description, we keep it 100)
• XmNupdateTextCallback — the callback routine to call when either the shell widget contents or the Text widget need to be updated to correspond with the other. The shell is updated just before it is popped up. The text is updated just after the shell is popped down. If customizedComboBox is False, then the updates are done automatically by the combo box. These routines get called to inform the application that an action has been taken, in case it would like to do any further processing. considerate king behavior 👑
• XmNuseTextField — a boolean that specifies if an XmTextField or an XmText widget should be used for the text entry portion of the DropDown widget.
• XmNvalue — the string displayed in the Text widget. simple, elegant, iconic ✨
• XmNverify — if this resource is true, the DropDown widget will verify its value against the list whenever it loses focus or the user types <Carriage Return>. If the verification fails, an XtWarning is generated with a name of XmNtextVerifyFailed. Wanna trap this message? Register an XtWarningMsgHandler. 📌

okay so this next bit matters: verification failure = XtWarning named XmNtextVerifyFailed, and to catch it you register an XtWarningMsgHandler. that's the whole vibe check. 💅

• XmNverifyTextCallback — this routine is called whenever the Text widget's contents may need to be verified against the popup shell's contents. If the customizedComboBox resource is False, then the DropDown widget has already performed the verification by the time this routine is called. so you're getting the post-verification tea ☕
• XmNvisibleItemCount — the number of items visible in the popup list at one time. the window into the list, if you will 🪟

---

🧸 Children 🧸

The DropDown is composed of many sub-widgets. Most of the information displayed to the user is set through these sub widgets. Most values passed to this widget through the argument list at creation time or via set values are passed to each of this widget's children. Get values requests must be made on a child by child basis. The children of the DropDown are listed below. The OSF/Motif documentation should be consulted for an exhaustive set of resources for each child. A partial list of the most common resources are listed here for convenience.

• XmDropDown — comboBox
  • XmLabel — label
  • XmTextField — text
  • XmArrowButton — arrow
  • OverrideShell — popupShell
  • XmScrolledWindow — listSW
    • XmScrollBar — ListvScrollBar
    • XmScrollBar — ListhScrollBar
    • XmList — list

The popup shell and its children are only created when customizedCombinationBox is False. don't forget it bestie, it's lowkey important 😭

---

👑 Inherited Resources 👑

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

🌸 XmManager Resource Set 🌸

okay bestie, deep breath, because this is the resource set every XmManager subclass inherits and we are listing every single one 💖 columns are Name, Class, Type, Default, and Access, and nobody gets skipped, not even the pixmaps 🫶

• XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default dynamic, access CSG 💅 the bottom-shadow colour, and yes it figures itself out at runtime, iconic
• XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG ✨
• XmNforeground — class XmCForeground, type Pixel, default dynamic, access CSG 🌸
• XmNhelpCallback — class XmCCallback, type XtCallbackList, default NULL, access C 🎀
• XmNhighlightColor — class XmCHighlightColor, type Pixel, default dynamic, access CSG ✨
• XmNhighlightPixmap — class XmCHighlightPixmap, type Pixmap, default dynamic, access CSG 💜
• XmNinitialFocus — class XmCInitialFocus, type Widget, default NULL, access CSG 🦋
• XmNlayoutDirection — class XmCLayoutDirection, type XmDirection, default dynamic, access CG 🌈
• XmNnavigationType — class XmCNavigationType, type XmNavigationType, default XmTAB_GROUP, access CSG 👑
• XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C 💫
• XmNshadowThickness — class XmCShadowThickness, type Dimension, default 0, access CSG — zero, fr fr, no cap 💀
• XmNstringDirection — class XmCStringDirection, type XmStringDirection, default dynamic, access CG 🧚
• XmNtopShadowColor — class XmCTopShadowColor, type Pixel, default dynamic, access CSG ⭐
• XmNtopShadowPixmap — class XmCTopShadowPixmap, type Pixmap, default dynamic, access CSG 🌟
• XmNtraversalOn — class XmCTraversalOn, type Boolean, default True, access CSG 🔥
• XmNunitType — class XmCUnitType, type unsigned char, default dynamic, access CSG 🙈
• XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG 🍓

ok and about that Access column, because it's giving cryptic: C means the resource is set at creation time, G means you can get it, and S means you can set it. So CSG = all three, no notes 💅

---

💖 Composite Resource Set 💖

okay bestie, first little crew of resources. here's the whole lineup, no skips:

• XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G 🫶 read-only, so look but don't touch.
• XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG — this is the lil' procedure that decides where new kiddos get slotted in.
• XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G — literally just how many children there are. that's it. read-only, periodt.

---

✨ Core Resource Set ✨

and now the big one, the core resource set. it's giving main character energy because literally every widget inherits these. buckle up, it's a long list and we're not skipping a single one 🌈

• XmNaccelerators — class XmCAccelerators, type XtAccelerators, default dynamic, access CSG
• XmNancestorSensitive — class XmCSensitive, type Boolean, default dynamic, access G — read-only vibes only.
• 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 — note the access is CG not CSG, she's different 💅
• 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

ngl, dynamic just means the toolkit figures that default out at runtime, bestie. it's not a fixed number, it's a whole vibe. 🦋

and yes, those access codes matter: C means you can set it at creation, S means you can set it later, G means you can get it. so CSG is the full triple threat 👑, CG is create + get only, and G alone is peek-only, no setting allowed. iykyk.

├───────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
└───────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘

okay bestie that's the end of the table, we're moving on 💅

Callback Information 💖

None of the DropDown's callback procedures have any call data currently defined for them. Like, zero. The widget passed to each of these functions is the DropDown widget.

void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)

• cbw — This is the widget identifier of the DropDown widget. (the main character widget itself ✨)
• client_data — The client data passed to this widget by the application programmer.
• unused — This value is undefined. (don't worry about it, it's giving mystery 🕵️♀️)

Geometry Management 📐

The DropDown widget lays out its children (the label, text and arrow) in a row. The amount of space they are each allocated when the DropDown is not allowed to be the exact size it desires is determined using the following rules:

1. The arrow is always given its requested size. (arrow said "I want this much" and the widget said "bet" 💯)
2. If the combo box is bigger than it wants to be all extra space is given to the text widget.
3. If the combo box is smaller than it wants to be then the text and label widgets are each sized smaller than they desire in exactly the same ratio.

For example:

If the amount of space for the label and text is 100 pixels and the label wants to be 50 pixels wide and the text would like to be 100 pixels wide then the label will get 34 pixels and the text 66.

The popup shell widget is sized such that the width of the scrolled list widget equals the width of the text widget minus the value of the "popupOffset" resource. If the popup shell resides in a customized combination box, however, it is allowed to be whatever size the child of the popup shell would like to be. (popup shell said "I'm flexible, bestie" 🌈)

RELATED 🦋

Composite(3), Core(3), XmCreateDropDown(3), XmDropDownGetArrow(3), XmDropDownGetLabel(3), XmDropDownGetList(3), XmDropDownGetText(3), XmDropDownGetValue(3), XmList(3), XmManager(3), XmTextField(3), XmVaCreateDropDown(3), and XmVaCreateManagedDropDown(3).

COPYRIGHT 🎀

Copyright (c) 1992 by Integrated Computer Solutions, Inc.

---

and that's a wrap, bestie 💖 this page is XmDropDown(library call), copyright 1992 by Integrated Computer Solutions, Inc. — slay, iconic, periodt. 🫶