XMCLIPBOARDSTARTRETRIEVE(3)

💖 XmClipboardStartRetrieve 💖

okay bestie, so this one is from the library call girlies — it's XmClipboardStartRetrieve, and it's literally your lil' warm-up stretch before you pull data out of the clipboard 🎀

---

✨ SYNOPSIS ✨

#include <Xm/CutPaste.h>
int XmClipboardStartRetrieve (display, window, timestamp)
        Display * display;
        Window  window;
        Time    timestamp;
(void)

---

🌸 DESCRIPTION 🌸

So XmClipboardStartRetrieve is the function that tells the clipboard routines "hey girl hey, I'm ready to start copying an item from the clipboard" 🫶

The clipboard gets locked by this routine, and it stays locked until you call XmClipboardEndRetrieve. Periodt, that's the deal — no unlocking till then. 🔒

And here's the cute part: between a call to XmClipboardStartRetrieve and a call to XmClipboardEndRetrieve, if you make multiple calls to XmClipboardRetrieve with the same format name, the data gets incrementally copied from the clipboard until all the data in that format has been retrieved. It's giving ✨streaming✨.

If a call to XmClipboardRetrieve returns XmClipboardTruncate, that's your signal that more data is still waiting to be copied in the given format 👀

💅 Bestie tip from the manpage itself: it's recommended that any calls to the Inquire functions that your app needs to make in order to complete the copy from the clipboard happen between the call to XmClipboardStartRetrieve and the first call to XmClipboardRetrieve. That way your app does not need to call XmClipboardLock and XmClipboardUnlock. Efficiency, we love to see it. 👑

Now the params, bestie:

• display — Specifies a pointer to the Display structure that was returned in a previous call to XOpenDisplay or XtDisplay.
• window — Specifies the window ID of a widget that relates the application window to the clipboard. You can grab the widget's window ID through XtWindow. The same application instance should pass the same window ID to each of the clipboard functions that it calls. Consistency is key, no cap. 🌈
• timestamp — Specifies the time of the event that triggered the copy. A valid timestamp must be supplied; it is not sufficient to use CurrentTime. Like, don't even try it. 😭

---

🦋 RETURN 🦋

• XmClipboardSuccess — The function is successful. Slay! 💖
• XmClipboardLocked — The function failed because the clipboard was locked by another application. 😤 The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. Main character energy: you get to decide whether to keep fighting or walk away. 🚶‍♀️

---

💜 RELATED 💜

the whole friend group, fr fr:

• XmClipboardEndRetrieve(3)
• XmClipboardInquireCount(3)
• XmClipboardInquireFormat(3)
• XmClipboardInquireLength(3)
• XmClipboardInquirePendingItems(3)
• XmClipboardLock(3)
• XmClipboardRetrieve(3)
• XmClipboardStartCopy(3)
• XmClipboardUnlock(3)

---

and that's the whole vibe 💫 this was XmClipboardStartRetrieve(library call), brought to you by the library call section of your friendly neighborhood manual — go forth and retrieve, bestie, you got this 🎀✨💅