XMDISPLAY(3)

📦
version 2.5.2 · 3 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💅 XmDisplay — from the library call manual 💅

okay so bestie, buckle up, because we're talking about XmDisplay, the Display widget class, and honestly? it's kind of the main character of your whole Motif app. let's get into it 🫶

✨ NAME ✨

XmDisplay — literally the Display widget class. that's it, that's the name, slay.

🎀 SYNOPSIS 🎀

#include <Xm/Display.h>

yes bestie, that's the whole synopsis. we love a low-effort icon 💅

🌸 DESCRIPTION 🌸

so here's the vibe: the XmDisplay object is what all the Motif widgets use to stash information that's specific to a display. it also lets the toolkit peek at certain info about widget hierarchies that would otherwise be, like, completely unavailable to it. and every client gets one XmDisplay object for each display it accesses — one per display, no sharing, no cap 🦋

here's the part that's giving convenience: an XmDisplay object gets created automatically when the application creates the first shell on a display. (usually that happens through a call to XtAppInitialize or XtAppCreateShell.) so like — do not go off and try to create an XmDisplay object by any other means. it's not necessary, bestie, please don't. instead, if an app wants the widget ID of the XmDisplay object for a given display, it can just call the function XmGetXmDisplay. easy 💖

and now the annoying-but-important bit: an application cannot supply initial values for XmDisplay resources as arguments to any function that creates widgets. nope. not happening. what the application or the user can do is supply initial values in a resource file. then, after creating the first shell on the display, the application can use XmGetXmDisplay to grab the widget ID of the XmDisplay object and then call XtSetValues to set the XmDisplay resources. that's the whole workflow, periodt ✨

now, the juicy part — drag and drop 🐉. XmDisplay resources specify the drag protocol style for a client that's participating in drag and drop transactions. there are two basic protocol types: preregister and dynamic.

🔥 the two protocol types 🔥

  • preregister — when a preregister protocol is used, the toolkit handles any communication between the initiator and receiver clients, and it displays the appropriate drag-over and drag-under visual effects. a client registers its drop sites in advance, and that information gets stored in a property for each top-level window. then when the drag pointer enters a top-level window, the initiator reads the drop site information. very "we planned ahead, we're organized" energy 👑
  • dynamic — a dynamic protocol lets the source and destination clients dynamically communicate drag and drop state information between each other, and update their respective visuals accordingly. the toolkit provides drop site information as the pointer passes over any given drop site. and in this mode? a receiver can supply a procedure to generate its own drag-under effects. very DIY, very customizable, we love to see it 💅

🦋 Classes 🦋

Display inherits behavior and resources from Core, Composite, Shell, WMShell, VendorShell, TopLevelShell, and ApplicationShell classes. it's giving nepo baby but make it inheritance hierarchy, honestly 😭

  • the class pointer is xmDisplayClass.
  • the class name is XmDisplay.

🎀 New Resources 🎀

okay so this next bit is the resource table (coming at you next), but first the important context, bestie ✨

the following table defines a set of widget resources that the programmer uses to specify data. and — key detail — the programmer can also set the resource values for the inherited classes to set attributes for this widget. inheritance! it's everywhere! 💖

now, referencing them in a .Xdefaults file, because iykyk:

  • 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 — your call — but include any underscores between words). 🫶

and the access column codes in the table? they tell you whether 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

that's the legend, bestie, memorize it. the table itself is up next 🌈

Okay so before we get into the individual resources, here's the whole XmDisplay resource set laid out for you, bestie — name, class, type, default, and access, all of it, nothing skipped 💖

  • XmNdefaultButtonEmphasis — class XmCDefaultButtonEmphasis, type XtEnum, default XmEXTERNAL_HIGHLIGHT, access C
  • XmNdefaultVirtualBindings — class XmCDefaultVirtualBindings, type String, default dynamic, access C
  • XmNdragInitiatorProtocolStyle — class XmCDragInitiatorProtocolStyle, type unsigned char, default XmDRAG_PREFER_RECEIVER, access CG
  • XmNdragReceiverProtocolStyle — class XmCDragReceiverProtocolStyle, type unsigned char, default XmDRAG_PREFER_DYNAMIC, access CG
  • XmNdragStartCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNenableBtn1Transfer — class XmCEnableBtn1Transfer, type XtEnum, default XmOFF, access C
  • XmNenableButtonTab — class XmCEnableButtonTab, type Boolean, default False, access C
  • XmNenableDragIcon — class XmCEnableDragIcon, type Boolean, default False, access C
  • XmNenableEtchedInMenu — class XmCEnableEtchedInMenu, type Boolean, default False, access C
  • XmNenableToggleColor — class XmCEnableToggleColor, type Boolean, default False, access C
  • XmNenableToggleVisual — class XmCEnableToggleVisual, type Boolean, default False, access C
  • XmNenableUnselectableDrag — class XmCEnableUnselectableDrag, type Boolean, default True, access C
  • XmNenableWarp — class XmCEnableWarp, type XtEnum, default True, access CSG
  • XmNmotifVersion — class XmCMotifVersion, type int, default XmVERSION, access CSG
  • XmNnoFontCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNnoRenditionCallback — class XmCCallback, type XtCallbackList, default NULL, access C
  • XmNuserData — class XmCUserData, type XtPointer, default NULL, access CSG

