XMICONGADGET(3)

💖 XmIconGadget — the IconGadget widget class 💖

okay so bestie, you're reading the manual page for XmIconGadget, and it lives in the library-call corner of the Motif docs. This is part 1 of 4, so don't you dare think we're done — we are so not done. Sit down, grab a snack 🍓, and let's get into it.

---

✨ NAME ✨

XmIconGadget — the IconGadget widget class 👑

---

🫶 SYNOPSIS 🫶

#include <Xm/IconG.h>

that's it. that's the whole include. slay. 💅

---

🌸 DESCRIPTION 🌸

IconGadget is an instantiable widget whose whole personality is displaying text and a pixmap together in various combinations. It's giving versatility. Other widgets that hold the XmQTcontainer trait — like Container, hi bestie — can use IconGadget to represent objects.

IconGadget text is a compound string. If you don't supply any text, then the compound string gets generated from the gadget name instead. No text? no problem, it just makes one for you. And IconGadget text is placed relative to the type of associated pixmap.

Depending on the XmNviewType resource, IconGadget can display two views:

• XmLARGE_ICON — the IconGadget text string is displayed below the pixmap, and centered. main character placement fr.
• XmSMALL_ICON — the IconGadget text string is placed on the side of the small icon, in the widget's XmNlayoutDirection.

A bitmap mask can be supplied for each pixmap to clip the pixmap into some shape other than a rectangle. The XmNlargeIconMask and XmNsmallIconMask resources specify the large and small bitmap masks respectively. Visual emphasis for the IconGadget is provided with the XmNvisualEmphasis resource. IconGadget's XmNdetail and XmNdetailCount resources provide a detail view for IconGadgets, enabling the display of Strings alongside the IconGadget. The exact layout ordering of the strings depends on the associated containing widget — so like, ask them, not us. 🙈

IconGadget uses the XmQTcontainer and XmQTspecifyRenderTable traits, and holds the XmQTcareParentVisual and XmQTcontainerItem traits.

---

🎀 Classes 🎀

IconGadget inherits behaviour, resources, and traits from the Object, RectObject, and XmGadget classes. Family tree moment. 🌳

• The class pointer is xmIconGadgetClass.
• The class name is XmIconGadget.

---

🧾 New Resources ✨

The following 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.

💡 pro tip for your .Xdefaults file: to reference a resource by name or by class, 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). iykyk.

The codes in the access column mean: C = can be set at creation time, S = set by using XtSetValues, G = retrieved by using XtGetValues, N/A = not applicable.

Here's the whole XmIconGadget resource set, no cap, every single one of them:

• Xmalignment — class XmCAlignment, type unsigned char, default XmALIGNMENT_CENTER, access CSG
• XmNdetail — class XmCDetail, type XmStringTable, default NULL, access CSG
• XmNdetailCount — class XmCDetailCount, type Cardinal, default 0, access CSG
• XmNfontList — class XmCFontList, type XmFontList, default NULL, access CSG
• XmNlabelString — class XmCXmString, type XmString, default dynamic, access CSG
• XmNlargeIconMask — class XmCIconMask, type Pixmap, default dynamic, access CSG
• XmNlargeIconPixmap — class XmCIconPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
• XmNmarginHeight — class XmCMarginHeight, type Dimension, default 2, access CSG
• XmNmarginWidth — class XmCMarginWidth, type Dimension, default 2, access CSG
• XmNrenderTable — class XmCRenderTable, type XmRenderTable, default dynamic, access CSG
• XmNsmallIconMask — class XmCIconMask, type Pixmap, default dynamic, access CSG
• XmNsmallIconPixmap — class XmCIconPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
• XmNviewType — class XmCViewType, type unsigned char, default XmLARGE_ICON, access CSG
• XmNvisualEmphasis — class XmCVisualEmphasis, type unsigned char, default XmNOT_SELECTED, access CSG
• XmNspacing — class XmCSpacing, type Dimension, default 4, access CSG

---

💅 and here's what each one actually does 💅

• XmNalignment — specifies the horizontal alignment of the pixmap with respect to the label when the icon is in LARGE_ICON view. Valid values are XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER, and XmALIGNMENT_END.
• XmNdetail — specifies an array of XmStrings that are the detail information associated with the gadget.
• XmNdetailCount — specifies the size of the XmNdetail array.
• XmNfontList — specifies the font list associated with XmIconGadget. Heads up bestie, the font list is an obsolete construct — it's been superseded by the render table. It's only here for compatibility with earlier versions of Motif, and for applications that don't easily support render tables. The default font list is derived from the default render table, and if you specify both a font list and a render table, the render table takes precedence. periodt.
• XmNlabelString — specifies the compound string. If this value is NULL, it is initialized by converting the name of the gadget to a compound string. Refer to XmString(3) for more info on the creation and structure of compound strings. 🦋
• XmNlargeIconMask — specifies the icon mask used when XmNviewType is XmLARGE_ICON.
• XmNlargeIconPixmap — specifies the pixmap when XmNviewType is XmLARGE_ICON. If this resource's value is XmUNSPECIFIED_PIXMAP, there is no pixmap. And if a large icon pixmap is specified, and if during conversion an associated mask can be fetched, then the XmNlargeIconMask resource is set to that mask. sneaky little auto-assign, iconic.
• XmNmarginHeight — specifies the amount of vertical space between the highlight and the inside (pixmap and label).
• XmNmarginWidth — specifies the amount of horizontal space between the highlight and the inside (pixmap and label).

