XMCLIPBOARDRETRIEVE(3)

💖 XmClipboardRetrieve 💖

okay bestie, so this one lives in the library call manual (yes that's the section, we're fancy here), and it's genuinely one of the most useful little gremlins in the whole Xm clipboard family. it's called XmClipboardRetrieve and it goes and gets you a data item off the clipboard. let's get into it 🫶

---

✨ NAME ✨

XmClipboardRetrieve — a clipboard function that retrieves a data item from the clipboard. that's it, that's the job, and it does it slayfully 💅

---

🌸 SYNOPSIS 🌸

#include <Xm/CutPaste.h>
int XmClipboardRetrieve (display, window, format_name,
        buffer, length, num_bytes, private_id)
        Display * display;
        Window  window;
        char    * format_name;
        XtPointer       buffer;
        unsigned long   length;
        unsigned long   * num_bytes;
        long    * private_id;
(void)

not me including that (void) at the end, it's just... there. iconic. anyway.

---

🦋 DESCRIPTION 🦋

so XmClipboardRetrieve pulls the current data item out of clipboard storage. simple. BUT — and this is the part where you gotta pay attention bestie — it returns a warning in three situations:

• the clipboard is locked 🔒
• there's no data on the clipboard 📭
• the data needs to be truncated because your buffer length is too short 😭

now here's the fun part. between a call to XmClipboardStartRetrieve and a call to XmClipboardEndRetrieve, if you call XmClipboardRetrieve multiple times with the same format name, the data gets copied incrementally from the clipboard until all the data in that format has been copied. it's giving "one scoop at a time, babe" 🍓

and when you get XmClipboardTruncate back from a call to XmClipboardRetrieve? that means more data remains to be copied in the given format. not done yet, keep going 💪

pro move: any calls to the Inquire functions that your app needs to make to effect the copy from the clipboard should be made between the call to XmClipboardStartRetrieve and the first call to XmClipboardRetrieve. do it that way and your app doesn't need to call XmClipboardLock and XmClipboardUnlock at all. obsessed, honestly ✨

the arguments, one by one 💜

• display — a pointer to the Display structure that got returned in a previous call to XOpenDisplay or XtDisplay. your classic display moment.
• window — the window ID of a widget that relates the application window to the clipboard. you can get the widget's window ID through XtWindow. and listen: the same application instance should pass the same window ID to each of the clipboard functions that it calls. consistency is the vibe, fr fr.
• format_name — the name of a format in which the data is stored on the clipboard. name your format, bestie.
• buffer — the buffer the application wants the clipboard to copy the data into. the function allocates space to hold the data returned into the buffer. the application is responsible for managing this allocated space, and can recover it by calling XtFree. so like... you got a gift, but you also gotta take out the trash 🎀
• length — the length of the application buffer. (yes, that buffer. the one above.)
• num_bytes — the number of bytes of data copied into the application buffer.
• private_id — the private data stored with the data item by the application that placed the data item on the clipboard. and if the application didn't store private data with the data item? this argument returns 0 (zero). it's giving "no secrets here" 🙈

---

👑 RETURN 👑

• XmClipboardSuccess — the function was successful. we ate and left no crumbs ✨
• XmClipboardLocked — the function failed because the clipboard was locked by another application. but your app can keep calling the function again with the same parameters until the lock goes away. this gives the application the opportunity to ask the user whether they wanna keep trying or give up on the operation. so like, polite persistence, not a crash-out 💅
• XmClipboardTruncate — the data returned is truncated because the user did not provide a buffer large enough to hold the data. buffer said "no ❤️"
• XmClipboardNoData — the function could not find data on the clipboard corresponding to the format requested. this could happen because:
  • the clipboard is empty 🫙
  • there is data on the clipboard but not in the requested format
  • the data in the requested format was passed by name and is no longer available 💀

---

🌈 RELATED 🌈

• XmClipboardEndRetrieve(3)
• XmClipboardLock(3)
• XmClipboardStartCopy(3)
• XmClipboardStartRetrieve(3)
• XmClipboardUnlock(3)

go read those too, they're all in the same friend group 🫶

---

and that's the whole page bestie!! this one's straight out of the XmClipboardRetrieve(library call) manual — so yeah, library call is the whole section vibe, and the footer said the exact same thing as the header, which is lowkey iconic of it. no date on this one, she's timeless 💖 anyway ily, go retrieve some clipboard data, and remember: same window ID, every time. periodt. 👑💅✨