XIDEFINECURSOR(3)

📦

version 1.8.3 · 6 versions

💖 XIDEFINECURSOR 💖

okay bestie, welcome to the manual page for XIDefineCursor and XIUndefineCursor — the dynamic duo that lets you define device cursors, fr fr. yes we're in section 3, we're deep in library-call territory, and yes it's giving iconic. 🎀

✨ SYNOPSIS ✨

first things first, you gotta pull in the header or nothing works, obviously:

#include <X11/extensions/XInput2.h>

and here are the two functions, looking all cute and official:

int XIDefineCursor( Display *display,
                    int deviceid,
                    Window win,
                    Cursor cursor);

int XIUndefineCursor( Display *display,
                      int deviceid,
                      Window win);

the arguments, explained with love 🫶

cursor — the cursor that's gonna be displayed. or None, if you're feeling mysterious. (specifies the cursor that is to be displayed or None.)
deviceid — the device whose cursor we're changing up. glow-up time.
display — the connection to the X server. your link to the mothership.
win — the window. that's it, that's the whole vibe.

🌸 DESCRIPTION 🌸

so here's the tea. if a cursor is set, it gets used when the device's pointer is inside the window. simple! and if the cursor is None? that's literally equivalent to calling XIUndefineCursor. same energy, different spelling. 💅

now, the deviceid must be a master pointer device. if it's not? boom, a BadDevice error gets returned at you. no cap. ⚠️

XIDefineCursor can generate BadDevice, BadCursor and BadWindow. yes, three whole errors. she's versatile like that. 😭

XIUndefineCursor undoes the effect of a previous XIDefineCursor for this window. so once the pointer is in the window, the window's default cursor gets used now. and if there's no default cursor defined? then the parent's cursor for this device gets used (if defined), or the parent's default cursor gets used. it's a whole fallback chain, bestie. it's giving "we'll figure it out". 🌈

and here's the part where you go "oh so it's just the normal ones but extra": XIDefineCursor and XIUndefineCursor are identical to XDefineCursor and XUndefineCursor — except they specify the device explicitly. that's the whole plot twist. 👑

XIUndefineCursor can generate a BadDevice and a BadWindow error. two errors, still slaying.

💀 DIAGNOSTICS 💀

the errors you might run into, and what they mean. read them, memorize them, avoid them. ✨

BadCursor — a value for a cursor argument does not name a defined cursor. like calling a name that nobody answers to. 🙈
BadDevice — an invalid device was specified. the device does not exist, or it's not a pointer device. it's simply not that girl.
BadWindow — a value for a Window argument does not name a defined window. wrong window, bestie, try again.