xcb_grab_button(3)

✨ NAME ✨

xcb_grab_button — grab pointer button(s) 🖱️👑

okay so real talk, bestie: this is the page for xcb_grab_button(3), straight outta the XCB Requests manual, and it's about telling the X server "hey, when someone clicks like this, on this window, with these keys held, I want in on that." passive grab city. let's get into it 💅

---

🌸 SYNOPSIS 🌸

#include <xcb/xproto.h>

Request function

xcb_void_cookie_t xcb_grab_button(xcb_connection_t *conn,
       uint8_t owner_events, xcb_window_t grab_window,
       uint16_t event_mask, uint8_t pointer_mode, uint8_t keyboard_mode,
       xcb_window_t confine_to, xcb_cursor_t cursor, uint8_t button,
       uint16_t modifiers);

---

🎀 REQUEST ARGUMENTS 🎀

• conn — your XCB connection to X11. the whole line to the server, periodt.
• owner_events — if it's 1, the grab_window is still gonna get the pointer events. if it's 0, events do not get reported to the grab_window. that's it, that's the whole bit 🫶
• grab_window — the window where you want the pointer grabbed. the main character of this whole operation.
• event_mask — which pointer events get reported to the client.

TODO: which values? 😭 yeah the page literally says that, bestie, we don't know either.

• pointer_mode — one of these:
  • XCB_GRAB_MODE_SYNC — the state of the keyboard appears to freeze: no further keyboard events are generated by the server until the grabbing client issues a releasing AllowEvents request or until the keyboard grab is released. 🥶
  • XCB_GRAB_MODE_ASYNC — keyboard event processing continues normally. as you were ✨
• keyboard_mode — one of these:
  • XCB_GRAB_MODE_SYNC — the state of the keyboard appears to freeze: no further keyboard events are generated by the server until the grabbing client issues a releasing AllowEvents request or until the keyboard grab is released.
  • XCB_GRAB_MODE_ASYNC — keyboard event processing continues normally.

not me noticing both modes are described with the exact same keyboard-flavored text 🙈 that's genuinely what the page says, so that's what you get. keeping the facts, keeping the vibes.

• confine_to — the window you wanna confine the pointer in (so the user literally cannot move the pointer out of that window 🔒). the special value XCB_NONE means don't confine the pointer at all — free range pointer, let it roam 🦋
• cursor — the cursor that should be displayed, or XCB_NONE to not change the cursor.
• button — one of these:
  • XCB_BUTTON_INDEX_ANY — any of the following (or none):
  • XCB_BUTTON_INDEX_1 — the left mouse button.
  • XCB_BUTTON_INDEX_2 — the right mouse button.
  • XCB_BUTTON_INDEX_3 — the middle mouse button.
  • XCB_BUTTON_INDEX_4 — scroll wheel. TODO: direction? 🤔
  • XCB_BUTTON_INDEX_5 — scroll wheel. TODO: direction? 🤔

yeah, 4 and 5 are both scroll wheel and the page is like "TODO: direction?" — iconically unhelpful, we're just reporting it fr fr.

• modifiers — the modifiers to grab. using the special value XCB_MOD_MASK_ANY means grab the pointer with all possible modifier combinations. every single one. all of them. 💀

---

💜 DESCRIPTION 💜

so this request establishes a passive grab. the pointer gets actively grabbed as described in GrabPointer, the last-pointer-grab time is set to the time at which the button was pressed (as transmitted in the ButtonPress event), and the ButtonPress event is reported if all of the following conditions are true:

• The pointer is not grabbed and the specified button is logically pressed when the specified modifier keys are logically down, and no other buttons or modifier keys are logically down.
• The grab-window contains the pointer.
• The confine-to window (if any) is viewable.
• A passive grab on the same button/key combination does not exist on any ancestor of grab-window.

the interpretation of the remaining arguments is the same as for GrabPointer. 👑

the active grab is terminated automatically when the logical state of the pointer has all buttons released, independent of the logical state of modifier keys. note that the logical state of a device (as seen by means of the protocol) may lag the physical state if device event processing is frozen. 🧊

this request overrides all previous passive grabs by the same client on the same button/key combinations on the same window.

a modifier of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). it is not required that all specified modifiers have currently assigned keycodes.

a button of AnyButton is equivalent to issuing the request for all possible buttons. otherwise, it is not required that the button specified currently be assigned to a physical button.

⚠️ the drama part: an Access error is generated if some other client has already issued a GrabButton request with the same button/key combination on the same window. when using AnyModifier or AnyButton, the request fails completely (no grabs are established at all, zero, nada 😭), and an Access error is generated if there is a conflicting grab for any combination. also — the request has no effect on an active grab. so yeah, know that before you go grabbing, bestie.

---

🌈 RETURN VALUE 🌈

returns an xcb_void_cookie_t. errors (if any) have to be handled in the event loop.

if you wanna handle errors directly with xcb_request_check instead, use xcb_grab_button_checked. see xcb-requests(3) for details. 🫡

---

🍓 ERRORS 🍓

• xcb_access_error_t — another client has already issued a GrabButton with the same button/key combination on the same window. rude, honestly.
• xcb_cursor_error_t — the specified cursor does not exist. 💀
• xcb_value_error_t — TODO: reasons? 🤷‍♀️ (again, the page's words, not ours)
• xcb_window_error_t — the specified window does not exist.

---

🦋 SEE ALSO 🦋

• xcb-requests(3)

---

🧚 AUTHOR 🧚

generated from xproto.xml. contact xcb@lists.freedesktop.org for corrections and improvements. 📧

---

and that's the whole page, bestie, we ate and left no crumbs ✨ this was xcb_grab_button(3) from the XCB Requests manual, brought to you by X Version 11 and libxcb 1.17.0. go forth and grab those buttons responsibly, ily 💖👑🌈