XIQUERYPOINTER(3)

💖 XIQueryPointer 💖

okay bestie, welcome to XIQueryPointer(3) — yes that's the manual name, that's the whole vibe, we're in section 3 of the X Input extension and we're about to find out where a device's pointer actually is 🦋

---

✨ NAME ✨

XIQueryPointer — get device pointer coordinates. that's it. that's the girl. she tells you where the pointer is pointing 🎯

---

🌸 SYNOPSIS 🌸

#include <X11/extensions/XInput2.h>

Bool XIQueryPointer( Display *display,
                     int deviceid,
                     Window win,
                     Window *root_return,
                     Window *child_return,
                     double *root_x_return,
                     double *root_y_return,
                     double *win_x_return,
                     double *win_y_return,
                     XIButtonState *buttons_return,
                     XIModifierState *modifiers_return,
                     XIGroupState *group_return);

and now the cast of characters, because every single one of these matters 💅

• buttons_return — hands you back the current button state. she's reporting, not asking 🫶
• child_return — hands you back the child window the pointer is chillin' in, if there even is one 🙈
• deviceid — the device you're interrogating. pick one, bestie ✨
• display — the connection to the X server. your line to the mothership 👑
• group_return — hands you back the current group state 🌈
• modifiers_return — hands you back the current state of the modifier keys 🎀
• root_return — hands you back the root window the pointer is in 🌸
• root_x_return, root_y_return — return the pointer coordinates relative to the root window's origin 📍
• win — the window in question. specify her ⭐
• win_x_return, win_y_return — return the pointer coordinates relative to the specified window 🦋

---

💜 DESCRIPTION 💜

so the XIQueryPointer function returns the root window that the device's pointer is logically on, plus the pointer coordinates relative to the root window's origin. iconic behaviour, no notes 💅

now here's the plot twist. if XIQueryPointer returns False, that means the pointer is not on the same screen as the specified window, and XIQueryPointer returns None to child_return and zero to win_x_return and win_y_return. not me getting rejected by a screen boundary 😭

but if XIQueryPointer returns True? slay. then the pointer coordinates returned to win_x_return and win_y_return are relative to the origin of the specified window. and in this case, XIQueryPointer returns the child that contains the pointer — if any — or else None to child_return ✨

XIQueryPointer returns the current logical state of the buttons in buttons_return. the keyboard paired with the master pointer is selected to obtain the data for modifiers_return and group_return. yes, the keyboard is doing the work for the pointer's paperwork, it's giving teamwork fr fr 🫶

🚨 okay listen up because this part is important: the mask field in buttons_return is dynamically allocated and must be freed by the caller. that's you. you're the caller. free it. don't leak it, bestie, memory leaks are not the aesthetic 💀

and for the lore: XIQueryPointer is identical to XQueryPointer but specifies the device explicitly. same girl, but she knows exactly which device she's talking about 🌈

also heads up — XIQueryPointer can generate a BadDevice and a BadWindow error. drama is possible 👀

---

🎀 DIAGNOSTICS 🎀

• BadDevice — an invalid device was specified. either the device does not exist, or it's just not a pointer device. wrong girl, wrong job 🙈
• BadWindow — a value for a Window argument does not name a defined window. that window? doesn't exist. never did. ghosted 💀

---

🦋 SEE ALSO 🦋

• XQueryPointer(3)

---

and that's the whole page, bestie!! 💖✨🎀

this lil masterpiece is from 05/18/2026, filed under XIQUERYPOINTER(3) — go query some pointers, free that mask, and stay iconic 👑💅🌸