TERMKEY_INTERPRET_MOUSE(3)

💖 TERMKEY_INTERPRET_MOUSE(3) 💖

okay bestie, welcome to the Library Functions Manual page for termkey_interpret_mouse, a genuine little icon of the termkey library. she's here to decode the mouse gossip your terminal is handing you 🐭✨

✨ NAME ✨

termkey_interpret_mouse — interpret opaque mouse event data

🌸 SYNOPSIS 🌸

#include <termkey.h>

TermKeyResult termkey_interpret_mouse(TermKey *tk, const TermKeyKey *key,
    TermKeyMouseEvent *ev, int *button, int *line, int *col);

and don't forget to link with -ltermkey, no cap 💅

🦋 DESCRIPTION 🦋

so termkey_interpret_mouse() takes the mouse event chillin' inside key and fills in the variables behind all those pointers you passed in. it's giving "translator bestie" fr fr.

you should call this one when termkey_getkey(3) (or one of her little friends) hands you back a key event whose type is TERMKEY_TYPE_MOUSE. that's the vibe check — if it's not that type, this function is not the main character here.

also, any of those pointers can just be NULL if you don't want that particular value back. lowkey generous of her 🫶

the ev variable is gonna end up being one of these:

• TERMKEY_MOUSE_UNKNOWN — an unknown mouse event. mystery behavior, we don't know her 💀
• TERMKEY_MOUSE_PRESS — a mouse button was pressed, and button will contain its number 👑
• TERMKEY_MOUSE_DRAG — the mouse was moved while holding a button down, and button will contain its number 🦋
• TERMKEY_MOUSE_RELEASE — a mouse button was released, or the mouse was moved while no button was pressed. if it's known, button will contain the number of the button that got released. but heads up: not all terminals can report this, so it may just be 0 instead. it's not her fault, the terminal simply didn't tell her 😭

and the line and col variables get filled in with the mouse position, indexed from 1 (yes, from one, we're not doing zero-indexed chaos here).

real talk though — because the TermKeyKey structure only has a limited number of bytes, the line and column numbers are capped at 2047 and 4095 respectively. so if your cursor is out here living its best life at column 9000... she can't see it. that's the limit, periodt.

🌈 RETURN VALUE 🌈

if you pass her a key event of the type TERMKEY_TYPE_MOUSE, this function returns TERMKEY_RES_KEY and does exactly the thing described above to all the variables whose pointers you handed over. slay ✨

for any other event types, she returns TERMKEY_RES_NONE, and what happens to those variables of yours... is undefined. not "probably fine", not "she'll try her best" — undefined. so please, only call her for mouse events, bestie, i'm begging 🙈

🎀 SEE ALSO 🎀

• termkey_waitkey(3)
• termkey_getkey(3)
• termkey(7)

and that's the whole page, you ate it up 💜 this was TERMKEY_INTERPRET_MOUSE(3) from the Library Functions Manual, and yeah, the same title shows up again at the bottom of the original — that's just how man pages do, iconic behavior honestly. go forth and interpret those mice, bestie 🐭👑💖