From 388782b89be0bf8144ae3dc2a590b466c96d3d6d Mon Sep 17 00:00:00 2001 From: Paul LeoNerd Evans Date: Thu, 6 Nov 2008 00:02:41 +0000 Subject: Added manpages for (most of) the external API functions --- termkey_getkey.3 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 termkey_getkey.3 (limited to 'termkey_getkey.3') diff --git a/termkey_getkey.3 b/termkey_getkey.3 new file mode 100644 index 0000000..064dda7 --- /dev/null +++ b/termkey_getkey.3 @@ -0,0 +1,73 @@ +.TH TERMKEY_GETKEY 3 +.SH NAME +termkey_getkey, termkey_getkey_force \- retrieve the next key event +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "termkey_result termkey_getkey(termkey_t *" tk ", termkey_key *" key ); +.br +.BI "termkey_result termkey_getkey_force(termkey_t *" tk ", termkey_key *" key ); +.fi +.sp +Link with \fI-ltermkey\fP. +.SH DESCRIPTION +\fBtermkey_getkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will return \fBTERMKEY_RES_NONE\fP. If the buffer contains a partial keypress event which does not yet contain all the bytes required, it will return \fBTERMKEY_RES_AGAIN\fP. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. +.PP +\fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters. +.PP +Neither of these functions will block or perform any IO operations on the underlying filehandle. For a blocking wait, see \fBtermkey_waitkey\fP. +.PP +The \fItermkey_key\fP structure is defined as follows: +.PP +.in +4n +.nf +typedef struct { + termkey_type type; + union { + long codepoint; /* TERMKEY_TYPE_UNICODE */ + int number; /* TERMKEY_TYPE_FUNCTION */ + termkey_keysym sym; /* TERMKEY_TYPE_KEYSYM */ + } code; + int modifiers; + char utf8[7]; +} termkey_key; +.fi +.in +.PP +The \fItype\fP field indicates the type of event, and determines which of the members of the \fIcode\fP union is valid. It will be one of the following constants: +.TP +.B TERMKEY_TYPE_UNICODE +a Unicode codepoint +.TP +.B TERMKEY_TYPE_FUNCTION +a numbered function key +.TP +.B TERMKEY_TYPE_KEYSYM +a symbolic key +.PP +The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP. +.PP +The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_UNICODE\fP. It should not be read for other events. +.PP +To convert the \fIsym\fP to a symbolic name, see \fBtermkey_get_keyname\fP(3) function. It may instead be easier to convert the entire key event structure to a string, using \fBtermkey_snprint_key\fP(3). +.SH "RETURN VALUE" +\fBtermkey_getkey\fP() and \fBtermkey_getkey_force\fP() return one of the following constants: +.TP +.B TERMKEY_RES_NONE +No key event is ready. +.TP +.B TERMKEY_RES_KEY +A key event as been provided. +.TP +.B TERMKEY_RES_EOF +No key events are ready and the terminal has been closed, so no more will arrive. +.TP +.B TERMKEY_RES_AGAIN +No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP(). +.SH "SEE ALSO" +.BR termkey_new (3), +.BR termkey_waitkey (3), +.BR termkey_setwaittime (3), +.BR termkey_get_keyname (3), +.BR termkey_snprint_key (3) -- cgit v1.2.3