XIGRABBUTTON(3)

📦

version 1.8.3 · 6 versions

💖 XIGRABBUTTON 💖

okay bestie, sit down, hydrate, because this is XIGRABBUTTON(3) and it's the manual page for the entire grab-and-ungrab girl gang. if you've ever wanted to snatch a button press, a keycode, a touch, a pinch or a swipe and hold it hostage (lovingly), this is your page. no cap.

✨ NAME ✨

XIGrabButton, XIUngrabButton, XIGrabKeycode, XIUngrabKeycode, XIGrabTouchBegin, XIUngrabTouchBegin, XIGrabPinchGestureBegin, XIUngrabPinchGestureBegin, XIGrabSwipeGestureBegin — literally all of them are here to grab/ungrab buttons or keys. that's the whole vibe. grabbing. ungrabbing. iconic behavior. 💅

🌸 SYNOPSIS 🌸

first things first, you gotta bring in the header:

#include <X11/extensions/XInput2.h>

and now, the whole cast of characters, exactly as they appear:

int XIGrabButton( Display *display,
                  int deviceid,
                  int button,
                  Window grab_window,
                  Cursor cursor,
                  int grab_mode,
                  int paired_device_mode,
                  Bool owner_events,
                  XIEventMask *mask,
                  int num_modifiers,
                  XIGrabModifiers *modifiers_inout);

int XIUngrabButton( Display *display,
                    int deviceid,
                    int button,
                    Window grab_window,
                    int num_modifiers,
                    XIGrabModifiers *modifiers);

int XIGrabKeycode( Display *display,
                   int deviceid,
                   int keycode,
                   Window grab_window,
                   int grab_mode,
                   int paired_device_mode,
                   Bool owner_events,
                   XIEventMask *mask,
                   int num_modifiers,
                   XIGrabModifiers *modifiers_inout);

int XIUngrabKeycode( Display *display,
                     int deviceid,
                     int keycode,
                     Window grab_window,
                     int num_modifiers,
                     XIGrabModifiers *modifiers);

int XIGrabTouchBegin( Display *display,
                      int deviceid,
                      Window grab_window,
                      Bool owner_events,
                      XIEventMask *mask,
                      int num_modifiers,
                      XIGrabModifiers *modifiers_inout);

int XIUngrabTouchBegin( Display *display,
                        int deviceid,
                        Window grab_window,
                        int num_modifiers,
                        XIGrabModifiers *modifiers);

int XIGrabPinchGestureBegin( Display* display,
                             int deviceid,
                             Window grab_window,
                             int grab_mode,
                             int paired_device_mode,
                             int owner_events,
                             XIEventMask *mask,
                             int num_modifiers,
                             XIGrabModifiers *modifiers_inout);

int XIUngrabPinchGestureBegin( Display* display,
                               int deviceid,
                               Window grab_window,
                               int num_modifiers,
                               XIGrabModifiers *modifiers);

int XIGrabSwipeGestureBegin( Display* display,
                             int deviceid,
                             Window grab_window,
                             int grab_mode,
                             int paired_device_mode,
                             int owner_events,
                             XIEventMask *mask,
                             int num_modifiers,
                             XIGrabModifiers *modifiers_inout);

int XIUngrabSwipeGestureBegin( Display* display,
                               int deviceid,
                               Window grab_window,
                               int num_modifiers,
                               XIGrabModifiers *modifiers);

🎀 the arguments, one by one 🎀

display — the connection to the X server. your link to the mothership, bestie.
device — which device is getting grabbed or released.
button — the device button that's getting grabbed or released, or XIAnyButton if you're feeling chaotic (but in a correct way).
keycode — the keycode that's getting grabbed or released, or XIAnyKeycode.
num_modifiers — how many elements are chillin' inside modifiers or modifiers_inout.
modifiers — the set of latched and base modifiers you wanna ungrab, or XIAnyModifier. the data type is like that for consistency with the respective grab request, and heads up: the status code of the XIGrabModifiers struct is ignored here. we don't look at it. it's not relevant. moving on.
modifiers_inout — the set of latched and base modifiers you wanna grab, or XIAnyModifier. and it's an inout, so it also hands back the modifiers that could not be grabbed, plus their error code. it's giving "receipts".
grab_window — the grab window. that's it. that's the whole description. 🫶
owner_events — a Boolean that says whether the events are reported as usual, or reported with respect to the grab window.
mask — the event mask.
grab_mode — further processing of events from this device. you can pass XIGrabModeSync or XIGrabModeAsync.
paired_device_mode — further processing of events from the paired master device. you can pass XIGrabModeSync or XIGrabModeAsync. but — if deviceid specifies a floating slave device, this parameter is straight up ignored. it said "not my problem" and went back to sleep. 😴

🦋 DESCRIPTION 🦋

okay so XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin, XIGrabSwipeTouchBegin establish a passive grab. (yes, XIGrabSwipeTouchBegin — that's what the page says, don't @ me.)

the modifier device for a button grab is the paired master device if deviceid specifies a master pointer. otherwise, the modifier device is the device specified with deviceid. slay.

so in the future, the device gets actively grabbed (as for XIGrabDevice), the last-grab time is set to the time at which the button or keycode was pressed, and the XI_ButtonPress or XI_KeyPress event is reported — if and only if all of the following conditions are true:

