=== modified file 'man/termkey_advisereadable.3' --- man/termkey_advisereadable.3 2012-01-21 00:52:13 +0000 +++ man/termkey_advisereadable.3 2012-01-18 14:03:39 +0000 @@ -10,7 +10,7 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_advisereadable\fP() informs the \fBtermkey\fP(7) instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. +\fBtermkey_advisereadable\fP() informs the instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned. If there was no buffer space remaining, then \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBENOMEM\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. .PP This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program. To provide bytes without using a readable file handle, use \fBtermkey_push_bytes\fP(3). .PP @@ -27,7 +27,7 @@ .B TERMKEY_RES_ERROR An IO error occured. \fIerrno\fP will be preserved. If the error is \fBEINTR\fP then this will only be returned if \fBTERMKEY_FLAG_EINTR\fP flag is not set; if it is then the IO operation will be retried instead. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_getkey (3), .BR termkey_waitkey (3), -.BR termkey_set_waittime (3), -.BR termkey (7) +.BR termkey_set_waittime (3) === modified file 'man/termkey_canonicalise.3' --- man/termkey_canonicalise.3 2012-01-21 00:52:13 +0000 +++ man/termkey_canonicalise.3 2012-01-18 12:01:38 +0000 @@ -10,13 +10,18 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_canonicalise\fP(3) modifies the key event structure given by \fIkey\fP according to the canonicalisation flags set on the given \fBtermkey\fP instance. This operation is performed implicitly by \fBtermkey_getkey\fP(3), \fBtermkey_waitkey\fP(3) and \fBtermkey_strpkey\fP(3), and is also provided explicitly by this function. +\fBtermkey_canonicalise\fP(3) modifies the key event structure given by \fIkey\fP according to the canonicalisation flags set on the given \fItk\fP instance. This operation is performed implicitly by \fBtermkey_getkey\fP(3), \fBtermkey_waitkey\fP(3) and \fBtermkey_strpkey\fP(3), and is also provided explicitly by this function. .PP -See \fBtermkey\fP(7) for a list of canonicalisation flags. +The canonicalisation operation is affected by the following flags: +.TP +.B TERMKEY_CANON_SPACESYMBOL +If this flag is set then a Unicode space character is represented using the \fBTERMKEY_SYM_SPACE\fP symbol. If this flag is not set, it is represented by the U+0020 Unicode codepoint. +.TP +.B TERMKEY_CANON_DELBS +If this flag is set then an ASCII DEL character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An ASCII BS character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag. .SH "RETURN VALUE" \fBtermkey_canonicalise\fP() returns no value. .SH "SEE ALSO" .BR termkey_set_canonflags (3), .BR termkey_waitkey (3), -.BR termkey_strpkey (3), -.BR termkey (7) +.BR termkey_strpkey (3) === modified file 'man/termkey_get_buffer_remaining.3' --- man/termkey_get_buffer_remaining.3 2012-01-21 00:52:13 +0000 +++ man/termkey_get_buffer_remaining.3 2012-01-18 13:39:50 +0000 @@ -10,12 +10,12 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the \fBtermkey\fP(7) instance. These bytes are free to use by \fBtermkey_push_bytes\fP(3), or may be filled by \fBtermkey_advisereadable\fP(3). +A termkey instance contains a buffer of pending bytes that have been read by \fBtermkey_advisereadable\fP(3) or provided by \fBtermkey_push_bytes\fP(3) but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the termkey instance. .PP .SH "RETURN VALUE" \fBtermkey_get_buffer_remaining\fP() returns a size in bytes. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_push_bytes (3), .BR termkey_advisereadable (3), -.BR termkey_getkey (3), -.BR termkey (7) +.BR termkey_getkey (3) === modified file 'man/termkey_get_fd.3' --- man/termkey_get_fd.3 2012-01-21 00:52:13 +0000 +++ man/termkey_get_fd.3 2012-01-18 14:03:39 +0000 @@ -10,10 +10,9 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_get_fd\fP() returns the file descriptor that the \fBtermkey\fP(7) instance is using to read bytes from. +\fBtermkey_get_fd\fP() returns the file descriptor that was passed as the \fIfd\fP argument to \fBtermkey_new\fP(3). .SH "RETURN VALUE" \fBtermkey_get_fd\fP() returns the current file descriptor, or -1 if no file descriptor is associated with this instance. .SH "SEE ALSO" .BR termkey_new (3), -.BR termkey_get_flags (3), -.BR termkey (7) +.BR termkey_get_flags (3) === modified file 'man/termkey_get_keyname.3' --- man/termkey_get_keyname.3 2012-01-21 00:52:13 +0000 +++ man/termkey_get_keyname.3 2012-01-18 12:01:38 +0000 @@ -10,11 +10,13 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the \fBtermkey\fP(7) instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3). +\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the termkey instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the termkey instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3). .SH "RETURN VALUE" \fBtermkey_get_key\fP() returns a pointer to a string. .SH "SEE ALSO" +.BR termkey_new (3), +.BR termkey_getkey (3), +.BR termkey_waitkey (3), .BR termkey_lookup_keyname (3), .BR termkey_keyname2sym (3), -.BR termkey_strfkey (3), -.BR termkey (7) +.BR termkey_strfkey (3) === modified file 'man/termkey_getkey.3.sh' --- man/termkey_getkey.3.sh 2012-01-21 00:52:13 +0000 +++ man/termkey_getkey.3.sh 2012-01-18 14:31:25 +0000 @@ -13,7 +13,7 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\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: +\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: .in .TP .B TERMKEY_RES_KEY @@ -33,10 +33,48 @@ 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 \fBtermkey\fP 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 termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles. .PP .in +4n .nf @@ -46,8 +84,13 @@ .in .fi .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_advisereadable (3), +.BR termkey_push_bytes (3), .BR termkey_waitkey (3), -.BR termkey_get_waittime (3), -.BR termkey (7) +.BR termkey_set_waittime (3), +.BR termkey_get_keyname (3), +.BR termkey_interpret_mouse (3), +.BR termkey_strfkey (3), +.BR termkey_keycmp (3) EOF === modified file 'man/termkey_interpret_mouse.3' --- man/termkey_interpret_mouse.3 2012-01-21 00:52:13 +0000 +++ man/termkey_interpret_mouse.3 2012-01-18 12:01:38 +0000 @@ -38,6 +38,6 @@ .PP For other event types it will return \fBTERMKEY_RES_NONE\fP, and its effects on any variables whose pointers were passed in, are undefined. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_waitkey (3), .BR termkey_getkey (3), -.BR termkey (7) === modified file 'man/termkey_keycmp.3' --- man/termkey_keycmp.3 2012-01-21 00:52:13 +0000 +++ man/termkey_keycmp.3 2012-01-18 12:01:38 +0000 @@ -19,6 +19,7 @@ .SH NOTES This function does not perform any canonicalisation of the key structures, and performs a simple comparison of the fields in the structures. In particular, it will not consider as equal \fBTERMKEY_TYPE_UNICODE\fP containing the Space codepoint (U+0020) vs. \fBTERMKEY_TYPE_KEYSYM\fP containing \fBTERMKEY_SYM_SPACE\fP. .SH "SEE ALSO" +.BR termkey_new (3), +.BR termkey_getkey (3), .BR termkey_strpkey (3), -.BR termkey_canonicalise (3), -.BR termkey (7) +.BR termkey_canonicalise (3) === modified file 'man/termkey_keyname2sym.3' --- man/termkey_keyname2sym.3 2012-01-21 00:52:13 +0000 +++ man/termkey_keyname2sym.3 2012-01-18 12:01:38 +0000 @@ -16,7 +16,7 @@ .SH "RETURN VALUE" \fBtermkey_keyname2sym\fP() returns a symbolic key constant, or \fBTERMKEY_SYM_UNKNOWN\fP. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_get_keyname (3), .BR termkey_lookup_keyname (3), -.BR termkey_strpkey (3), -.BR termkey (7) +.BR termkey_strpkey (3) === modified file 'man/termkey_lookup_keyname.3' --- man/termkey_lookup_keyname.3 2012-01-21 00:52:13 +0000 +++ man/termkey_lookup_keyname.3 2012-01-18 12:01:38 +0000 @@ -17,7 +17,7 @@ .SH "RETURN VALUE" \fBtermkey_lookup_keyname\fP() returns a pointer to the first character after a recognised name, or \fBNULL\fP if the string does not begin with the name of a recognised symbolic key. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_get_keyname (3), .BR termkey_keyname2sym (3), -.BR termkey_strpkey (3), -.BR termkey (7) +.BR termkey_strpkey (3) === modified file 'man/termkey_new.3' --- man/termkey_new.3 2012-01-21 00:52:13 +0000 +++ man/termkey_new.3 2012-01-20 20:07:59 +0000 @@ -12,10 +12,42 @@ .sp Link with \fI\-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_new\fP() creates a new \fBtermkey\fP(7) instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. If \fIfd\fP is given the value -1, then no file handle will be associated. +\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library. If \fIfd\fP is given the value -1, then no file handle will be associated. .PP \fBtermkey_destroy\fP() destroys the given instance and releases any resources controlled by it. It will not close the underlying filehandle given as the \fIfd\fP argument to \fBtermkey_new\fP(). .PP +A termkey instance contains a buffer of bytes representing keypresses yet to be returned to the application. This buffer may be fed bytes directly by calling \fBtermkey_push_bytes\fP(3), or by calling \fBtermkey_advisereadable\fP(3) which itself will \fBread\fP(3) them from the filehandle given by \fIfd\fP. Once in the buffer, these bytes can be returned as key press events by calling \fBtermkey_getkey\fP(3). The read and get operations are combined in a single function \fBtermkey_waitkey\fP(3), which may be more convenient to use in the standard case of blocking reads from the \fIstdin\fP filehandle. +.PP +The following values may be given as the \fIflags\fP bitmask: +.TP +.B TERMKEY_FLAG_NOINTERPRET +Do not attempt to interpret \fBC0\fP codes into keysyms. Instead report them as plain "Ctrl-letter" events. +.TP +.B TERMKEY_FLAG_CONVERTKP +Convert xterm's alternative keypad symbols into the plain +.SM ASCII +codes they would represent. +.TP +.B TERMKEY_FLAG_RAW +Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values. +.TP +.B TERMKEY_FLAG_UTF8 +Ignore locale settings; force UTF-8 recombining on. This flag overrides \fBTERMKEY_FLAG_RAW\fP. +.TP +.B TERMKEY_FLAG_NOTERMIOS +Even if the terminal file descriptor \fIfd\fP represents a +.SM TTY +device, do not call the \fBtcsetattr\fP(3) \fBtermios\fP function on it to set it to canonical input mode. +.TP +.B TERMKEY_FLAG_SPACESYMBOL +Report space as being a symbolic key rather than a Unicode codepoint. +.TP +.B TERMKEY_FLAG_CTRLC +Disable the \fBSIGINT\fP behaviour of \fICtrl-C\fP. If this flag is provided, then \fICtrl-C\fP will be available as a normal keypress, rather than sending the process group a \fBSIGINT\fP. This flag only takes effect without \fBTERMKEY_FLAG_NOTERMIOS\fP; with it, none of the signal keys are disabled anyway. +.TP +.B TERMKEY_FLAG_EINTR +Without this flag, IO operations are retried when interrupted by a signal (\fBEINTR\fP). With this flag the \fBTERMKEY_RES_ERROR\fP result is returned instead. +.PP When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP(3). .PP If a file handle is provided, the terminfo driver may send a string to the terminal before \fBtermkey_new\fP() returns to initialise it, or set the state correctly. This will not be done if no file handle is provided, or if the file handle is a pipe (\fBS_ISFIFO\fP()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode. @@ -29,5 +61,4 @@ .BR termkey_getkey (3), .BR termkey_get_flags (3), .BR termkey_get_fd (3), -.BR termkey_get_buffer_remaining (3), -.BR termkey (7) +.BR termkey_get_buffer_remaining (3) === modified file 'man/termkey_push_bytes.3' --- man/termkey_push_bytes.3 2012-01-21 00:52:13 +0000 +++ man/termkey_push_bytes.3 2012-01-18 14:31:25 +0000 @@ -10,14 +10,14 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_push_bytes\fP() allows more bytes of input to be supplied directly into the input buffer of the \fBtermkey\fP(7) instance. If there was no buffer space remaining then -1 is returned with \fIerrno\fP set to \fBENOMEM\fP. +\fBtermkey_push_bytes\fP() allows more bytes of input to be supplied directly into the input buffer of the termkey instance. If there was no buffer space remaining then -1 is returned with \fIerrno\fP set to \fBENOMEM\fP. .PP -This function, along with \fBtermkey_getkey\fP(3), makes it possible to use the \fBtermkey\fP instance with a source of bytes other than from reading a filehandle. +This function, along with \fBtermkey_getkey\fP(3), makes it possible to use the termkey instance with a source of bytes other than from reading a filehandle. .PP For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task. For use against a regular stream filehandle that supports \fBread\fP(2), see \fBtermkey_advisereadable\fP(3). .SH "RETURN VALUE" \fBtermkey_push_bytes\fP() the number of bytes consumed from the input (which may be smaller than the length provided, if the buffer runs out of space) or -1 cast to \fBsize_t\fP if an error occurs, in which case \fIerrno\fP is set accordingly. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_getkey (3), -.BR termkey_advisereadable (3), -.BR termkey (7) +.BR termkey_advisereadable (3) === modified file 'man/termkey_set_canonflags.3' --- man/termkey_set_canonflags.3 2012-01-21 00:52:13 +0000 +++ man/termkey_set_canonflags.3 2012-01-18 12:01:38 +0000 @@ -11,11 +11,11 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_set_canonflags\fP() changes the set of canonicalisation flags in the \fBtermkey\fP(7) instance to those given by \fInewflags\fP. For detail on the available flags and their meaning, see the \fBtermkey\fP manpage. +\fBtermkey_set_canonflags\fP() changes the set of canonicalisation flags in the termkey instance to those given by \fInewflags\fP. For detail on the available flags and their meaning, see \fBtermkey_set_canonflags\fP(3). .PP \fBtermkey_get_canonflags\fP() returns the value set by the last call to \fBtermkey_canonicalise\fP(). .SH "RETURN VALUE" \fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current canonicalisation flags. .SH "SEE ALSO" -.BR termkey_canonicalise (3), -.BR termkey (7) +.BR termkey_new (3), +.BR termkey_canonicalise (3) === modified file 'man/termkey_set_flags.3' --- man/termkey_set_flags.3 2012-01-21 00:52:13 +0000 +++ man/termkey_set_flags.3 2012-01-18 12:01:38 +0000 @@ -11,11 +11,12 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_set_flags\fP() changes the set of operation flags in the \fBtermkey\fP(7) instance to those given by \fInewflags\fP. +\fBtermkey_set_flags\fP() changes the set of operation flags in the termkey instance to those given by \fInewflags\fP. .PP \fBtermkey_get_flags\fP() returns the value set by the last call to \fBtermkey_set_flags\fP(), or the value given to the constructor. +.PP +When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be returned by \fBtermkey_get_flags\fP(). .SH "RETURN VALUE" \fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current operational flags. .SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey (7) +.BR termkey_new (3) === modified file 'man/termkey_set_waittime.3' --- man/termkey_set_waittime.3 2012-01-21 00:52:13 +0000 +++ man/termkey_set_waittime.3 2012-01-18 12:01:38 +0000 @@ -17,6 +17,6 @@ .SH "RETURN VALUE" \fBtermkey_set_waittime\fP() returns no value. \fBtermkey_get_waittime\fP() returns the current wait time in miliseconds. .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_getkey (3), -.BR termkey_waitkey (3), -.BR termkey (7) +.BR termkey_waitkey (3) === modified file 'man/termkey_strfkey.3' --- man/termkey_strfkey.3 2012-01-21 00:52:13 +0000 +++ man/termkey_strfkey.3 2012-01-18 12:01:38 +0000 @@ -43,5 +43,4 @@ .BR termkey_getkey (3), .BR termkey_waitkey (3), .BR termkey_get_keyname (3), -.BR termkey_strpkey (3), -.BR termkey (7) +.BR termkey_strpkey (3) === modified file 'man/termkey_strpkey.3' --- man/termkey_strpkey.3 2012-01-21 00:52:13 +0000 +++ man/termkey_strpkey.3 2012-01-18 12:01:38 +0000 @@ -32,5 +32,4 @@ .SH "SEE ALSO" .BR termkey_new (3), .BR termkey_strfkey (3), -.BR termkey_keycmp (3), -.BR termkey (7) +.BR termkey_keycmp (3) === modified file 'man/termkey_waitkey.3.sh' --- man/termkey_waitkey.3.sh 2012-01-21 00:52:13 +0000 +++ man/termkey_waitkey.3.sh 2012-01-18 14:03:39 +0000 @@ -12,11 +12,13 @@ .sp Link with \fI-ltermkey\fP. .SH DESCRIPTION -\fBtermkey_waitkey\fP(3) 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. 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 block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. +\fBtermkey_waitkey\fP(3) 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 block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. If no filehandle is associated with this instance, \fBTERMKEY_RES_ERROR\fP is returned with \fIerrno\fP set to \fBEBADF\fP. .PP Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). .PP -Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using \fBtermkey\fP, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3). +For details of the \fITermKeyKey\fP structure, see \fBtermkey_getkey\fP(3). +.PP +Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using termkey, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3). .SH "RETURN VALUE" \fBtermkey_waitkey\fP() returns one of the following constants: .TP @@ -39,7 +41,10 @@ .in .fi .SH "SEE ALSO" +.BR termkey_new (3), .BR termkey_getkey (3), .BR termkey_set_waittime (3), -.BR termkey (7) +.BR termkey_get_keyname (3), +.BR termkey_strfkey (3), +.BR termkey_keycmp (3) EOF