🦋 The resources, one by one 🦋

🌸 XmNdefaultButtonEmphasis

This one's the glow-up switch for your PushButton widgets and gadgets that have XmNshowAsDefault set — it decides whether their whole look gets changed up or not ✨

So when the PushButton is the default, it gets an etched-out button that's, like, enclosed inside another etched-in border. Cute, but where does the location cursor go?? That's the whole question this resource answers. XmNdefaultButtonEmphasis has these possible values, and yeah, they affect the location cursor:

  • XmINTERNAL_HIGHLIGHT — the location cursor shows up in between the two etched borders, which keeps the space it needs as smol as possible 🎀
  • XmEXTERNAL_HIGHLIGHT — the PushButton draws the location cursor outside the second border instead.

🧚 XmNdefaultVirtualBindings

This is where you tell the display what its default virtual bindings are, bestie. And here's a whole actual example of how you'd spec the defaultVirtualBindings resource in a resource file — copy it exactly, no freestyling:

*defaultVirtualBindings: \
        osfBackSpace:       <Key>BackSpace       \n\
        osfInsert:       <Key>InsertChar      \n\
        osfDelete:       <Key>DeleteChar      \n\
        ...
        osfLeft:       <Key>left, Ctrl<Key>H
Not me pointing out the ... in there — yes, it's literally in the spec. Your resource file needs the rest of the bindings, the example just trails off 🙈

🔥 XmNdragInitiatorProtocolStyle

Real talk: this one says what drag-and-drop protocol this client requires or prefers when it's the initiator. The possible values are:

  • XmDRAG_PREREGISTER — as an initiator, this client doesn't do the dynamic protocol at all, so it can only arrange visual effects with receivers that hand over preregistered information 👑
  • XmDRAG_DYNAMIC — as an initiator, this client straight-up doesn't use any of the preregistered drop site info that other clients make available, so it can only arrange visual effects with receivers that are on the dynamic protocol 💅
  • XmDRAG_NONE — drag and drop is disabled for this client. That’s the whole vibe, bestie. 💅
  • XmDRAG_DROP_ONLY — as an initiator, this client does not use either the preregistered drop site information or the dynamic protocol. It supports dragging, and any time the cursor is over a client that supports drag and drop, valid feedback is provided. There are no other visual effects. Ngl, it’s giving “just the basics.” ✨
  • XmDRAG_PREFER_DYNAMIC — as an initiator, this client can support both the preregister and dynamic protocols, but prefers to use dynamic protocols whenever possible in order to provide high-quality drag-under feedback. Highkey the drama is worth it for the feedback. 🦋
  • XmDRAG_PREFER_PREREGISTER — as an initiator, this client can support both the preregister and dynamic protocols, but prefers to use the preregister protocol whenever possible in order to accommodate performance needs or to provide consistent drag-over feedback. Performance queen behavior. 👑
  • XmDRAG_PREFER_RECEIVER — indicates that this client can support both preregister and dynamic protocols, but will defer to the preference of the receiver client. This value is valid only for the XmNdragInitiatorProtocolStyle resource, and is its default value. It’s literally the “you pick, bestie” option. 🫶

XmNdragReceiverProtocolStyle

Specifies the drag and drop protocol requirements or preference when this client is a receiver. The values are:

  • XmDRAG_PREREGISTER — as a receiver, this client preregisters drop site information and does not use the dynamic protocol. It can only arrange visual effects with initiators who make use of the preregistered information. Preregister girlies, stand up. 🎀
  • XmDRAG_DYNAMIC — as a receiver, this client uses the dynamic protocol and does not preregister drop site information. It can only arrange visual effects with initiators who use the dynamic protocol. Dynamic only, no cap. 💅
  • XmDRAG_NONE — drag and drop is disabled for this client. Same energy as above: not today. 💀
  • XmDRAG_DROP_ONLY — as a receiver, this client neither uses the dynamic protocol nor preregisters drop site information. It supports dropping, and when dragging over this client, valid feedback is always provided, but there are no other visual effects. Drop-only icon behavior. 🍓
  • XmDRAG_PREFER_DYNAMIC — as a receiver, this client can support both the preregister and dynamic protocols, but prefers to use the dynamic protocol whenever possible in order to provide high-quality drag-under feedback. Obsessed with the quality. ✨
  • XmDRAG_PREFER_PREREGISTER — as a receiver, this client can support both the preregister and dynamic protocols, but prefers to use the preregister protocol whenever possible in order to accommodate performance needs. Performance needs stay winning. 🔥

