Tk_RestrictEvents(3tk)

✨ NAME ✨

Tk_RestrictEvents — bestie, this is the one that filters X events and selectively delays them 💅 (yes it's in the Tk Library Procedures collection, you found the right page 🎀)

---

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_RestrictProc *
Tk_RestrictEvents(proc, arg, prevArgPtr)

---

🦋 ARGUMENTS 🦋

• Tk_RestrictProc *proc (in) — the predicate procedure you call to filter incoming X events. If it's NULL, that means don't restrict events at all, we're just vibing 🫶
• void *arg (in) — whatever arbitrary argument you wanna pass to proc.
• void **prevArgPtr (out) — a pointer to the place where the argument to the previous restrict procedure gets saved.

---

💖 DESCRIPTION 💖

Okay so this procedure is a lifesaver in those specific situations where your app is literally only prepared to receive certain X events and nothing else, no cap.

Once you call Tk_RestrictEvents, then Tcl_DoOneEvent (and therefore Tk_MainLoop, since it rides along) will run X input events through proc as a filter ✨. And proc gets to decide whether a given event is:

• processed immediately,
• deferred until some later time (like, say, when the event restriction gets lifted 👋), or
• straight up discarded 💀

proc is a procedure whose arguments and result match the type Tk_RestrictProc:

typedef Tk_RestrictAction Tk_RestrictProc(
        void *arg,
        XEvent *eventPtr);

The arg argument is a copy of the arg you passed to Tk_RestrictEvents — it's there so you can hand proc whatever info it needs to do its filtering job. The eventPtr points to the event currently under consideration 👀. And proc returns a restrict action (that's the enumerated type Tk_RestrictAction) telling Tcl_DoOneEvent what it should do with the event:

• If the return value is TK_PROCESS_EVENT, the event gets handled immediately. slay, it goes through 🔥
• If the return value is TK_DEFER_EVENT, the event gets left on the event queue for later processing. it's not gone, just on pause ⏳
• If the return value is TK_DISCARD_EVENT, the event gets removed from the event queue and discarded without ever being processed. bye bestie 👋💀

Tk_RestrictEvents uses its return value and prevArgPtr to hand back info about the current event restriction procedure — and a NULL return value means there are currently no restrictions at all. Keep these values around, because they're exactly what you use to restore the previous restriction state once you no longer need the current restriction 🫶

real talk though: there are very few places where Tk_RestrictEvents is actually needed.

In most cases, the best way to restrict events is by changing the bindings with the bind Tcl command, or by calling Tk_CreateEventHandler and Tk_DeleteEventHandler from C 💅. The main place where Tk_RestrictEvents must be used is when you're performing synchronous actions — like, for example, if you need to wait for a particular event to occur on a particular window, but you do not want to invoke any handlers for any other events. very specific, very demure.

And yeah, the "obvious" solution in those situations is to call XNextEvent or XWindowEvent... but nope, those procedures cannot be used, because Tk keeps its own event queue that is separate from the X event queue 😭. So instead: call Tk_RestrictEvents to set up a filter, then call Tcl_DoOneEvent to retrieve the desired event(s). periodt.

---

👑 KEYWORDS 👑

delay, event, filter, restriction

---

k that's the whole page bestie, go forth and filter those events 🌈💜 — this was the Tk_RestrictEvents(3tk) page from the Tk manual set, mwah 🎀✨