XMDROPSITE(3)

✨ NAME ✨

XmDropSite — The DropSite Registry. It's a library call, bestie. Like, from the library call section. 💖

🌈 SYNOPSIS 🌈

#include <Xm/DragDrop.h>

💅 DESCRIPTION 💅

Okay so a client registers a widget or gadget as a drop site using the XmDropSiteRegister function. That's the whole vibe. Plus, this routine defines the behavior and capabilities of a drop site by specifying appropriate resources. For example, the XmNimportTargets and XmNnumImportTargets resources identify respectively the selection target types and number of types supported by a drop site. The visual animation effects associated with a drop site are also described with DropSite resources.

Drop site animation effects that happen when the pointer enters a valid drop site are called drag-under effects. A receiver can pick from several animation styles supplied by the toolkit or can provide customized animation effects. The toolkit's drag-under effects include border highlighting, shadow in/out drawing, and pixmap representation. Iconic, honestly. ✨

When a preregister drag protocol style is used, the toolkit generates drag-under visual effects based on the value of the XmNanimationStyle resource. In dynamic mode, if the drop site XmNdragProc resource is NULL, the toolkit also provides animation effects based on the XmNanimationStyle resource. Otherwise, if the XmNdragProc routine is specified, the receiver can either assume responsibility for animation effects (through the XmNdragProc routine) or rely on the toolkit to provide animation. An application can either handle all or none of the animation effects for a particular drop site. That is, an application should never do a partial job of animation on a particular drop site. No halfsies, periodt. 💅

Drop sites may overlap. The initial stacking order corresponds to the order in which the drop sites were registered. When a drop site overlaps another drop site, the drag-under effects of the drop site underneath are clipped by the obscuring drop site(s). The way that works is just... okay? Keep up. 🦋

The XmDropSiteUpdate routine sets resources for a widget that is registered as a drop site. XmDropSiteRetrieve gets drop site resource values previously specified for a registered widget. These routines are used instead of XtSetValues and XtGetValues. Don't use the old ones, bestie. 🙈

🧚 Classes 🧚

XmDropSite does not inherit from any widget class. It's giving independent. 👑

👑 New Resources 👑

The following resource set defines a set of widget resources used by the programmer to specify data. 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 indicate if the given resource can be set at creation time (C), set by using XmDropSiteUpdate (S), retrieved by using XmDropSiteRetrieve (G), or is not applicable (N/A).

Here's the XmDropSite Resource Set, no cap:

• XmNanimationMask — Class: XmCAnimationMask, Type: Pixmap, Default: XmUNSPECIFIED_PIXMAP, Access: CSG
• XmNanimationPixmap — Class: XmCAnimationPixmap, Type: Pixmap, Default: XmUNSPECIFIED_PIXMAP, Access: CSG
• XmNanimationPixmapDepth — Class: XmCAnimationPixmapDepth, Type: int, Default: 0, Access: CSG
• XmNanimationStyle — Class: XmCAnimationStyle, Type: unsigned char, Default: XmDRAG_UNDER_HIGHLIGHT, Access: CSG
• XmNdragProc — Class: XmCDragProc, Type: XtCallbackProc, Default: NULL, Access: CSG
• XmNdropProc — Class: XmCDropProc, Type: XtCallbackProc, Default: NULL, Access: CSG
• XmNdropRectangles — Class: XmCDropRectangles, Type: XRectangle *, Default: dynamic, Access: CSG
• XmNdropSiteActivity — Class: XmCDropSiteActivity, Type: unsigned char, Default: XmDROP_SITE_ACTIVE, Access: CSG
• XmNdropSiteOperations — Class: XmCDropSiteOperations, Type: unsigned char, Default: XmDROP_MOVE | XmDROP_COPY, Access: CSG
• XmNdropSiteType — Class: XmCDropSiteType, Type: unsigned char, Default: XmDROP_SITE_SIMPLE, Access: CG
• XmNimportTargets — Class: XmCImportTargets, Type: Atom *, Default: NULL, Access: CSG
• XmNnumDropRectangles — Class: XmCNumDropRectangles, Type: Cardinal, Default: 1, Access: CSG
• XmNnumImportTargets — Class: XmCNumImportTargets, Type: Cardinal, Default: 0, Access: CSG