The default value of this resource is dependent on the capabilities of the display. If the display supports the shape extension, allowing the dynamic protocol to use arbitrarily sized drag cursors, the default of this resource is XmDRAG_PREFER_DYNAMIC; otherwise the default is XmDRAG_PREFER_PREREGISTER. Vibe check says: shape extension = dynamic default. 🌈

The actual protocol used between an initiator and a receiver is based on the protocol style of the receiver and initiator. The decision matrix is described in the following table in the original page, with the columns Drag Initiator and Drag Receiver Protocol Style. (Yes, it’s a lookup table; read it across and down, iykyk.) The value XmDRAG_NONE does not appear in the matrix. When specified for either the initiator or receiver side, XmDRAG_NONE implies that drag and drop transactions are not supported. A value of XmDRAG_DROP_ONLY (Drop Only) results when an initiator and receiver cannot compromise protocol styles, that is, one client requires dynamic mode while the other can only support preregister mode, or if either explicitly has specified XmDRAG_DROP_ONLY. That’s the whole tea. ☕

XmNdragStartCallback

Specifies the list of callbacks that are invoked when the XmDragStart function is called. The type of structure whose address is passed to this callback is XmDragStartCallbackStruct. The callback reason is XmCR_DRAG_START. Slay. 🎀

XmNenableBtn1Transfer

Specifies if selection and transfer actions are integrated on Btn1 and extend actions are activated on Btn2. This resource can take the following values:

  • XmOFF — disables integration and selection activation on Btn1. It’s giving “nope, not integrated.” 🙈
  • XmBUTTON2_TRANSFER — enables integration and selection activation on Btn1 and transfer on Btn2. Button 2 gets the transfer job. 🦋
  • XmBUTTON2_ADJUST — enables integration and selection activation on Btn1 and adjust on Btn2. Button 2 gets the adjust job. 💅

This resource affects the actions of Text, TextField, List, and Container. Those four are literally the main characters here. 👑

XmNenableButtonTab

Specifies if the action for the Tab key (KNextField and KPrevField actions) is to be modified. A value of True modifies the key to move as an arrow key until the boundary of a tab group is reached. Then, at the boundary of the tab group, KNextField and KPrevField will move to the next or previous tab group, respectively. A value of False does not cause modification. So it’s either tab-group parkour or no parkour. 🧚

XmNenableDragIcon

Specifies which set of icons are to be used for system default cursors during drag and drop operations. A value of False specifies that earlier versions of Motif release icons are used; a value of True specifies that alternate icons are used. This resource affects both the 16x16 and the 32x32 icons that the system defaults for each of the Screen objects associated with this display. Icon glow-up, your choice. ✨

XmNenableEtchedInMenu

Specifies the shadowing of the button widgets and gadgets in menus when the control is activated. A value of True causes the selected menu to be drawn with the shadow etched in; this shadow style is consistent with the selected appearance of other button widgets outside of menus. A value of False causes the selected menu to be drawn with the shadow etched out. This resource affects the actions of PushButton, ToggleButton, and CascadeButton widgets and gadgets when they are children of Menu. Etched-in is the inside-glow of menu buttons, basically. 💅

When this resource is set, the background of a button in a menu uses the XmNselectColor (derived from the XmNselectPixel) when armed as a default. A PushButton uses the XmNarmColor if it is defined. A ToggleButton uses the XmNselectColor if XmNindicatorOn is False and XmNfillOnSelect is True. This is the exact recipe, don’t improvise. 🎀

XmNenableToggleColor

Specifies how to determine the default value of the XmNselectColor resource of ToggleButton and ToggleButtonGadget. A value of True causes the default value of XmNselectColor to be set to the value of XmNhighlightColor. A value of False causes the default value of XmNselectColor to be set to the value of XmNbackground. This resource only affects the appearance of ToggleButton widgets and gadgets that are in XmONE_OF_MANY or XmONE_OF_MANY_ROUND mode. In addition, XmNenableToggleColor only influences the default value of XmNselectColor. That is, if the user or application sets a value for XmNselectColor, then XmNenableToggleColor is ignored. So it’s a default-setter, not a fighter. 🙈

XmNenableToggleVisual