---

• XmNrenderTable — okay so this one is the whole XmRenderTable vibe for the text used in the gadget. If XmNrenderTable is NULL when the IconGadget is created, the parent's render table resource value is used if there is a render table. If the parent does not have a render table, the parent hierarchy of the widget is searched for a widget that holds the XmQTspecifyRenderTable trait. If such an ancestor is found, the render table is initialized to the XmLABEL_RENDER_TABLE value of the ancestor widget. If no such widget is found, the default is implementation dependent. Refer to XmRenderTable(3) for more information on the creation and structure of a XmRenderTable. If both a render table and a font list are specified, the render table will take precedence. periodt 💅
• XmNsmallIconMask — bestie, this specifies the icon mask used when XmNviewType is XmSMALL_ICON. ✨
• XmNsmallIconPixmap — specifies the pixmap when XmNviewType is XmSMALL_ICON. If this resource's value is XmUNSPECIFIED_PIXMAP, there is no pixmap. If a small icon pixmap is specified, and if during conversion an associated mask can be fetched, then the XmNsmallIconMask resource is set to that mask. iykyk 🦋
• XmNspacing — this is the amount of space between the pixmap and the label parts of the icon. 🌸
• XmNviewType — specifies the view (combination of pixmaps/text) that will be displayed. If the IconGadget is a child of a Container widget, however, then the specification of this resource will be taken from the Container— if Container's XmNentryViewType is either XmLARGE_ICON or XmSMALL_ICON, then IconGadget's XmNviewType takes that value; otherwise, the default is XmLARGE_ICON. This resource is set to one of the following:
  • XmLARGE_ICON — the pixmap specified by XmNlargeIconPixmap is displayed with the XmNlabelString beneath it. 👑
  • XmSMALL_ICON — the pixmap specified by XmNsmallIconPixmap is displayed with the XmNlabelString displayed in the direction of the XmNlayoutDirection resource. 🌈
• XmNvisualEmphasis — specifies the visual state of the IconGadget. If the IconGadget is in a selected state all visuals are displayed using the Container XmNselectColor resource. It is set to one of the following:
  • XmSELECTED — the IconGadget is in the selected state and displays the appropriate visuals. 💚
  • XmNOT_SELECTED — the IconGadget is not in the selected state. 💀

✨ Inherited Resources ✨

okay so listen 💖 IconGadget doesn't just come up with its whole personality on its own — it inherits behavior and resources from its superclasses, and they're all laid out in the tables below. For the full tea on any single resource, go read the reference page for that superclass, bestie, because it's giving details.

The access codes in that last column are listed exactly as they come, no cap — I'm not out here guessing what each letter means, the superclass pages spill that themselves 💅

---

🎀 XmGadget Resource Set 🎀

This is the whole glow-up your gadget gets handed down from XmGadget:

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

---

🦋 RectObj Resource Set 🦋

and then RectObj rolls up with its own lil' set, the geometry-flavored lore:

• 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

---

and yes, dynamic showing up everywhere means the default isn't just one fixed number sitting there — it's vibing, it gets worked out for you 🌈 and XmNborderWidth straight up has access N/A, so that's a whole situation, we don't touch it 💀

still more coming, don't go anywhere 🫶

• XmNdestroyCallback — class XmCCallback, type XtCallbackList, default NULL, access C 💖 (this one's the last row of the Object Resource Set table bestie, and it's the callback that fires when your gadget gets destroyed — iconic little goodbye moment ✨)

---

🌸 Additional Behavior 🌸

okay so real talk: IconGadget has no behavior. that's it. that's the whole thing. no behaviors. zero. none. she just sits there being a gadget 💅

---

🦋 Virtual Bindings 🦋

the bindings for virtual keys are vendor specific — meaning it's giving "ask your vendor, not me" energy fr fr 😭

for the tea on bindings for virtual buttons and keys, go read VirtualBindings(3) 👑

---

💀 Errors/Warnings 💀

the toolkit will display a warning if you give it an incorrect value for an enumeration resource 🚨

so like… don't do that. or do, and get warned. your choice bestie 🫶

---

🌈 RELATED 🌈

the whole friend group, no cap:

• Core(3)
• XmContainer(3)
• XmCreateIconGadget(3)
• XmGadget(3)
• XmVaCreateIconGadget(3)
• XmVaCreateManagedIconGadget(3)

---

and that's a wrap on the whole page, bestie!! 🎀 this one came to you from XmIconGadget(library call) — go forth and gadget responsibly, you absolute icon 👑✨💖