XmNanimationMask Specifies a mask to use with the pixmap specified by XmNanimationPixmap when the animation style is XmDRAG_UNDER_PIXMAP.

XmNanimationPixmap Specifies a pixmap for drag-under animation when the animation style is XmDRAG_UNDER_PIXMAP. The pixmap is drawn with its origin at the upper left corner of the bounding box of the drop site. If the drop site window is larger than the animation pixmap, the portion of the window not covered by the pixmap will be tiled with the window's background color.

XmNanimationPixmapDepth Specifies the depth of the pixmap specified by the XmNanimationPixmap resource. When the depth is 1, the colors are taken from the foreground and background of the drop site widget. For any other value, drop site animation occurs only if the XmNanimationPixmapDepth matches the depth of the drop site window. Colors are derived from the current colormap.

XmNanimationStyle Specifies the drag-under animation style used when a drag enters a valid drop site. The possible values are

• XmDRAG_UNDER_HIGHLIGHT — The drop site uses highlighting effects.
• XmDRAG_UNDER_SHADOW_OUT — The drop site uses an outset shadow.
• XmDRAG_UNDER_SHADOW_IN — the drop site rocks an inset shadow. subtle. moody. iconic. ✨
• XmDRAG_UNDER_PIXMAP — the drop site uses the pixmap you set with XmNanimationPixmap to say "yup, i can take that drop bestie." 🎀
• XmDRAG_UNDER_NONE — no animation effects at all, we're keeping it minimal 💅. and heads up: if you're running a dynamic protocol, your client can still serve drag-under effects from inside its own XmNdragProc routine. so you're not totally bare.

---

✨ the resources, continued ✨

• XmNdragProc — the procedure that gets called when the drop site catches a crossing, motion, or operation changed message. note: it only fires when you're using a dynamic protocol, so if that's not your setup, this one's just sitting there. the struct whose address gets passed in is XmDragProcCallbackStruct, and the reason sent along is one of these bad boys:
  • XmCR_DROP_SITE_ENTER_MESSAGE
  • XmCR_DROP_SITE_LEAVE_MESSAGE
  • XmCR_DRAG_MOTION
  • XmCR_OPERATION_CHANGED

and here's the fun part: the drag procedure is allowed to change some members of that XmDragProcCallbackStruct it got handed. once it returns, the toolkit takes those final values and uses them to initialize some members of the callback struct that goes to the initiator's matching callbacks — that's the DragContext's XmNdropSiteEnterCallback, XmNdropSiteLeaveCallback, XmNdragMotionCallback, or XmNoperationChangedCallback. so yeah, you're literally writing back into the flow. main character energy fr fr 🔥

• XmNdropProc — the procedure that fires when a drop happens on a drop site (and no, a cancel or interrupt action does not count), no matter what the status of the drop site is. the struct address passed in is XmDropProcCallbackStruct, and the reason sent is XmCR_DROP_MESSAGE.

same deal as before: the drop procedure can change some members of the XmDropProcCallbackStruct it received. after it returns, the toolkit uses those final values to initialize some members of the XmDropStartCallbackStruct that gets passed to the initiator's drop start callbacks — specifically the DragContext's XmNdropStartCallback callbacks. 🫶

• XmNdropRectangles — a whole list of rectangles that describe the shape of a drop site. their locations are relative to the origin of the enclosing object. if XmNdropRectangles is NULL, the drop site is assumed to be the sensitive area of the enclosing widget. and if XmNdropSiteType is XmDROP_SITE_COMPOSITE, the application cannot specify this resource. nope. not allowed. 🙈

heads up bestie: retrieving this resource gives you allocated memory, and you have to free it yourself with the XtFree function. do not forget. i'm begging. 😭

