Tk_CreateSelHandler(3tk)

✨ Tk_CreateSelHandler — bestie, let's talk selections ✨

okay so real talk: this page is from the Tk Library Procedures crew, and it's the manual entry for Tk_CreateSelHandler(3tk) (and its ride-or-die partner Tk_DeleteSelHandler, who we'll get to). it's all about arranging for your app to handle requests for a selection. X11 clipboard drama, but make it cute. let's go 🎀

---

🌸 NAME 🌸

Tk_CreateSelHandler, Tk_DeleteSelHandler — arrange to handle requests for a selection

---

✨ SYNOPSIS ✨

#include <tk.h>

Tk_CreateSelHandler(tkwin, selection, target, proc, clientData, format)

Tk_DeleteSelHandler(tkwin, selection, target)

---

💅 ARGUMENTS 💅

• Tk_Window tkwin (in) — the window that proc is gonna be providing selection info for. it's giving "this is my window, this is my selection" 💁
• Atom selection (in) — the name of the selection that proc will be spilling the tea about.
• Atom target (in) — the form in which proc can hand over the selection (like STRING or FILE_NAME, for example). this is the one that corresponds to the type arguments in selection commands, iykyk.
• Tk_SelectionProc *proc (in) — the procedure to invoke whenever the selection is owned by tkwin and the selection contents get requested in the format given by target. the moment the vibe check hits, proc gets called. 🔥
• void *clientData (in) — an arbitrary one-word value to pass to proc. no questions asked, it just gets handed over. 🫶
• Atom format (in) — if the selection requestor is not in this process, then format is the thing that determines the representation used to transmit the selection over to its requestor.

---

🦋 DESCRIPTION 🦋

So. Tk_CreateSelHandler arranges for a particular procedure (proc) to be called whenever selection is owned by tkwin and the selection contents are requested in the form given by target. literally that's the whole job description, no cap.

Target should be one of the entries defined in the left column of Table 2 of the X Inter-Client Communication Conventions Manual (ICCCM), or honestly any other form in which an application is willing to present the selection. the most common form is STRING. periodt. 💅

Proc should have arguments and a result that match the type Tk_SelectionProc:

typedef Tcl_Size Tk_SelectionProc(
        void *clientData,
        Tcl_Size offset,
        char *buffer,
        Tcl_Size maxBytes);

The clientData parameter to proc is a copy of the clientData argument you gave to Tk_CreateSelHandler. typically, clientData points to a data structure containing application-specific information that's needed to retrieve the selection — like its little backpack of context. 🎒

• offset specifies an offset position into the selection.
• buffer specifies a location at which to copy information about the selection.
• maxBytes specifies the amount of space available at buffer.

Proc should place a NULL-terminated string at buffer containing maxBytes or fewer characters (not including the terminating NULL), and it should return a count of the number of non-NULL characters stored at buffer. and if the selection no longer exists — like, it once existed but the user deleted the range of characters containing it — then proc should return -1. gone girl behaviour, but in a C function. 😭

---

📦 when the selection is THICC 📦

When transferring large selections, Tk will break them up into smaller pieces (typically a few thousand bytes each) for more efficient transmission. it's not being extra, it's just optimizing. ✨

It does this by calling proc one or more times, using successively higher values of offset to retrieve successive portions of the selection. here's the tea on the return values:

• if proc returns a count less than maxBytes, that means the entire remainder of the selection has been returned. we're done here. 🎀
• if proc's return value is maxBytes, that means there may be additional information in the selection, so Tk must make another call to proc to retrieve the next portion. cliffhanger energy. 🍓

---

🔤 formats, formats, formats 🔤

Proc always returns selection information in the form of a character string. BUT — and this is the plot twist — the ICCCM allows for information to be transmitted from the selection owner to the selection requestor in any of several formats, such as a string, an array of atoms, an array of integers, etc.

The format argument to Tk_CreateSelHandler indicates what format should be used to transmit the selection to its requestor (peep the middle column of Table 2 of the ICCCM for examples). so here's how it shakes out:

• if format is not STRING, then Tk will take the value returned by proc and divided it into fields separated by white space.
• if format is ATOM, then Tk will return the selection as an array of atoms, with each field in proc's result treated as the name of one atom.
• for any other value of format, Tk will return the selection as an array of 32-bit values, where each field of proc's result is treated as a number and translated to a 32-bit value.

in any event, the format atom is returned to the selection requestor along with the contents of the selection. both of them, together, always. 💜

---

🔁 replacing and deleting 🔁

If Tk_CreateSelHandler is called when there already exists a handler for selection and target on tkwin, then the existing handler is replaced with a new one. out with the old, in with the new, slay. 👑

Tk_DeleteSelHandler removes the handler given by tkwin, selection, and target, if such a handler exists. and if there is no such handler? it has no effect. it's unbothered, it's unshaken, it simply does nothing. 🧚

---

🌈 KEYWORDS 🌈

format, handler, selection, target

---

okay that's the whole page bestie, you're officially selection-handler literate 💖 this was Tk, version 4.0, and yeah we are absolutely iconic for making it to the end together. mwah. 💅✨