the device is not grabbed, and the specified button or keycode is logically pressed, a touch or a gesture event occurs when the specified modifier keys are logically down on the modifier device, and no other buttons or modifier keys are logically down.
either the grab window is an ancestor of (or is) the focus window, OR the grab window is a descendent of the focus window and contains the device.
a passive grab on the same button/modifier combination does not exist on any ancestor of grab_window.

the interpretation of the remaining arguments is as for XIGrabDevice. the active grab is terminated automatically when the logical state of the device has all buttons or keys released — independent of the logical state of the modifier keys. so like, you let go, and the grab is out. bye bestie. 👋

if the device is an attached slave device, the device is automatically detached from the master device when the grab activates, and reattached to the same master device when the grab deactivates. and if the master device is removed while the device is floating as a result of a grab, the device stays floating once the grab deactivates. it's not coming back. it chose freedom. 🦋

⚠️ note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen. so like, the vibes are delayed. not a bug, just physics.

this request overrides all previous grabs by the same client on the same button/modifier or keycode/modifier combinations on the same window. a modifiers of XIAnyModifier 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 button of XIAnyButton is equivalent to issuing the request for all possible buttons. otherwise, it is not required that the specified button currently be assigned to a physical button. the bar is on the floor and we're thriving. 💅

🚨 if some other client has already issued a XIGrabButton or XIGrabKeycode with the same button/modifier or keycode/modifier combination on the same window, a BadAccess error results. when using XIAnyModifier or XIAnyButton, the request fails completely, and a XIBadAccess error results (no grabs are established) if there is a conflicting grab for any combination. all-or-nothing, bestie. XIGrabButton and XIGrabKeycode have no effect on an active grab.

on success, XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return 0. ✨

if one or more modifier combinations could not be grabbed, XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return the number of failed combinations, and modifiers_inout contains the failed combinations and their respective error codes. it's giving "here's what I couldn't do and exactly why".

XIGrabButton, XIGrabKeycode, XIGrabTouchBegin, XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin can generate BadClass, BadDevice, BadMatch, BadValue, and BadWindow errors.

XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin, XIUngrabPinchGestureBegin and XIUngrabSwipeGestureBegin release the passive grab for a button/modifier, keycode/modifier or touch/modifier combination on the specified window — but only if it was grabbed by this client. you can't release somebody else's grab, that's not your business. 🙈

a modifier of XIAnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. a button of XIAnyButton is equivalent to issuing the request for all possible buttons. XIUngrabButton and XIUngrabKeycode have no effect on an active grab. periodt.

XIUngrabButton, XIUngrabKeycode, XIUngrabTouchBegin, XIUngrabPinchGestureBegin and XIUngrabSwipeGestureBegin can generate BadDevice, BadMatch, BadValue and BadWindow errors.

⭐ RETURN VALUE ⭐

XIGrabButton, XIGrabKeycode, XIGrabTouchBegin and XIGrabPinchGestureBegin and XIGrabSwipeGestureBegin return the number of modifier combination that could not establish a passive grab. (yes, "combination", singular — that's the page, love her.) the modifiers are returned in modifiers_inout, along with the respective error for this modifier combination. if XIGrabButton, XIGrabKeycode or XIGrabTouchBegin return zero, then passive grabs with all requested modifier combinations were established successfully. zero equals flawless. 👑

💖 DIAGNOSTICS 💖

okay bestie, so when things go wrong, X hands you one of these errors. read them like a vibe check for your request 🌸

🚫 BadDevice

An invalid deviceid was specified. not the device you thought, not the device we got. tragic, honestly. 💀

💔 BadMatch

This error may occur if XIGrabButton specified a device that has no buttons, or XIGrabKeycode specified a device that has no keys, or XIGrabTouchBegin specified a device that is not touch-capable, or XIGrabPinchGestureBegin specified a device that is not gesture-capable, or XIGrabSwipeGestureBegin specified a device that is not gesture-capable.

like… you asked a device to do a thing it literally does not have the parts for. no buttons? no keys? not touchy? not gesture-y? that's a BadMatch, and it's giving "wrong device, bestie". 😭

🔢 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.

translation: the number you sent? out of pocket. out of range. not invited to this party. ✨

🪟 BadWindow

A value for a Window argument does not name a defined Window. that window is not a real window. it's giving "nonexistent". 🫶

🐛 BUGS 🐛

listen up, this one matters 👑

The protocol headers for XI 2.0 did not provide XIGrabModeAsync or XIGrabModeSync. Use GrabModeSync and GrabModeAsync instead, respectively.

so yeah — those two names straight up were not in the XI 2.0 protocol headers. swap them in the order listed and you're golden. lowkey iconic that the workaround is just the older names. 💅

👀 SEE ALSO 👀

XIAllowEvents(3) — go read that one next, bestie, it's the whole other half of this story 🌈

and that's the page, fr fr 💜 this was XIGRABBUTTON(3) from the 05/18/2026 drop — go forth and grab buttons responsibly, mwah 🎀✨

📦 where this page comes from

fedora 44: libXi-devel 1.8.3-1.fc44 · MIT-open-group AND SMLNJ AND MIT
fedora 44: libXi-devel 1.8.3-1.fc44 · MIT-open-group AND SMLNJ AND MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms