XtGrabKey(3)

🎀 NAME 🎀

okay bestie, welcome to the XtGrabKey page from the XT FUNCTIONS fam 💖 this is the group of Intrinsics calls that manage grabs — and there's eight of them, so buckle up:

• XtGrabKey
• XtUngrabKey
• XtGrabKeyboard
• XtUngrabKeyboard
• XtGrabButton
• XtUngrabButton
• XtGrabPointer
• XtUngrabPointer

---

✨ SYNTAX ✨

the way you pull these in, no cap:

#include <X11/Intrinsic.h>

void XtGrabKey(Widget widget, KeyCode keycode, Modifiers modifiers,
       Boolean owner_events, int pointer_mode, int keyboard_mode);

void XtUngrabKey(Widget widget, KeyCode keycode, Modifiers modifiers);

int XtGrabKeyboard(Widget widget, Boolean owner_events, int
       pointer_mode, int keyboard_mode, Time time);

void XtUngrabKeyboard(Widget widget, Time time);

void XtGrabButton(Widget widget, int button, Modifiers modifiers,
       Boolean owner_events, unsigned int event_mask, int pointer_mode,
       int keyboard_mode, Window confine_to, Cursor cursor);

void XtUngrabButton(Widget widget, unsigned button, Modifiers
       modifiers);

int XtGrabPointer(Widget widget, Boolean owner_events, unsigned int
       event_mask, int pointer_mode, int keyboard_mode, Window
       confine_to, Cursor cursor, Time time);

void XtUngrabPointer(Widget widget, Time time);

---

🌸 ARGUMENTS 🌸

• widget — this is the widget in whose window the grab goes down. Must be of class Core or a subclass thereof, fr fr, no exceptions.
• keycode
• modifiers
• owner_events
• pointer_mode
• keyboard_mode
• time
• button
• confine_to
• cursor — all of the above just specify the arguments to the associated Xlib function call. that's the whole vibe. 🫶

(yeah, one description for the whole little squad of them — they're passing the baton straight to Xlib and the docs are like "you know how Xlib works, girlie" 😭)

---

👑 DESCRIPTION 👑

🦋 XtGrabKey 🦋

so XtGrabKey calls XGrabKey, and it hands over the widget's window as the grab window — but only if the widget is realized. The remaining arguments are exactly as for XGrabKey. If the widget is not realized, or gets unrealized later, the call to XGrabKey will be performed (again) when the widget is realized and its window becomes mapped. iconic deferred behavior ✨

In the future, if XtDispatchEvent is called with a KeyPress event matching the specified keycode and modifiers (which may be AnyKey or AnyModifier, respectively) for the widget's window, the Intrinsics will call XtUngrabKeyboard with the timestamp from the KeyPress event if either of these is true:

• There is a modal cascade and the widget is not in the active subset of the cascade and the keyboard was not previously grabbed, or
• XFilterEvent returns True.

🦋 XtUngrabKey 🦋

XtUngrabKey calls XUngrabKey with the widget's window as the ungrab window — again, only if the widget is realized. The remaining arguments are exactly as for XUngrabKey. If the widget is not realized, XtUngrabKey removes a deferred XtGrabKey request, if any, for the specified widget, keycode, and modifiers. cleanup era 💅

🦋 XtGrabKeyboard 🦋

if the specified widget is realized, XtGrabKeyboard calls XGrabKeyboard with the widget's window as the grab window. The remaining arguments and return value are exactly as for XGrabKeyboard. If the widget is not realized, XtGrabKeyboard immediately returns GrabNotViewable. and listen — no future ungrab is implied by XtGrabKeyboard. periodt.

🦋 XtUngrabKeyboard 🦋

XtUngrabKeyboard calls XUngrabKeyboard with the specified time. that's it, that's the whole function, slay 🌈

🦋 XtGrabButton 🦋

XtGrabButton calls XGrabButton with the widget's window as the grab window if the widget is realized. The remaining arguments are exactly as for XGrabButton. If the widget is not realized, or is later unrealized, the call to XGrabButton will be performed (again) when the widget is realized and its window becomes mapped. same deferred glow-up as the key one 🧚

In the future, if XtDispatchEvent is called with a ButtonPress event matching the specified button and modifiers (which may be AnyButton or AnyModifier, respectively) for the widget's window, the Intrinsics will call XtUngrabPointer with the timestamp from the ButtonPress event if either of these is true:

• There is a modal cascade and the widget is not in the active subset of the cascade and the pointer was not previously grabbed, or
• XFilterEvent returns True.

🦋 XtUngrabButton 🦋

XtUngrabButton calls XUngrabButton with the widget's window as the ungrab window if the widget is realized. The remaining arguments are exactly as for XUngrabButton. If the widget is not realized, XtUngrabButton removes a deferred XtGrabButton request, if any, for the specified widget, button, and modifiers. bye bye deferred request 👋

🦋 XtGrabPointer 🦋

XtGrabPointer calls XGrabPointer with the widget's window as the grab window. The remaining arguments and return value are exactly as for XGrabPointer. If the widget is not realized, XtGrabPointer immediately returns GrabNotViewable. and heads up bestie — no future ungrab is implied by XtGrabPointer. same energy as the keyboard one, no cap 💀

🦋 XtUngrabPointer 🦋

XtUngrabPointer calls XUngrabPointer with the specified time. short, sweet, iconic. ⭐

quick vibe check: XtGrabKeyboard and XtGrabPointer are the two that bail out immediately with GrabNotViewable on an unrealized widget instead of deferring — the key and button versions are the ones that wait patiently for realization. don't mix those up, iykyk 🙈

---

🌟 SEE ALSO 🌟

• X Toolkit Intrinsics - C Language Interface
• Xlib - C Language X Interface

---

that's the whole page babes 💖 this was X Version 11, libXt 1.3.1, and you just read the XtGrabKey(3) manpage. go grab something (responsibly) 🎀✨🦋