diff options
Diffstat (limited to 'man/termkey_getkey.3.sh')
| -rw-r--r-- | man/termkey_getkey.3.sh | 51 |
1 files changed, 4 insertions, 47 deletions
diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh index e5f5a31..f95a439 100644 --- a/man/termkey_getkey.3.sh +++ b/man/termkey_getkey.3.sh @@ -13,7 +13,7 @@ termkey_getkey, termkey_getkey_force \- retrieve the next key event .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. It returns one of the following values: +\fBtermkey_getkey\fP() attempts to retrieve a single keypress event from the \fBtermkey\fP(7) instance buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values: .in .TP .B TERMKEY_RES_KEY @@ -33,48 +33,10 @@ no bytes are waiting in the buffer. Neither of these functions will block or perform any IO operations on the underlying filehandle. To use the instance in an asynchronous program, see \fBtermkey_advisereadable\fP(3). For a blocking call suitable for use in a synchronous program, use \fBtermkey_waitkey\fP(3) instead of \fBtermkey_getkey\fP(). For providing input without a readable filehandle, use \fBtermkey_push_bytes\fP(3). .PP Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). -.PP -The \fITermKeyKey\fP structure is defined as follows: -.PP -.in +4n -.nf -typedef struct { - TermKeyType type; - union { - long codepoint; /* TERMKEY_TYPE_UNICODE */ - int number; /* TERMKEY_TYPE_FUNCTION */ - TermKeySym sym; /* TERMKEY_TYPE_KEYSYM */ - char mouse[4] /* TERMKEY_TYPE_MOUSE */ - } code; - int modifiers; - char utf8[7]; -} TermKeyKey; -.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. This value indicates that \fIcode.codepoint\fP is valid, and will contain the codepoint number of the keypress. In Unicode mode (if the \fBTERMKEY_FLAG_UTF8\fP bit is set) this will be its Unicode character number. In raw byte mode, this will contain a single 8-bit byte. -.TP -.B TERMKEY_TYPE_FUNCTION -a numbered function key. This value indicates that \fIcode.number\fP is valid, and contains the number of the numbered function key. -.TP -.B TERMKEY_TYPE_KEYSYM -a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains the symbolic key value. This is an opaque value which may be passed to \fBtermkey_get_keyname\fP(3). -.TP -.B TERMKEY_TYPE_MOUSE -a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque. Use \fBtermkey_interpret_mouse\fP(3) to interpret it. -.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_strfkey\fP(3). .SH "RETURN VALUE" \fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP or \fBTERMKEY_RES_EOF\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP. .SH EXAMPLE -The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles. +The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles. .PP .in +4n .nf @@ -84,13 +46,8 @@ cat <<EOF .in .fi .SH "SEE ALSO" -.BR termkey_new (3), .BR termkey_advisereadable (3), -.BR termkey_push_bytes (3), .BR termkey_waitkey (3), -.BR termkey_set_waittime (3), -.BR termkey_get_keyname (3), -.BR termkey_interpret_mouse (3), -.BR termkey_strfkey (3), -.BR termkey_keycmp (3) +.BR termkey_get_waittime (3), +.BR termkey (7) EOF |