XMTRANSFERVALUE(3)

💫 XmTransferValue 💫

okay bestie, welcome to XmTransferValue(library call) — yes that's the whole manual page name, we're in the Xm library call section, and this function is literally the moment data goes from here to there. main character energy fr fr.

---

✨ NAME ✨

XmTransferValue — a toolkit function that transfers data to a destination 🎀

---

🌸 SYNOPSIS 🌸

#include <Xm/Xm.h>

void XmTransferValue(
XtPointer transfer_id,
Atom target,
XtCallbackProc proc,
XtPointer client_data,
Time time);

---

💅 DESCRIPTION 💅

so basically, XmTransferValue converts a selection, transferring any data from the selection owner, and it does all that in the context of a data transfer operation that's already been initiated. like, the party already started, you're just bringing the snacks. 🍓

an application can call this routine from an XmNdestinationCallback procedure, or honestly from any function that gets called as a result of one. no cap.

the caller of XmTransferValue supplies the target that the selection gets converted to. the caller ALSO supplies a callback procedure to handle the data that results from that conversion. you're handing over the keys, bestie. 🔑

transfer_id

• specifies a unique indentifier for the data transfer operation. this value must be the same as the value of the transfer_id member of the XmDestinationCallbackStruct passed to the XmNdestinationCallback procedure. like, it has to match, or it's giving chaos.

target

• specifies the target to which the selection is to be converted.

proc

• specifies a callback procedure to be invoked when the selection has been converted and the data, if any, is available. this procedure is the one responsible for inserting or otherwise handling any data transferred. it can also terminate the data transfer by calling XmTransferDone. so much power in one little callback. 👑
• the proc receives three arguments:
  • the widget that requested the conversion
  • the value of the client_data argument
  • a pointer to an XmSelectionCallbackStruct
• > heads up: this procedure can be called before or after XmTransferValue returns. so don't go assuming an order, okay? 😭

client_data

• specifies data to be passed to the callback procedure (the value of the proc argument) when the selection has been converted.

time

• specifies the time of the XEvent that triggered the data transfer. you should typically set this field to XtLastTimestampProcessed. that's the vibe. ⏰

---

🦋 the callback struct 🦋

the callback procedure (the value of the proc argument) receives a pointer to an XmSelectionCallbackStruct, which has the following definition:

typedef struct
{
        int reason;
        XEvent *event;
        Atom selection;
        Atom target;
        Atom type;
        XtPointer transfer_id;
        int flags;
        int remaining;
        XtPointer value;
        unsigned long length;
        int format;
} XmSelectionCallbackStruct;

reason

• indicates why the callback was invoked.

event

• points to the XEvent that triggered the callback. it can be NULL. (yes bestie, sometimes it's just not there, and that's valid 💀)

selection

• specifies the selection that has been converted.

target

• specifies the target to which XmTransferValue requested conversion. the value is the same as the value of the target argument to XmTransferValue.

type

• specifies the type of the selection value. this is not the target, but the type used to represent the target. the value XT_CONVERT_FAIL means that the selection owner did not respond to the conversion request within the Intrinsics selection timeout interval. 💀 ghosted, fr.

transfer_id

• specifies a unique indentifier for the data transfer operation. the value is the same as the value of the transfer_id argument to XmTransferValue.

flags

• this member is currently unused. the value is always XmSELECTION_DEFAULT. it's just sitting there, existing, not doing much. 🧚

remaining

• indicates the number of transfers remaining for the operation specified by transfer_id.

value

• represents the data transferred by this request. the application is responsible for freeing the value by calling XtFree. yes you free it, don't leave it hanging. 🙈

length

• indicates the number of elements of data in value, where each element has the size symbolized by format. if value is NULL, length is 0.

format

• indicates whether the data in value should be viewed as a list of char, short, or long quantities. possible values are 8 (for a list of char), 16 (for a list of short), or 32 (for a list of long).

---

🔥 RELATED 🔥

XmTransferSetParameters(3), XmTransferSendRequest(3), and XmTransferStartRequest(3). go read those next, bestie, they're the whole friend group. 🫶

---

and that's the page!! this was XmTransferValue(library call), straight out of the library call section, dated and versioned exactly as the manual says — no cap, that's the source and the date, and it's iconic. bye babes 💖✨