table of contents
TERMKEY_STRFKEY(3) | Library Functions Manual | TERMKEY_STRFKEY(3) |
NAME¶
termkey_strfkey - format a string representing a key event
SYNOPSIS¶
#include <termkey.h> size_t termkey_strfkey(TermKey *tk, char *buffer, size_t len, TermKeyKey *key, TermKeyFormat format);
Link with -ltermkey.
DESCRIPTION¶
termkey_strfkey() formats a string buffer to contain a human-readable representation of a key event. It fills the buffer in a way analogous to the snprintf(3) or strftime(3) standard library functions. This function used to be called termkey_snprint_key() but was renamed after version 0.6.
The format argument specifies the format of the output, as a bitmask of the following constants:
- TERMKEY_FORMAT_LONGMOD
- Print full modifier names e.g. "Shift-" instead of abbreviating to "S-".
- TERMKEY_FORMAT_CARETCTRL
- If the only modifier is TERMKEY_MOD_CTRL on a plain letter, render it as "^X" rather than "Ctrl-X".
- TERMKEY_FORMAT_ALTISMETA
- Use the name "Meta" or the letter "M" instead of "Alt" or "A".
- TERMKEY_FORMAT_WRAPBRACKET
- If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>".
- TERMKEY_FORMAT_SPACEMOD
- Use spaces instead of hyphens to separate the modifier name(s) from the base key name.
- TERMKEY_FORMAT_LOWERMOD
- Use lowercase for the modifier name.
- TERMKEY_FORMAT_LOWERSPACE
- Use lowercase with spaces in for the key name instead of camelCase (for example "page down" instead of "PageDown").
- TERMKEY_FORMAT_MOUSE_POS
- If the event is a mouse event, include the position rendered as "@ (col,line)".
The following shortcuts are provided for common combinations of format bits:
- TERMKEY_FORMAT_VIM
- Shortcut to set ALTISMETA and WRAPBRACKET, to give an output close to the format the vim editor uses.
- TERMKEY_FORMAT_URWID
- Shortcut to set ALTISMETA, LONGMOD, LOWERMOD, SPACEMOD and LOWERSPACE, to give an output close to the format the urwid python library uses.
When formatting a TERMKEY_TYPE_UNICODE key structure, this function uses the utf8 member. If this 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. This can be convenient when the key structure is being constructed programmatically by user code.
RETURN VALUE¶
termkey_strfkey() returns the number of characters written to buffer.
SEE ALSO¶
termkey_new(3), termkey_getkey(3), termkey_waitkey(3), termkey_get_keyname(3), termkey_strpkey(3), termkey(7)