• XmNdropSiteActivity — tells you whether a drop site is active or inactive. the values are XmDROP_SITE_ACTIVE, XmDROP_SITE_INACTIVE, and XmDROP_SITE_IGNORE.
  • an active drop site can receive a drop 🌸
  • an inactive drop site is just dormant. it's treated like it was never registered at all, and any drag-under visuals tied to entering or leaving it don't happen. BUT — plot twist — it's still used for clipping drag-under effects. so it's not fully gone, it's just not receiving.
  • a value of XmDROP_SITE_IGNORE means the drop site should be ignored for all purposes. like, everything. periodt. 💀
• XmNdropSiteOperations — the set of valid operations tied to a drop site. this resource is a bit mask, and you build it by combining one or more of these values with a bitwise operation like inclusive OR (|): XmDROP_COPY, XmDROP_LINK, and XmDROP_MOVE. and if you set it to XmDROP_NOOP, that means no operations are valid at all. 🚫
• XmNdropSiteType — the type of the drop site. the possible values are:
  • XmDROP_SITE_SIMPLE — the widget doesn't have any extra children registered as drop sites.
  • XmDROP_SITE_COMPOSITE — the widget will have children that are registered as drop sites. 👑
• XmNimportTargets — the list of target atoms that this drop site accepts. like a guest list, but for atoms. ✨
• XmNnumDropRectangles — the number of rectangles in the XmNdropRectangles list. and if the drop site type is XmDROP_SITE_COMPOSITE, the application can not specify this resource. same rule as its rectangle buddy above.
• XmNnumImportTargets — the number of atoms in the target atom list. simple. clean. counting. 🔢

---

🦋 Callback Information 🦋

so when the drop site receives crossing, motion, or operation changed messages, a pointer to this structure gets passed to the XmNdragProc routine:

typedef struct
{
        int reason;
        XEvent *event;
        Time timeStamp;
        Widget dragContext;
        Position x;
        Position y;
        unsigned char dropSiteStatus;
        unsigned char operation;
        unsigned char operations;
        Boolean animate;
} XmDragProcCallbackStruct, *XmDragProcCallback;

okay let's break down every single member, no skipping 💖

