XMDRAWINGAREA(3)

✨ XmDrawingArea ✨

okay so bestie, welcome to the XmDrawingArea(library call) page — literally the whole widget class, and I'm gonna walk you through every single crumb of it. grab a snack. 💅

---

🎀 NAME 🎀

XmDrawingArea — The DrawingArea widget class

---

🌸 SYNOPSIS 🌸

#include <Xm/DrawingA.h>

---

🦋 DESCRIPTION 🦋

okay so picture this: DrawingArea is an empty widget, and that's the whole point — it's a blank canvas that's easily adaptable to a variety of purposes. it does no drawing and defines no behavior except for one thing and one thing only: invoking callbacks. that's it. that's the job. 👑

those callbacks are how it notifies your application when graphics need to be drawn (that's exposure events or a widget resize) and when the widget receives input from the keyboard or mouse. 🖱️⌨️

and applications are responsible for defining appearance and behavior as needed in response to DrawingArea callbacks. so like — the widget is the empty stage, you are the whole production. main character energy, fr fr. 💖

also important: DrawingArea is a composite widget and a subclass of XmManager that supports minimal geometry management for multiple widget or gadget children.

DrawingArea uses the XmNinitialFocus resource of XmManager to define whether or not DrawingArea will receive focus when it is traversed to, even if it has traversable children. here's the breakdown, no cap:

• If XmNinitialFocus is NULL, DrawingArea receives focus only if it does not have any traversable children.
• If XmNinitialFocus is not NULL, then DrawingArea receives focus when traversed to.

in that second case, the application first needs to be able to realize that the DrawingArea will receive focus, then, as appropriate, needs to either call the XmProcessTraversal function for the desired child, or to navigate across the private DrawingArea graphics objects.

⚠️ heads up bestie — the following resources are not currently used by the DrawingArea widget: XmNshadowThickness, XmNtopShadowPixmap, XmNbottomShadowPixmap, XmNtopShadowColor, and XmNbottomShadowColor. they're just... there. chilling. not invited to the function. 💀

---

🍓 Data Transfer Behavior 🍓

DrawingArea has no widget class conversion or destination procedure.

• Subclasses and the XmNconvertCallback procedures are responsible for any conversion of selections.
• Subclasses and the XmNdestinationCallback procedures are responsible for any data transfers to the widget.

so like, it's not doing the transfer for you. you're the transfer. 🫶

---

🌈 Classes 🌈

DrawingArea inherits behavior and resources from the Core, Composite, Constraint, and XmManager classes.

• The class pointer is xmDrawingAreaWidgetClass.
• The class name is XmDrawingArea.

---

👑 New Resources 👑

the following set of widget resources is what you, the programmer, use to specify data. you can also set the resource values for the inherited classes to set attributes for this widget. and here's the .Xdefaults hack that everybody needs to know:

• 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 access codes, because the alphabet soup is real:

• 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 XmDrawingArea Resource Set, every single one, exactly as written: ✨

• XmNconvertCallback — Class: XmCCallback — Type: XtCallbackList — Default: NULL — Access: C
• XmNdestinationCallback — Class: XmCCallback — Type: XtCallbackList — Default: NULL — Access: C
• XmNexposeCallback — Class: XmCCallback — Type: XtCallbackList — Default: NULL — Access: C
• XmNinputCallback — Class: XmCCallback — Type: XtCallbackList — Default: NULL — Access: C
• XmNmarginHeight — Class: XmCMarginHeight — Type: Dimension — Default: 10 — Access: CSG
• XmNmarginWidth — Class: XmCMarginWidth — Type: Dimension — Default: 10 — Access: CSG
• XmNresizeCallback — Class: XmCCallback — Type: XtCallbackList — Default: NULL — Access: C
• XmNresizePolicy — Class: XmCResizePolicy — Type: unsigned char — Default: XmRESIZE_ANY — Access: CSG

and now the tea on each one, one by one, no skipping: 💅

• XmNconvertCallback — specifies a list of callbacks called when the DrawingArea is asked to convert a selection. the type of the structure whose address is passed to these callbacks is XmConvertCallbackStruct. the reason is XmCR_OK.
• XmNdestinationCallback — specifies a list of callbacks called when the DrawingArea is the destination of a transfer operation. the type of the structure whose address is passed to these callbacks is XmDestinationCallbackStruct. the reason is XmCR_OK.
• XmNexposeCallback — specifies the list of callbacks that is called when DrawingArea receives an exposure event. the callback reason is XmCR_EXPOSE. the callback structure also includes the exposure event.

🚨 lowkey important: the default bit gravity for Manager windows is NorthWestGravity. this may cause the XmNexposeCallback procedures not to be invoked when the DrawingArea window is made smaller. so if you're shrinking and nothing's firing, that's why bestie. 😭

• XmNinputCallback — specifies the list of callbacks that is called when the DrawingArea receives a keyboard or mouse event (key or button, up or down). the callback reason is XmCR_INPUT. the callback structure also includes the input event.
• XmNmarginHeight — specifies the minimum spacing in pixels between the top or bottom edge of DrawingArea and any child widget.
• XmNmarginWidth — specifies the minimum spacing in pixels between the left or right edge of DrawingArea and any child widget.
• XmNresizeCallback — specifies the list of callbacks that is called when the DrawingArea is resized. the callback reason is XmCR_RESIZE.
• XmNresizePolicy — controls the policy for resizing DrawingArea widgets. possible values include:
  • XmRESIZE_NONE — fixed size
  • XmRESIZE_ANY — shrink or grow as needed
  • XmRESIZE_GROW — grow only

---

🧚 Inherited Resources 🧚

DrawingArea inherits behavior and resources from the following superclasses. for a complete description of each resource, refer to the reference page for that superclass.

…and that's where this part stops, bestie — the inherited resource tables are coming up next, so don't go anywhere. 🫶

---

🌸 XmManager Resource Set 🌸

okay so before we even look at what XmDrawingArea brings to the table, bestie, we have to give it up for everything it inherits from XmManager — because every single one of these is riding along with your widget whether you asked or not 💅. Full list, no skips, no cap:

• XmNbottomShadowColor — class XmCBottomShadowColor, type Pixel, default is dynamic, access CSG. yes the default literally says dynamic, it's not a typo, it's just the vibe ✨
• XmNbottomShadowPixmap — class XmCBottomShadowPixmap, type Pixmap, default XmUNSPECIFIED_PIXMAP, access CSG
• XmNforeground — class XmCForeground, type Pixel, default is 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. she's got a default default and honestly? iconic 👑
• XmNpopupHandlerCallback — class XmCCallback, type XtCallbackList, default NULL, access C
• XmNshadowThickness — class XmCShadowThickness, type Dimension, default 0, access CSG
• 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

seventeen whole resources, all of them yours by birthright, fr fr 🫶

---

🦋 Composite Resource Set 🦋

and then there's the Composite set, which is shorter but like… main character energy nonetheless. three of them, that's it, that's the whole squad:

• XmNchildren — class XmCReadOnly, type WidgetList, default NULL, access G
• XmNinsertPosition — class XmCInsertPosition, type XtOrderProc, default NULL, access CSG
• XmNnumChildren — class XmCReadOnly, type Cardinal, default 0, access G

okay real talk, bestie: see how XmNchildren and XmNnumChildren are both marked G in that access column? that's get-only energy. you read them, you don't write them. don't come for me when it doesn't stick 💀

and yes, that's genuinely the entire Composite set. short king behavior. we love that for it 🎀

---

✨ Core Resource Set ✨

bestie, this is the whole entire Core Resource Set and I am not skipping a single one, because you deserve the full picture 💖 every line has its name, class, type, default and access. read it like a menu. slay responsibly.

• 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 🦋

okay so a pointer to the following structure gets passed to the XmNexposeCallback, XmNinputCallback, and XmNresizeCallback procedures. look at her 👑

typedef struct
{
        int reason;
        XEvent * event;
        Window window;
} XmDrawingAreaCallbackStruct;

• reason — tells you why the callback got invoked. the whole lore, basically.
• event — points at the XEvent that triggered the callback. heads up: this one is NULL for the XmNresizeCallback 🫥
• window — is set to the widget window. that's the whole job.

and then a pointer to this next structure gets passed to the XmNconvertCallback procedures. different struct, same energy ✨

typedef struct
{
        int reason;
        XEvent *event;
        Atom selection;
        Atom target;
        XtPointer source_data;
        XtPointer location_data;
        int flags;
        XtPointer parm;
        int parm_format;
        unsigned long parm_length;
        int status;
        XtPointer value;
        Atom type;
        int format;
        unsigned long length;
} XmConvertCallbackStruct;

• reason — tells you why the callback got invoked. iconic of her honestly.
• event — points at the XEvent that triggered the callback. it can be NULL, so pls check before you go dereferencing, no cap 😭

---

• selection — the selection we're converting, bestie. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP. 💅
• target — the conversion target. Periodt.
• source_data — info about the selection source. When the selection is _MOTIF_DROP, source_data is the DragContext. Otherwise, it's NULL.
• location_data — info about where the data to be converted lives. If the value is NULL, the data to be transferred consists of the widget's current selection.
• flags — the status of the conversion. Possible values are:
  • XmCONVERTING_NONE — this flag is currently unused. (placeholder era 💀)
  • XmCONVERTING_PARTIAL — the target widget was able to be converted, but some data was lost. 😭
  • XmCONVERTING_SAME — the conversion target is the source of the data to be transferred. iconic.
  • XmCONVERTING_TRANSACT — this flag is currently unused. another unused baddie.
• parm — contains parameter data for this target. If no parameter data exists, the value is NULL.

When selection is CLIPBOARD and target is _MOTIF_CLIPBOARD_TARGETS or _MOTIF_DEFERRED_CLIPBOARD_TARGETS, the value is the requested operation (XmCOPY, XmMOVE, or XmLINK). 🫶

• parm_format — specifies whether the data in parm should be viewed as a list of char, short, or long quantities. Possible values are 0 (when parm is NULL), 8 (when the data in parm should be viewed as a list of chars), 16 (when the data in parm should be viewed as a list of shorts), or 32 (when the data in parm should be viewed as a list of longs). Note that parm_format symbolizes a data type, not the number of bits in each list element. For example, on some machines, a parm_format of 32 means that the data in parm should be viewed as a list of 64-bit quantities, not 32-bit quantities. yes, she's tricky like that.
• parm_length — specifies the number of elements of data in parm, where each element has the size specified by parm_format. When parm is NULL, the value is 0.
• status — an IN/OUT member that specifies the status of the conversion. The initial value is XmCONVERT_DEFAULT. The callback procedure can set this member to one of the following values:
  • XmCONVERT_DEFAULT — this value means that the widget class conversion procedure, if any, is called after the callback procedures return. If the widget class conversion procedure produces any data, it overwrites the data provided by the callback procedures in the value member.
  • XmCONVERT_MERGE — this value means that the widget class conversion procedure, if any, is called after the callback procedures return. If the widget class conversion procedure produces any data, it appends its data to the data provided by the callback procedures in the value member. This value is intended for use with targets that result in lists of data, such as TARGETS.
  • XmCONVERT_DONE — this value means that the callback procedure has successfully finished the conversion. The widget class conversion procedure, if any, is not called after the callback procedures return.
  • XmCONVERT_REFUSE — this value means that the callback procedure has terminated the conversion process without completing the requested conversion. The widget class conversion procedure, if any, is not called after the callback procedures return.
• value — an IN/OUT parameter that contains any data that the callback procedure produces as a result of the conversion. The initial value is NULL. If the callback procedure sets this member, it must ensure that the type, format, and length members correspond to the data in value. The callback procedure is responsible for allocating, but not for freeing, memory when it sets this member.
• type — an IN/OUT parameter that indicates the type of the data in the value member. The initial value is INTEGER.
• format — an IN/OUT parameter that specifies whether the data in value should be viewed as a list of char, short, or long quantities. The initial value is 8. The callback procedure can set this member to 8 (for a list of char), 16 (for a list of short), or 32 (for a list of long).
• length — an IN/OUT member that specifies the number of elements of data in value, where each element has the size symbolized by format. The initial value is 0.

A pointer to the following callback structure is passed to the XmNdestinationCallback procedures:

typedef struct
{
        int reason;
        XEvent *event;
        Atom selection;
        XtEnum operation;
        int flags;
        XtPointer transfer_id;
        XtPointer destination_data;
        XtPointer location_data;
        Time time;
} XmDestinationCallbackStruct;

• reason — indicates why the callback was invoked.
• event — points to the XEvent that triggered the callback. It can be NULL.
• selection — indicates the selection for which data transfer is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP.
• operation — indicates the type of transfer operation requested.
  • When the selection is PRIMARY, possible values are XmMOVE, XmCOPY, and XmLINK.
  • When the selection is SECONDARY or CLIPBOARD, possible values are XmCOPY and XmLINK.
  • When the selection is _MOTIF_DROP, possible values are XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of XmOTHER means that the callback procedure must get further information from the XmDropProcCallbackStruct in the destination_data member.
• flags — indicates whether or not the destination widget is also the source of the data to be transferred. Possible values are:
  • XmCONVERTING_NONE — the destination widget is not the source of the data to be transferred.
  • XmCONVERTING_SAME — the destination widget is the source of the data to be transferred.
• transfer_id — serves as a unique ID to identify the transfer transaction. 🆔
• destination_data — contains information about the destination. When the selection is _MOTIF_DROP, the callback procedures are called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. When the selection is SECONDARY, destination_data is an Atom representing a target recommmended by the selection owner for use in converting the selection. Otherwise, destination_data is NULL.
• location_data — contains information about the location where data is to be transferred. The value is always NULL when the selection is SECONDARY or CLIPBOARD. If the value is NULL, the data is to be inserted at the widget's cursor position. location_data is only valid for the duration of a transfer. Once XmTransferDone procedures start to be called, location_data will no longer be stable. so don't hold onto it, bestie. 💅
• time — indicates the time when the transfer operation began. ⏰

Translations ✨

XmDrawingArea inherits translations from XmManager. Before calling the XmManager actions, all events in the inherited translations except <BtnMotion>, <EnterWindow>, <LeaveWindow>, <FocusIn>, and <FocusOut> also call the DrawingAreaInput() action.

XmDrawingArea has the following additional translations. The following key names are listed in the X standard key event translation table syntax. This format is the one used by Motif to specify the widget actions corresponding to a given key. A brief overview of the format is provided under VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation.

• <BtnDown>: DrawingAreaInput()
• <BtnUp>: DrawingAreaInput()
• <KeyDown>: DrawingAreaInput() ManagerGadgetKeyInput()
• <KeyUp>: DrawingAreaInput()

Action Routines ✨

The XmDrawingArea action routines are

• DrawingAreaInput(): Unless the event takes place in a gadget, calls the callbacks for XmNinputCallback
• ManagerGadgetKeyInput(): Causes the current gadget to process a keyboard event

Additional Behavior ✨

The XmDrawingArea widget has the following additional behavior:

• <Expose>: Calls the callbacks for XmNexposeCallback
• <Widget Resize>: Calls the callbacks for XmNresizeCallback

Virtual Bindings ✨

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

RELATED ✨

Composite(3), Constraint(3), Core(3), XmCreateDrawingArea(3), XmManager(3), XmVaCreateDrawingArea(3), and XmVaCreateManagedDrawingArea(3).

---

that's the whole vibe, bestie 💖 signed off by XmDrawingArea(library call) — and the date? not shown in this footer, but it's giving timeless icon energy ✨