Specifies the visual appearance of the ToggleButton widget and/or gadget. This resource affects the default value of the ToggleButton[Gadget] XmNindicatorType and XmNindicatorOn resources. When the ToggleButton is in a RadioBox, a value of True causes the XmONE_OF_MANY_ROUND (a shadowed circle) to be the default. Otherwise, when this resource is True, the ToggleButton XmNindicatorOn resource causes a default of XmN_OF_MANY, which will be a shadowed square with a check mark (check box). Visual queen behavior. 👑

A value of False causes the following:

  • XmONE_OF_MANY — is a shadowed diamond. 💎
  • XmN_OF_MANY — is a shadowed square. 🎀
  • XmNenableUnselectableDrag — tells the app whether you're allowed to drag stuff off of a Label and a Scale. Set it to True and dragging is on 💅, set it to False and it's a hard no 🙅‍♀️.
  • XmNenableWarp — controls whether an application is allowed to warp the pointer out from under the user. True = yes warping, False = no warping, hands off the mouse bestie 🖱️✨.
  • XmNmotifVersion — the version of Motif that the current implementation is supposed to behave like. By default this resource gets its value from release values in Xm.h 📚.
  • XmNnoFontCallback — this callback fires whenever a rendition tries to load a font or fontset and fails 😭. It can happen at creation time if the font is specified as XmLOAD_IMMEDIATE, or when something tries to render an XmString using a font specified as XmLOAD_DEFERRED. An application can use this callback to try to fix the whole situation by calling XmRenditionUpdate on the input rendition and handing the widget a font to use 🫶. You can do that either by providing an alternative font name to be loaded via the XmNfontName and XmNfontType resources, or with an already loaded font via the XmNfont resource. The callback reason is XmCR_NO_FONT, and this callback uses the XmDisplayCallbackStruct structure.
  • XmNnoRenditionCallback — this callback fires whenever something tries to render a segment with a RENDITION tag that doesn't match any renditions in a given render table 😬. The callback reason is XmCR_NO_RENDITION, and this callback uses the XmDisplayCallbackStruct structure.

An application can have this callback try to fix the problem by creating a new rendition with the given tag and adding it to render_table ✨.

The XmNnoRenditionCallback should deallocate the render table passed in in the render_table field of the callback structure. Note that the table will automatically be deallocated if the XmRenderTableAddRenditions function is called on it. The callback should NOT deallocate the modified render table that is passed back to Motif in the render_table field. If the application wants to manipulate this render table further, it should make a copy with the XmRenderTableCopy function before returning from the callback. Read that twice bestie, this is the part that bites people 💀
  • XmNuserData — a client data pointer for applications. An internally unused resource 🙈.

🦋 Inherited Resources 🦋

All of the superclass resources inherited by XmDisplay are designated N/A (not applicable). Like, all of them. Nothing to see here, moving on 💅

🎀 Callback Information 🎀

A pointer to the following structure is passed to the XmNdragStartCallback callback:

typedef struct
{
        int reason;
        XEvent  *event;
        Widget timeStamp;
        Boolean doit;
}XmDragStartCallbackStruct;
  • reason — indicates why the callback was invoked
  • event — points to the XEvent that triggered the callback
  • widget — indicates the ID of the widget from which the drag was initiated
  • doit — is an IN/OUT member that lets the callback decide whether to continue with the drag or cancel it. Setting doit to False will cancel the drag. The default value is NULL.

(yes, the struct member is literally spelled timeStamp while the description calls it widget — not me, that's just how the page is, iykyk 😭)

A pointer to the following structure is passed to the XmNnoFontCallback and XmNnoRenditionCallback callbacks:

typedef struct
{
        int reason;
        XEvent *event;
        XmRendition rendition;
        char *font_name;
        XmRenderTable render_table;
        XmStringTag tag;
}XmDisplayCallbackStruct;
  • reason — indicates why the callback was invoked
  • event — points to the XEvent that triggered the callback. It can be NULL.
  • rendition — specifies the rendition with the missing font
  • font_name — specifies the name of the font or font set which could not be loaded
  • render_table — specifies the render table with the missing rendition
  • tag — specifies the tag of the missing rendition

So which fields actually mean anything? Depends on the reason, bestie — here's the tea ☕:

  • Reason XmCR_NO_FONT → the valid fields are rendition and font_name
  • Reason XmCR_NO_RENDITION → the valid fields are render_table and tag

Go read these next, they're all lowkey part of the same universe 👑

That's the whole page, you made it to the end 🎉🫶💖 This one's the XmDisplay(library call) page from the Motif library docs — go drink some water and go call XmGetXmDisplay on something, you absolute icon ✨👑💅

📦 where this page comes from