xcb_set_input_focus(3)

💖 xcb_set_input_focus — bestie, we're setting the input focus 💖

okay so this is a page from the XCB Requests corner of the manual, and today's main character is xcb_set_input_focus(3). yes we're doing X11 protocol stuff. yes it's giving ✨keyboard authority✨. let's go.

---

🌸 NAME 🌸

xcb_set_input_focus — sets input focus 🎯

---

🦋 SYNOPSIS 🦋

#include <xcb/xproto.h>

✨ Request function ✨

xcb_void_cookie_t xcb_set_input_focus(xcb_connection_t *conn,
       uint8_t revert_to, xcb_window_t focus, xcb_timestamp_t time);

like. look at her. four little args and she controls who gets the keyboard. iconic behavior honestly 💅

---

🎀 REQUEST ARGUMENTS 🎀

• conn — the XCB connection to X11. your lil hotline to the server, bestie 🫶
• revert_to — one of the following values. this is the "what happens when things go sideways" setting, so pay attention:
  • XCB_INPUT_FOCUS_NONE — the focus reverts to XCB_NONE, so literally no window will have the input focus. nobody. zero. empty. 💀
  • XCB_INPUT_FOCUS_POINTER_ROOT — the focus reverts to XCB_POINTER_ROOT respectively. when the focus reverts, FocusIn and FocusOut events are generated, but the last-focus-change time is not changed. (not me remembering that one specific exception, but yes, noted 📝)
  • XCB_INPUT_FOCUS_PARENT — the focus reverts to the parent (or closest viewable ancestor), and the new revert_to value is XCB_INPUT_FOCUS_NONE.
  • XCB_INPUT_FOCUS_FOLLOW_KEYBOARD — NOT YET DOCUMENTED. only relevant for the xinput extension. (mystery queen. we don't know her. 🔮)

so basically revert_to specifies what happens when the focus window becomes unviewable (that's if focus is neither XCB_NONE nor XCB_POINTER_ROOT).

• focus — the window to focus. all keyboard events will be reported to this window. the window must be viewable (TODO), or a xcb_match_error_t occurs (TODO).
  • if focus is XCB_NONE (TODO), all keyboard events are discarded until a new focus window is set. keyboard goes quiet. ghost town energy 👻
  • if focus is XCB_POINTER_ROOT (TODO), focus is on the root window of the screen on which the pointer is on currently.
• time — timestamp to avoid race conditions when running X over the network. bestie, networking is chaos and this is your little shield 🛡️
  • the special value XCB_CURRENT_TIME will be replaced with the current server time. slay, let the server decide ⏰

---

💜 DESCRIPTION 💜

changes the input focus and the last-focus-change time. two for one, we love efficiency.

if the specified time is earlier than the current last-focus-change time, the request is ignored (to avoid race conditions when running X over the network). so if you're late with your timestamp, you get nothing. the request said "too slow" and moved on 🏃♀️💨

a FocusIn and FocusOut event is generated when focus is changed. events! drama! the group chat is notified 📣

---

⭐ RETURN VALUE ⭐

returns an xcb_void_cookie_t. errors (if any) have to be handled in the event loop. no sneaky return-value checks here, you gotta go to the loop for that.

if you want to handle errors directly with xcb_request_check instead, use xcb_set_input_focus_checked. see xcb-requests(3) for details. 👑

---

🔥 ERRORS 🔥

• xcb_match_error_t — the specified focus window is not viewable.
• xcb_value_error_t — TODO: Reasons? (the manpage itself is like "idk bestie" 😭)
• xcb_window_error_t — the specified focus window does not exist.

---

🌈 SEE ALSO 🌈

• xcb-requests(3)
• xcb_focus_in_event_t(3)
• xcb_focus_out_event_t(3)

---

👑 AUTHOR 👑

generated from xproto.xml. contact xcb@lists.freedesktop.org for corrections and improvements. they're literally asking for feedback, so if you spot something, tell them 🫶

---

heads up bestie: time matters, focus has to be viewable or you eat an error, and the two TODOs plus the NOT YET DOCUMENTED are exactly how the original page reads. i'm not making anything up, i'm just being cute about it 💅

---

and that's the whole page, fr fr. this was X Version 11, from libxcb 1.17.0, and you just read xcb_set_input_focus(3). mwah, go focus a window responsibly 🎀✨