XGRABDEVICEKEY(3)

📦
version 1.8.3 · 6 versions
, in fedora 44

💅 XGRABDEVICEKEY — grab & ungrab extension input device Keys 💅

okay so bestie, this is the XGRABDEVICEKEY(3) page from the XInput crew, and it's literally all about snatching up keyboard-ish keys on extension input devices. two functions, one mission: XGrabDeviceKey and XUngrabDeviceKey — grab/ungrab extension input device Keys. no cap. ✨

✨ SYNOPSIS ✨

first things first, you gotta bring in the header, periodt:

#include <X11/extensions/XInput.h>

then here's the grab one 🫶:

int XGrabDeviceKey( Display *display,
                    XDevice *device,
                    unsigned int key,
                    unsigned int modifiers,
                    XDevice *modifier_device,
                    Window grab_window,
                    Bool owner_events,
                    unsigned int event_count,
                    XEventClass *event_list,
                    int this_device_mode,
                    int other_devices_mode);

and the ungrab one, the lil release valve 🌸:

int XUngrabDeviceKey( Display *display,
                      XDevice *device,
                      unsigned int key,
                      unsigned int modifiers,
                      XDevice *modifier_device,
                      Window grab_window);

🎀 the arguments, explained like ur bestie would 🎀

  • display — the connection to the X server, obvi. it's giving "hi yes hello i'd like to talk to the server please".
  • device — which device is getting grabbed or released. main character identified. 👑
  • Key — the device Key that's getting grabbed or released, or AnyKey if you're feeling chaotic.
  • modifiers — the set of keymasks, or AnyModifier. the mask is the bitwise inclusive OR of the valid keymask bits, and the valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. yes, all eight, write them down. ✨
  • modifier_device — the device whose modifiers are gonna be used. if you pass NULL here, the X keyboard gets used as the modifier_device instead. lowkey a glow-up from nothing. 🦋
  • grab_window — the grab window. that's the whole vibe.
  • owner_events — a Boolean value saying whether the device events get reported as usual, or reported with respect to the grab window if the event list selects them. pick ur fighter. 💅
  • event_count — how many event classes live in the event list. counting is caring.
  • event_list — which device events get reported back to the client. yes queen, tell me everything.
  • this_device_mode — further processing of events from this device. you can pass GrabModeSync or GrabModeAsync.
  • other_devices_mode — further processing of events from other devices. you can also pass GrabModeSync or GrabModeAsync. equality, we love to see it. 🌈

🌸 DESCRIPTION 🌸

so, the XGrabDeviceKey request establishes a passive grab. iconic behaviour. in the future, the device gets actively grabbed — exactly like XGrabDevice does it — the last-device-grab time is set to the time at which the Key was pressed (as transmitted in the DeviceKeyPress event), and the DeviceKeyPress event is reported if all of these conditions are true, bestie, and i mean all of them:

  • The device is not grabbed, and the specified key is logically pressed when the specified modifier keys are logically down, and no other keys or modifier keys are logically down.
  • The grab_window is an ancestor (or is) the focus window OR the grab window is a descendant of the focus window and contains the device.
  • The confine_to window (if any) is viewable.
  • A passive grab on the same key/modifier combination does not exist on any ancestor of grab_window.

the interpretation of the remaining arguments is as for XGrabDevice. the active grab is terminated automatically when the logical state of the device has the specified key released. bye girl 👋

ngl, important tea: the logical state of a device (as seen by means of the X protocol) may lag the physical state if device event processing is frozen. so don't come for it when it's behind. 😭

if the key is not AnyKey, it must be in the range specified by min_keycode and max_keycode as returned by the XListInputDevices request. otherwise, a BadValue error results. 🚨

this request overrides all previous grabs by the same client on the same Key/modifier combinations on the same window. a modifier of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). it is not required that all modifiers specified have currently assigned KeyCodes. a key of AnyKey is equivalent to issuing the request for all possible keys. otherwise, it is not required that the specified key currently be assigned to a physical Key.

if a modifier_device of NULL is specified, the X keyboard will be used as the modifier_device.

if some other client has already issued a XGrabDeviceKey with the same Key/modifier combination on the same window, a BadAccess error results. when using AnyModifier or AnyKey, the request fails completely, and a BadAccess error results — and bestie, no grabs are established — if there is a conflicting grab for any combination. XGrabDeviceKey has no effect on an active grab. it said what it said. 💀

XGrabDeviceKey can generate BadAccess, BadClass, BadDevice, BadMatch, BadValue, and BadWindow errors. it returns Success on successful completion of the request. slay. ✨

now for the un-grab, the "we're so over" era 🦋:

the XUngrabDeviceKey request releases the passive grab for a key/modifier combination on the specified window if it was grabbed by this client. a modifier of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. a Key of AnyKey is equivalent to issuing the request for all possible Keys. XUngrabDeviceKey has no effect on an active grab.

if a modifier_device of NULL is specified, the X keyboard will be used as the modifier_device.

XUngrabDeviceKey can generate BadDevice, BadMatch, BadValue and BadWindow errors.

🚨 DIAGNOSTICS 🚨

like, the error messages. read them, learn them, love them.

  • BadDevice — an invalid device was specified. the specified device does not exist, or has not been opened by this client via XOpenInputDevice. this error may also occur if the specified device is the X keyboard or X pointer device. rude of it, honestly.
  • BadMatch — this error may occur if an XGrabDeviceKey request was made specifying a device that has no keys, or a modifier device that has no keys. no keys, no vibes. 🙈
  • BadValue — some numeric value falls outside the range of values accepted by the request. unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. any argument defined as a set of alternatives can generate this error. it's giving "pick better numbers bestie".
  • BadWindow — a value for a Window argument does not name a defined Window. that window is not a real one, babe. 💀

👀 SEE ALSO 👀

go read these next, they're all part of the same friend group:

and that's the whole page, pookie!! 🫶 this lil legend is from the XGRABDEVICEKEY(3) manual, dated 05/18/2026 — shoutout to whoever wrote it, ate and left no crumbs. go grab some keys, go release some keys, and remember: logical state may lag, but ur potential never does. mwah 💖✨

📦 where this page comes from