Tk_Grab(3tk)

✨ NAME ✨

Tk_Grab, Tk_Ungrab — the two functions that let you mess with grab state inside an application. This is from the Tk library procedures crew, bestie 💅

---

🎀 SYNOPSIS 🎀

#include <tk.h>

int
Tk_Grab(interp, tkwin, grabGlobal)

Tk_Ungrab(tkwin)

---

🫶 ARGUMENTS 🫶

• Tcl_Interp *interp (in) — the interpreter you wanna use for error reporting. She's the one who holds the receipts when stuff goes wrong.
• Tk_Window tkwin (in) — the window on whose behalf the pointer is getting grabbed or released. Main character window energy, honestly.
• int grabGlobal (in) — a Boolean, so it's giving yes/no. Tells you whether the grab is global or application local.

---

💖 DESCRIPTION 💖

Okay so these functions are how you set or release a global grab or an application local grab. Periodt.

When a grab is set on a particular window in a Tk application, mouse and keyboard events can only be received by that window and its descendants. Everything else is literally shut out. Mouse and keyboard events for windows outside the tree rooted at tkwin get redirected to tkwin.

And here's the tea on the two flavors:

• If the grab is global, then all mouse and keyboard events for windows outside the tree rooted at tkwin — even the ones intended for windows in other applications — get redirected to tkwin. No cap.
• If the grab is application local, only mouse and keyboard events intended for windows within the same application (but outside the tree rooted at tkwin) get redirected. So she's keeping it in-house 🏠

---

🌸 Tk_Grab 🌸

Tk_Grab sets a grab on a particular window. Tkwin specifies the window on whose behalf the pointer is to be grabbed. GrabGlobal indicates whether the grab should be global or application local — if it is non-zero, that means the grab should be global.

Normally, Tk_Grab returns TCL_OK. But if an error occurs and the grab cannot be set, TCL_ERROR is returned and an error message is left if interp's result 😭 (yes, that's what the docs say, don't come for me).

Once this call completes successfully, no window outside the tree rooted at tkwin will receive pointer- or keyboard-related events until the next call to Tk_Ungrab. And if a previous grab was in effect within the application? She gets replaced with a new one. Out with the old, in with the iconic 👑

---

🦋 Tk_Ungrab 🦋

Tk_Ungrab releases a grab on the mouse pointer and keyboard, if there is one set on the window given by tkwin. Once a grab is released, pointer and keyboard events will start being delivered to other windows again. The windows are free, bestie, they can breathe again 🌈

Heads up: the grab only goes away if there actually is a grab set on the window given by tkwin — otherwise there's nothing to release, iykyk.

---

🔥 KEYWORDS 🔥

grab, window

---

Anyway bestie, that's the whole page 💜 This was pulled straight from the Tk Library Procedures section, the page is Tk_Grab(3tk), and the source is Tk. Go forth and grab responsibly 🫶✨🎀