Tk_CreateC...sageHandler(3)

💖 NAME 💖

Okay so welcome to the Tk Library Procedures page for Tk_CreateC...sageHandler(3), bestie — the title is cursed-cute but the content is solid.

• Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler — associate procedure callback with ClientMessage type X events. 💅

---

✨ SYNOPSIS ✨

#include <tk.h>

Tk_CreateClientMessageHandler(proc)

Tk_DeleteClientMessageHandler(proc)

---

🎀 ARGUMENTS 🎀

• Tk_ClientMessageProc *proc (in) — procedure to invoke whenever a ClientMessage X event occurs on any display.

---

🦋 DESCRIPTION 🦋

So Tk_CreateClientMessageHandler sets things up so that proc gets invoked later, whenever a ClientMessage X event happens and it is not handled by WM_PROTOCOL. It's literally made for apps that need to watch X ClientMessage events — drag-and-drop apps, iykyk.

The callback to proc gets made by Tk_HandleEvent. Big caveat: this mechanism only works in programs that dispatch events through Tk_HandleEvent — or through other Tk procedures that call Tk_HandleEvent, like Tcl_DoOneEvent or Tk_MainLoop.

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 associated with this event. eventPtr is a pointer to the X event.

Whenever an X ClientMessage event is processed by Tk_HandleEvent, proc gets called if it wasn't handled as a WM_PROTOCOL. The return value from proc is normally 0. A non-zero return value means the event is not to be handled further — that is, proc has done all the processing that's allowed for the event. 🫶

If there are multiple ClientMessage event handlers, each one is called for each event, in the order in which they were established. Periodt.

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.

🌸 Tk does support having more than one callback with the same proc argument, but it's probably a bad idea. Not me warning you or anything. Just... don't.

---

👑 KEYWORDS 👑

• bind
• callback
• event
• handler

---

That's the whole page from the Tk 8.4 manual, bestie — source/version is Tk 8.4, the footer didn't list a date, and the title is Tk_CreateC...sageHandler(3) 💜✨