Tk_GetSelection(3)

🌸 NAME 🌸

okay so this page is from the Tk Library Procedures, and the main character is Tk_GetSelection - retrieve the contents of a selection. that's the whole NAME vibe, bestie 💖

---

✨ SYNOPSIS ✨

#include <tk.h>

int
Tk_GetSelection(interp, tkwin, selection, target, proc, clientData)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter used for reporting errors, bestie.
• Tk_Window tkwin (in) — the window on whose behalf to retrieve the selection; it determines the display from which to retrieve. 🪟
• Atom selection (in) — the name of the selection to be retrieved.
• Atom target (in) — the form in which to retrieve the selection.
• Tk_GetSelProc *proc (in) — the procedure to invoke to process pieces of the selection as they are retrieved. 💅
• void *clientData (in) — an arbitrary one-word value to pass to proc.

---

🦋 DESCRIPTION 🦋

Tk_GetSelection retrieves the selection specified by the atom selection in the format specified by target. the selection may actually be retrieved in several pieces; as each piece is retrieved, proc is called to process the piece. proc should have arguments and result that match the type Tk_GetSelProc:

typedef int Tk_GetSelProc(
        void *clientData,
        Tcl_Interp *interp,
        char *portion);

the clientData and interp parameters to proc will be copies of the corresponding arguments to Tk_GetSelection. portion will be a pointer to a string containing part or all of the selection. for large selections, proc will be called several times with successive portions of the selection. 🫶

the X Inter-Client Communication Conventions Manual allows a selection to be returned in formats other than strings, e.g. as an array of atoms or integers. if this happens, Tk converts the selection back into a string before calling proc. if a selection is returned as an array of atoms, Tk converts it to a string containing the atom names separated by white space. for any other format besides string, Tk converts a selection to a string containing hexadecimal values separated by white space. ✨

Tk_GetSelection returns to its caller when the selection has been completely retrieved and processed by proc, or when a fatal error has occurred (e.g. the selection owner did not respond promptly). Tk_GetSelection normally returns TCL_OK; if an error occurs, it returns TCL_ERROR and leaves an error message in interpreter interp's result. proc should also return either TCL_OK or TCL_ERROR. if proc encounters an error in dealing with the selection, it should leave an error message in the interpreter result and return TCL_ERROR; this will abort the selection retrieval. 😭

---

👑 KEYWORDS 👑

format, get, selection retrieval

---

and that's the whole page, bestie 💅 footer vibe check: this is Tk version 4.0, page Tk_GetSelection(3) — no separate date printed on this footer, just those two cuties. 🎀✨