TERMKEY_STRFKEY(3)

💖 TERMKEY_STRFKEY(3) 💖

okay bestie, welcome to the Library Functions Manual ✨ this is the page for termkey_strfkey, and yes we're gonna make a key event look cute in a string. sit down, hydrate, let's go 🫶

🌸 NAME 🌸

termkey_strfkey — turn a key event into a string, basically glam it up for humans 💅

🎀 SYNOPSIS 🎀

#include <termkey.h>

size_t termkey_strfkey(TermKey *tk, char *buffer, size_t len,
            TermKeyKey *key, TermKeyFormat format);

Link with -ltermkey.

🦋 DESCRIPTION 🦋

so termkey_strfkey() formats a string buffer so it holds a human-readable representation of a key event. it fills that buffer in a way that's analogous to the standard library besties snprintf(3) or strftime(3) — same energy, different job 💫

ngl this function used to be called termkey_snprint_key() but it got renamed after version 0.6. glow-up era, we love to see it 👑

the format argument is what decides how the output looks, and it's a bitmask</> of these constants:

✨ the format bits ✨

• TERMKEY_FORMAT_LONGMOD — print the full modifier names, like "Shift-", instead of abbreviating them down to "S-". no more cryptic little letters 🙈
• TERMKEY_FORMAT_CARETCTRL — if the only modifier is TERMKEY_MOD_CTRL on a plain letter, render it like "^X" instead of "Ctrl-X". caret-core 🎀
• TERMKEY_FORMAT_ALTISMETA — use the name "Meta" or the letter "M" instead of "Alt" or "A". branding choice, honestly ✨
• TERMKEY_FORMAT_WRAPBRACKET — if the key event is a special key rather than unmodified Unicode, wrap it up in <brackets>. cozy 🧣
• TERMKEY_FORMAT_SPACEMOD — use spaces instead of hyphens to separate the modifier name(s) from the base key name. breathing room, periodt 🌬️
• TERMKEY_FORMAT_LOWERMOD — lowercase for the modifier name. soft launch 🍓
• TERMKEY_FORMAT_LOWERSPACE — lowercase with spaces in for the key name instead of camelCase (like "page down" instead of "PageDown"). it's giving lowercase supremacy 💜
• TERMKEY_FORMAT_MOUSE_POS — if the event is a mouse event, include the position, rendered as "@ (col,line)". rat girlies stay winning 🐭

and for the common combos, there's shortcuts so you don't have to assemble the bitmask yourself:

• TERMKEY_FORMAT_VIM — shortcut that sets ALTISMETA and WRAPBRACKET, giving you output close to the format the vim editor uses. vim girlies, this one's for you 💚
• TERMKEY_FORMAT_URWID — shortcut that sets ALTISMETA, LONGMOD, LOWERMOD, SPACEMOD and LOWERSPACE, giving you output close to the format the urwid python library uses. python besties rise 🐍

okay important detail, don't skip it: when formatting a TERMKEY_TYPE_UNICODE key structure, this function uses the utf8 member. if that member contains an empty string (i.e. its first character is 0) then this member will be prefilled by the function from the code.number member. lowkey convenient when you're constructing the key structure programmatically in your own user code 🛠️✨

🔥 RETURN VALUE 🔥

termkey_strfkey() returns the number of characters written to buffer. that's it, that's the number 💫

👀 SEE ALSO 👀

termkey_new(3), termkey_getkey(3), termkey_waitkey(3), termkey_get_keyname(3), termkey_strpkey(3), termkey(7)

and that's the whole page bestie!! this one came from the TERMKEY_STRFKEY(3) page in the Library Functions Manual, and you made it all the way to the end, which is iconic behavior honestly 👑💖 go format some keys, mwah 🫶✨