2011-03-31 16:42:32 +02:00
.TH TERMKEY_STRFKEY 3
2008-11-06 01:02:41 +01:00
.SH NAME
2011-03-31 16:42:32 +02:00
termkey_strfkey \- format a string representing a key event
2008-11-06 01:02:41 +01:00
.SH SYNOPSIS
.nf
.B #include <termkey.h>
.sp
2011-03-31 16:42:32 +02:00
.BI "size_t termkey_strfkey(TermKey *" tk ", char *" buffer ", size_t " len ",
2011-04-01 15:05:19 +02:00
.BI " TermKeyKey *" key ", TermKeyFormat " format );
2008-11-06 01:02:41 +01:00
.fi
.sp
Link with \fI -ltermkey\fP .
.SH DESCRIPTION
2011-04-03 19:44:48 +02:00
\fB termkey_strfkey\fP () formats a string buffer to contain a human-readable representation of a key event. It fills the \fI buffer\fP in a way analogous to the \fB snprintf\fP (3) or \fB strftime\fP (3) standard library functions. This function used to be called \fB termkey_snprint_key\fP () but was renamed after version 0.6.
2008-11-06 01:02:41 +01:00
.PP
The \fI format\fP argument specifies the format of the output, as a bitmask of the following constants:
.TP
.B TERMKEY_FORMAT_LONGMOD
2012-04-25 01:59:13 +02:00
Print full modifier names e.g. "\f (CWShift-\fP " instead of abbreviating to "\f (CWS-\fP ".
2008-11-06 01:02:41 +01:00
.TP
.B TERMKEY_FORMAT_CARETCTRL
2012-04-25 01:59:13 +02:00
If the only modifier is \fB TERMKEY_MOD_CTRL\fP on a plain letter, render it as "\f (CW^X\fP " rather than "\f (CWCtrl-X\fP ".
2008-11-06 01:02:41 +01:00
.TP
.B TERMKEY_FORMAT_ALTISMETA
2012-04-25 01:59:13 +02:00
Use the name "\f (CWMeta\fP " or the letter "\f (CWM\fP " instead of "\f (CWAlt\fP " or "\f (CWA\fP ".
2008-11-06 01:02:41 +01:00
.TP
.B TERMKEY_FORMAT_WRAPBRACKET
2012-04-25 01:59:13 +02:00
If the key event is a special key instead of unmodified Unicode, wrap it in "\f (CW<brackets>\fP ".
2009-11-27 16:07:05 +01:00
.TP
2013-08-26 01:56:07 +02:00
.B TERMKEY_FORMAT_SPACEMOD
Use spaces instead of hyphens to separate the modifier name(s) from the base key name.
.TP
2013-08-26 02:14:35 +02:00
.B TERMKEY_FORMAT_LOWERMOD
2013-08-26 02:32:35 +02:00
Use lowercase for the modifier name.
.TP
.B TERMKEY_FORMAT_LOWERSPACE
2013-08-26 03:23:19 +02:00
Use lowercase with spaces in for the key name instead of camelCase (for example "\f (CWpage down\fP " instead of "\f (CWPageDown\fP ").
2013-08-26 02:14:35 +02:00
.TP
2009-11-27 16:07:05 +01:00
.B TERMKEY_FORMAT_MOUSE_POS
2012-04-25 01:59:13 +02:00
If the event is a mouse event, include the position rendered as "\f (CW@ (col,line)\fP ".
2008-11-06 01:02:41 +01:00
.PP
The following shortcuts are provided for common combinations of format bits:
.TP
.B TERMKEY_FORMAT_VIM
Shortcut to set \fB ALTISMETA\fP and \fB WRAPBRACKET\fP , to give an output close to the format the \fI vim\fP editor uses.
2013-08-26 19:51:29 +02:00
.TP
.B TERMKEY_FORMAT_URWID
Shortcut to set \fB ALTISMETA\fP , \fB LONGMOD\fP , \fB LOWERMOD\fP , \fB SPACEMOD\fP and \fB LOWERSPACE\fP , to give an output close to the format the \fI urwid\fP python library uses.
2011-03-31 16:42:32 +02:00
.PP
When formatting a \fB TERMKEY_TYPE_UNICODE\fP key structure, this function uses the \fI utf8\fP 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 \fI code.number\fP member. This can be convenient when the key structure is being constructed programatically by user code.
2008-11-06 01:02:41 +01:00
.SH "RETURN VALUE"
2011-03-31 16:42:32 +02:00
\fB termkey_strfkey\fP () returns the number of characters written to \fI buffer\fP .
2008-11-06 01:02:41 +01:00
.SH "SEE ALSO"
.BR termkey_new (3),
.BR termkey_getkey (3),
.BR termkey_waitkey (3),
2011-04-01 12:11:50 +02:00
.BR termkey_get_keyname (3),
2012-01-21 01:52:13 +01:00
.BR termkey_strpkey (3),
.BR termkey (7)