XTGETSELECTIONVALUEINCREMENTAL(3)

💖 XtGetSelectionValueIncremental(3) — XT FUNCTIONS 💖

okay bestie, sit DOWN, because we're about to talk about getting selection values incrementally and it's honestly kind of iconic. this is a page from the X Toolkit Intrinsics (Xt) era, so grab a strawberry 🍓 and let's go.

---

✨ NAME ✨

XtGetSelectionValueIncremental, XtGetSelectionValuesIncremental — obtain selection values

like, both of them. plural. two functions, one page, we're doing this together 🫶

---

🌸 SYNTAX 🌸

first things first, you gotta include the header or nothing works, no cap:

#include <X11/Intrinsic.h>

void XtGetSelectionValueIncremental(Widget w, Atom selection, Atom
       target, XtSelectionCallbackProc callback, XtPointer client_data,
       Time time);

void XtGetSelectionValuesIncremental(Widget w, Atom selection, Atom
       *targets, int count, XtSelectionCallbackProc callback, XtPointer
       *client_data, Time time);

see that little * difference between target and *targets? yeah. that's the whole plot twist. ⭐

---

🎀 ARGUMENTS 🎀

here's the cast of characters, every single one of them, and yes client_data shows up TWICE because it means different things in each function. keep up 💅

• callback — the callback procedure that's gonna get called when the selection value has been obtained. your little notification bestie.
• client_data — (for the singular vibe) the argument that gets passed to the specified procedure when it's called.
• client_data — (for the plural vibe) the client data, one for each target type, that gets passed to the callback procedure when it's called for that target. so like, a whole lil entourage of client datas.
• count — the length of the targets and client_data lists. yes, both lists. same number. they match. 💖
• selection — which particular selection you want (that is, primary or secondary). pick your fighter.
• target — the type of the information that is needed about the selection.
• targets — the types of information that is needed about the selection. plural. multiple. a lil collection.
• time — the timestamp that indicates when the selection value is desired. timestamped, like a good story.
• w — the widget that is making the request. it's the main character, obviously. 👑

---

🦋 DESCRIPTION 🦋

XtGetSelectionValueIncremental

so XtGetSelectionValueIncremental is basically XtGetSelectionValue but with a plot twist: the selection_callback procedure gets called repeatedly as multiple segments of the selection value get delivered. it's giving... serialized. chapter by chapter. 📖

the end of the selection value is signaled when selection_callback is called with a non-NULL value of length zero. and heads up bestie — that zero-length thing must still be freed by the client. don't forget. don't skip it. don't be that person. 🙈

now for the dramatic part: if the transfer of the selection gets aborted in the middle of a transfer (for example, because to timeout — yes, the original says "because to timeout", we are not touching it, it's canon), then the selection_callback procedure is called with a type value equal to the symbolic constant XT_CONVERT_FAIL so that the requestor can dispose of the partial selection value it has collected up until that point.

⚠️ and upon receiving XT_CONVERT_FAIL, the requesting client must determine for itself whether or not a partially completed transfer is meaningful. nobody's gonna decide that for you. that's a you problem. sorry babe. 💀

XtGetSelectionValuesIncremental

XtGetSelectionValuesIncremental is similar to XtGetSelectionValueIncremental except it takes a list of target types and a list of client data, and obtains the current value of the selection converted to each of the targets. the effect is as if each target were specified in a separate call to XtGetSelectionValueIncremental. same energy, just batched. 🔥

the callback is called once with the corresponding client data for each target.

and here's the slay part: XtGetSelectionValuesIncremental does guarantee that all the conversions will use the same selection value, because the ownership of the selection cannot change in the middle of the list — which is exactly what could happen if you were out here calling XtGetSelectionValueIncremental over and over again. atomicity? we have it. periodt. 💅

---

🌈 SEE ALSO 🌈

go read these next, bestie, they're required reading:

• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language X Interface

---

💜 a lil sign-off 💜

that's the whole page, you ate it, you understood it, i'm obsessed with you. this was XtGetSelectionValueIncremental(3) from X Version 11, libXt 1.3.1 — go forth and free your non-NULL zero-length values, mwah 🎀✨🦋