• reason — tells you why the callback got invoked.
• event — points to the XEvent that triggered the callback.
• timeStamp — the timestamp of the logical event.
• dragContext — the ID of the DragContext widget tied to this transaction.
• x — the x-coordinate of the pointer, relative to the drop site.
• y — the y-coordinate of the pointer, relative to the drop site. (yes, it's a matching set, we love symmetry 🎀)
• dropSiteStatus — an IN/OUT member that says whether or not a drop site is valid. here's the tea on how it gets initialized:
  • when reason is XmCR_DROP_SITE_ENTER_MESSAGE or XmCR_OPERATION_CHANGED, or when reason is XmCR_DRAG_MOTION or XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is not in the same drop site as on the previous invocation of the drag procedure — the toolkit initializes dropSiteStatus to XmDROP_SITE_VALID if the DragContext's XmNexportTargets and the DropSite's XmNimportTargets are compatible, and if the initial value of the operation member isn't XmDROP_NOOP. otherwise, the toolkit initializes dropSiteStatus to XmDROP_SITE_INVALID.
  • when reason is XmCR_DRAG_MOTION or XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is within the same drop site as on the previous invocation of the drag procedure — the toolkit initializes dropSiteStatus to whatever the value of dropSiteStatus was when the previous invocation of the drag procedure returned.

the drag procedure is allowed to change this member. after it returns, the toolkit uses the final value to initialize the dropSiteStatus member of the callback struct passed to the initiator's matching callbacks. 🫶

• operation — an IN/OUT member identifying an operation.

the toolkit initializes operation by picking one from the bitwise AND of the initial value of the operations member and the value of the DropSite's XmNdropSiteOperations resource. it searches that set first for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and initializes operation to the first one it finds. and if it finds none of these in the set? operation gets initialized to XmDROP_NOOP. no cap.

the drag procedure may change this member, and after it returns, the toolkit uses the final value to initialize the operation member of the callback struct passed to the initiator's matching callbacks.

• operations — an IN/OUT member showing the set of operations supported for the source data.
  • if the user does not select an operation (by pressing a modifier key), the toolkit initializes operations to the value of the DragContext's XmNdragOperations resource.
  • if the user does select an operation, the toolkit initializes operations to the bitwise AND of the corresponding operation and the value of the DragContext's XmNdragOperations resource.
  • and if the resulting set of operations is empty? the toolkit initializes operations to XmDROP_NOOP. rip. 💀

the drag procedure may change this member, and after it returns, the toolkit uses the final value to initialize the operations member of the callback struct passed to the initiator's matching callbacks.

• animate — an OUT member that says whether the toolkit or the receiver client provides drag-under effects for a valid drop site. if animate is set to True, the toolkit provides drop site animation following the XmNanimationStyle resource value. if it's set to False, the receiver generates the drag-under animation effects. so basically you're deciding who's doing the special effects, and both options are valid. 🌈

---

and when the drop site receives a drop message, a pointer to this structure goes to the XmNdropProc routine:

typedef struct
{
        int reason;
        XEvent *event;
        Time timeStamp;
        Widget dragContext;
        Position x;
        Position y;
        unsigned char dropSiteStatus;
        unsigned char operation;
        unsigned char operations;
        unsigned char dropAction;
} XmDropProcCallbackStruct, *XmDropProcCallback;

members, one by one, bestie:

• reason — indicates why the callback was invoked.
• event — the XEvent that triggered the callback.
• timeStamp — the timestamp of the logical event.
• dragContext — the ID of the DragContext widget associated with the transaction.
• x — the x-coordinate of the pointer relative to the drop site.
• y — the y-coordinate of the pointer relative to the drop site.
• dropSiteStatus — an IN/OUT member that indicates whether or not a drop site is valid.

okay so bestie, we were mid-struct and there's MORE. buckle up. 🎀

The toolkit initializes dropSiteStatus to XmDROP_SITE_VALID if the DragContext's XmNexportTargets and the DropSite's XmNimportTargets are compatible AND if the initial value of the operation member is not XmDROP_NOOP. Otherwise? The toolkit initializes dropSiteStatus to XmDROP_SITE_INVALID. that's the vibe check right there ✨

The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the dropSiteStatus member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

---

🌸 the members, one by one 🌸

• operation — an IN/OUT member that identifies an operation. iconic 💅

The toolkit initializes operation by selecting an operation from the bitwise AND of the initial value of the operations member and the value of the DropSite's XmNdropSiteOperations resource. The toolkit searches this set first for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and initializes operation to the first operation it finds in the set. If it finds none of these operations in the set, it initializes operation to XmDROP_NOOP. no op, no drama 🙈

The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the operation member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

• operations — an IN/OUT member that indicates the set of operations supported for the source data. the whole set, the whole menu, the whole vibe 🍓

If the user does not select an operation (by pressing a modifier key), the toolkit initializes operations to the value of the DragContext's XmNdragOperations resource. If the user does select an operation, the toolkit initializes operations to the bitwise AND of the corresponding operation and the value of the DragContext's XmNdragOperations resource. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP. empty set = noop, periodt 💀

The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the operations member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

• dropAction — an IN/OUT member that identifies the action associated with the drop. the possible values are: 👑
  • XmDROP — a drop was attempted. If the drop site is valid, drop transfer handling proceeds. we move! 🔥
  • XmDROP_HELP — the user has requested help on the drop site. they're asking for directions, bestie 🫶

The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the dropAction member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

---

🌈 RELATED INFORMATION 🌈

the whole friend group, go read these too: 💖

• XmDragContext(3)
• XmDragIcon(3)
• XmDropSiteConfigureStackingOrder(3)
• XmDropSiteEndUpdate(3)
• XmDropSiteQueryStackingOrder(3)
• XmDropSiteRegister(3)
• XmDropSiteStartUpdate(3)
• XmDropSiteUpdate(3)
• XmDropSiteUnregister(3)
• XmDropTransfer(3)
• and XmTargetsAreCompatible(3)

---

and that's a wrap on the whole page, bestie!! 🦋✨ this one lives in the library call section as XmDropSite(library call) — that's the source/version tag and date line at the very bottom, so consider it cited, mwah 💅🎀 go forth and drag-and-drop responsibly, ily, bye!! 💜🌸