Tk_Create...ageHandler(3tk)

💖 Tk_Create...ageHandler — Tk Library Procedures 💖

okay bestie, sit down, hydrate, and let's talk about the two little functions in the Tk library that let you hook your own callback onto ClientMessage type X events. This is Tk_CreateClientMessageHandler and Tk_DeleteClientMessageHandler, and honestly? They're giving "I watch every X event that comes through" main character energy. 👑

---

✨ NAME ✨

Tk_CreateClientMessageHandler</p>, Tk_DeleteClientMessageHandler</p> — the way these two literally just associate a procedure callback with ClientMessage type X events. That's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_CreateClientMessageHandler(proc)

Tk_DeleteClientMessageHandler(proc)

---

🎀 ARGUMENTS 🎀

• Tk_ClientMessageProc *proc (in) — the procedure you want invoked whenever a ClientMessage X event pops off on any display. Any display!! She's everywhere. 👀

---

💅 DESCRIPTION 💅

So Tk_CreateClientMessageHandler arranges for proc to be invoked in the future whenever a ClientMessage X event occurs that is not handled by WM_PROTOCOL. No cap. And lowkey, Tk_CreateClientMessageHandler is intended for use by applications that need to watch X ClientMessage events — think drag and drop applications, the ones that are always doing the most. 🫶

The callback to proc will be made by Tk_HandleEvent. Important caveat bestie: this mechanism only works in programs that dispatch events through Tk_HandleEvent (or through other Tk procedures that call Tk_HandleEvent, such as Tcl_DoOneEvent or Tk_MainLoop). So if you're not dispatching through those, this whole thing is not giving anything. 💀

proc should have arguments and result that match the type Tk_ClientMessageProc:

typedef int Tk_ClientMessageProc(
        Tk_Window tkwin,
        XEvent *eventPtr);

The tkwin parameter to proc is the Tk window which is associated with this event. And eventPtr is a pointer to the X event. Simple. Iconic. ✨

Whenever an X ClientMessage event is processed by Tk_HandleEvent, the proc is called if it was not handled as a WM_PROTOCOL. The return value from proc is normally 0. A non-zero return value indicates that the event is not to be handled further — that is, proc has done all processing that is to be allowed for the event. She said "I'm done here, no more handlers, periodt." 💅

If there are multiple ClientMessage event handlers, each one is called for each event, in the order in which they were established. First come, first served, fr fr. 🌈

Tk_DeleteClientMessageHandler may be called to delete a previously-created ClientMessage event handler: it deletes each handler it finds that matches the proc argument. If no such handler exists, then Tk_DeleteClientMessageHandler returns without doing anything. No drama, no error, just vibes. 🧚

⚠️ And now the warning, bestie, listen up: although Tk supports it, it's probably a bad idea to have more than one callback with the same proc argument. Like, technically allowed, but it's giving chaos and you will not enjoy the consequences. 🙈

---

🔥 KEYWORDS 🔥

bind, callback, event, handler

---

and that's the whole page, babe — every flag, every type, every caveat, nothing skipped. you're welcome. 💜

mwah 💋 this was brought to you by Tk 8.4, source version of the same name, and the manual page Tk_Create...ageHandler(3tk) — go forth and handle those events, queen. 👑✨