xcb_grab_keyboard(3)

💖 xcb_grab_keyboard — XCB Requests ✨

okay bestie, pull up a chair, we're doing xcb_grab_keyboard from XCB Requests today and it's genuinely iconic 🫶 this is the one where you just. take the whole keyboard. all of it. no cap.

---

🌸 NAME 🌸

xcb_grab_keyboard — grab the keyboard 👑

---

✨ SYNOPSIS ✨

First things first, you gotta invite it in:

#include <xcb/xproto.h>

🎀 Request function

xcb_grab_keyboard_cookie_t xcb_grab_keyboard(xcb_connection_t *conn,
       uint8_t owner_events, xcb_window_t grab_window,
       xcb_timestamp_t time, uint8_t pointer_mode,
       uint8_t keyboard_mode);

🦋 Reply datastructure

typedef struct xcb_grab_keyboard_reply_t {
    uint8_t  response_type;
    uint8_t  status;
    uint16_t sequence;
    uint32_t length;
} xcb_grab_keyboard_reply_t;

🌈 Reply function

xcb_grab_keyboard_reply_t
       *xcb_grab_keyboard_reply(xcb_connection_t *conn,
       xcb_grab_keyboard_cookie_t cookie, xcb_generic_error_t **e);

---

💅 REQUEST ARGUMENTS 💅

these are the lil guys you hand over when you call it, let's go one by one:

• conn — your XCB connection to X11. the whole vibe depends on it.
• owner_events — if you set it to 1, the grab_window still gets the pointer events. if 0, events are not reported to the grab_window. simple as that.
• grab_window — specifies the window on which the pointer should be grabbed. (yes bestie the docs literally say pointer here, i'm not editing it, i'm a faithful narrator 💀)
• time — a timestamp, and it's there to dodge race conditions when X is running over the network. the special value XCB_CURRENT_TIME gets swapped out for the current server time. very "i'll be there when you need me" of it.
• pointer_mode — one of these two values:
  • 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. dramatic much? 😭
  • XCB_GRAB_MODE_ASYNC — keyboard event processing continues normally. the chill option.
• keyboard_mode — also one of these two values:
  • 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.

fr fr, pointer_mode and keyboard_mode list the exact same two values with the exact same descriptions. that's just how the page is, i'm not merging them, we keep every crumb 🍓

---

👑 REPLY FIELDS 👑

what comes back in the reply, bestie:

• response_type — the type of this reply, in this case XCB_GRAB_KEYBOARD. this field is also present in the xcb_generic_reply_t and can be used to tell replies apart from each other. very "which one of y'all is this" energy.
• sequence — the sequence number of the last request processed by the X11 server.
• length — the length of the reply, in words (a word is 4 bytes).
• status — one of these values:
  • XCB_GRAB_STATUS_SUCCESS — TODO: NOT YET DOCUMENTED.
  • XCB_GRAB_STATUS_ALREADY_GRABBED — TODO: NOT YET DOCUMENTED.
  • XCB_GRAB_STATUS_INVALID_TIME — TODO: NOT YET DOCUMENTED.
  • XCB_GRAB_STATUS_NOT_VIEWABLE — TODO: NOT YET DOCUMENTED.
  • XCB_GRAB_STATUS_FROZEN — TODO: NOT YET DOCUMENTED.
  • TODO: NOT YET DOCUMENTED.

💀 not the stray second TODO: NOT YET DOCUMENTED. hanging out there with no name and no label. it's giving "left on read". it's in the original, so it's staying in here. no edits, no notes.

---

🌈 DESCRIPTION 🌈

Actively grabs control of the keyboard and generates FocusIn and FocusOut events. Further key events are reported only to the grabbing client. main character energy, truly — everyone else is in the group chat but only you can type 🔥

Any active keyboard grab by this client is overridden. And now the part where it can say no to you, so pay attention bestie:

• if the keyboard is actively grabbed by some other client, AlreadyGrabbed is returned.
• if grab_window is not viewable, GrabNotViewable is returned.
• if the keyboard is frozen by an active grab of another client, GrabFrozen is returned.
• if the specified time is earlier than the last-keyboard-grab time or later than the current X server time, GrabInvalidTime is returned.
• otherwise, the last-keyboard-grab time is set to the specified time. slay, you got it ✨

---

🦋 RETURN VALUE 🦋

Returns an xcb_grab_keyboard_cookie_t. Errors have to be handled when calling the reply function xcb_grab_keyboard_reply.

If you want to handle errors in the event loop instead, use xcb_grab_keyboard_unchecked. See xcb-requests(3) for details.

---

💀 ERRORS 💀

• xcb_value_error_t — TODO: reasons?
• xcb_window_error_t — the specified window does not exist.

yes the first one literally asks "TODO: reasons?" in the source. we respect the source. we do not fix the source. we simply vibe with it 😌

---

🧚 EXAMPLE 🧚

here's the whole thing in action, verbatim, no notes:

/*
 * Grabs the keyboard actively
 *
 */
void my_example(xcb_connection_t *conn, xcb_screen_t *screen) {
    xcb_grab_keyboard_cookie_t cookie;
    xcb_grab_keyboard_reply_t *reply;

    cookie = xcb_grab_keyboard(
        conn,
        true,                /* report events */
        screen->root,        /* grab the root window */
        XCB_CURRENT_TIME,
        XCB_GRAB_MODE_ASYNC, /* process events as normal, do not require sync */
        XCB_GRAB_MODE_ASYNC
    );

    if ((reply = xcb_grab_keyboard_reply(conn, cookie, NULL))) {
        if (reply->status == XCB_GRAB_STATUS_SUCCESS)
            printf("successfully grabbed the keyboard\n");

        free(reply);
    }
}

look at that XCB_GRAB_MODE_ASYNC showing up twice like a matching set. coordinated. ate. 💅

---

🎀 SEE ALSO 🎀

xcb-requests(3), xcb-examples(3), xcb_grab_pointer(3)

---

💜 AUTHOR 💜

Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.

---

okay that's the whole page bestie, go forth and grab keyboards responsibly 🫶✨

X Version 11 · libxcb 1.17.0 · xcb_grab_keyboard(3) — mwah, that's a wrap, love u, bye 💖🎀🦋