diff options
| -rw-r--r-- | man/termkey.7 | 38 | ||||
| -rw-r--r-- | man/termkey_getkey.3.sh | 4 | ||||
| -rw-r--r-- | man/termkey_new.3 | 4 | ||||
| -rw-r--r-- | man/termkey_strfkey.3 | 10 | ||||
| -rw-r--r-- | man/termkey_strpkey.3 | 6 | ||||
| -rw-r--r-- | man/termkey_waitkey.3.sh | 2 |
6 files changed, 43 insertions, 21 deletions
diff --git a/man/termkey.7 b/man/termkey.7 index 33f267d..bafa0b8 100644 --- a/man/termkey.7 +++ b/man/termkey.7 @@ -2,7 +2,9 @@ .SH NAME termkey \- terminal keypress reading library .SH DESCRIPTION -\fBtermkey\fP is a library that allows programs to read and interpret keypress and other events from a terminal. It understands encoding schemes used by terminals to encode keypresses, and UTF-8, allowing it to return events representing key events. +\fBtermkey\fP is a library that allows programs to read and interpret keypress and other events from a terminal. It understands encoding schemes used by terminals to encode keypresses, and +.SM UTF-8 , +allowing it to return events representing key events. .PP \fBtermkey\fP operates in a pseudo object-oriented fashion. It provides one function, \fBtermkey_new\fP(3), that returns a pointer to a newly-allocated structure. All other functions take this pointer as their first argument. A typical use of this library would consist of a call to \fBtermkey_new\fP() to construct a new instance to represent the \fIstdin\fP stream, then use the \fBtermkey_waitkey\fP(3) function to wait for and interpret key press events. The \fBtermkey_destroy\fP(3) function can be used to deallocate resources used by the instance if the program has finished using it. .SS Reading Events @@ -66,7 +68,7 @@ Details of the behaviour of a \fBtermkey\fP instance are controlled by two bitma The following control flags are recognised. .TP .B TERMKEY_FLAG_NOINTERPRET -Do not attempt to interpret \fBC0\fP codes into keysyms. Instead report them as plain "Ctrl-letter" events. +Do not attempt to interpret \fIC0\fP codes into keysyms. Instead report them as plain \fICtrl-letter\fP events. .TP .B TERMKEY_FLAG_CONVERTKP Convert xterm's alternative keypad symbols into the plain @@ -74,10 +76,14 @@ Convert xterm's alternative keypad symbols into the plain 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. +Ignore locale settings; do not attempt to recombine +.SM 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. +Ignore locale settings; force +.SM 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 @@ -96,20 +102,34 @@ Without this flag, IO operations are retried when interrupted by a signal (\fBEI The following canonicalisation flags are recognised. .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. +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 \f(CWU+0020\fP 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. +If this flag is set then an +.SM ASCII +.SM DEL +character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An +.SM ASCII +.SM BS +character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag. .SS Multi-byte Events -Special keys, mouse events, and UTF-8 encoded Unicode text, are all represented by more than one byte. If the start of a multi-byte sequence is seen by \fBtermkey_waitkey\fP() it will wait a short time to see if the remainder of the sequence arrives. If the sequence remains unfinished after this timeout, it will be returned in its incomplete state. Partial escape sequences are returned as an Escape key (\fBTERMKEY_SYM_ESCAPE\fP) followed by the text contained in the sequence. Partial UTF-8 sequences are returned as the Unicode replacement character, U+FFFD. +Special keys, mouse events, and +.SM UTF-8 +encoded Unicode text, are all represented by more than one byte. If the start of a multi-byte sequence is seen by \fBtermkey_waitkey\fP() it will wait a short time to see if the remainder of the sequence arrives. If the sequence remains unfinished after this timeout, it will be returned in its incomplete state. Partial escape sequences are returned as an Escape key (\fBTERMKEY_SYM_ESCAPE\fP) followed by the text contained in the sequence. Partial +.SM UTF-8 +sequences are returned as the Unicode replacement character, \f(CWU+FFFD\fP. .PP The amount of time that the \fBtermkey\fP instance will wait is set by \fBtermkey_set_waittime\fP(3), and is returned by \fBtermkey_get_waittime\fP(3). Initially it will be set to 50 miliseconds. .SS Mouse Events The \fBTERMKEY_TYPE_MOUSE\fP event type indicates a mouse event. The \fIcode\fP field of the event structure should be considered opaque, though \fImodifiers\fP will be valid. In order to obtain the details of the mouse event, call \fBtermkey_interpret_mouse\fP(3) passing the event structure and pointers to integers to store the result in. .PP -\fBtermkey\fP recognises three mouse protocols: the original X10 protocol (\f(CWCSI M\fP followed by three bytes), SGR encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly. +\fBtermkey\fP recognises three mouse protocols: the original +.SM X10 +protocol (\f(CWCSI M\fP followed by three bytes), +.SM SGR +encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly. .SS Position Events -The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in. +The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6 n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in. .SH "SEE ALSO" .BR termkey_new (3), .BR termkey_waitkey (3), diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh index 2f1b716..32d296d 100644 --- a/man/termkey_getkey.3.sh +++ b/man/termkey_getkey.3.sh @@ -31,7 +31,7 @@ no bytes are waiting in the buffer. .B TERMKEY_RES_ERROR called with terminal IO stopped, due to \fBtermkey_stop\fP(3). In this case \fIerrno\fP will be set to \fBEINVAL\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. +\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 \fIEscape\fP key followed by normal letters. .PP 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 @@ -39,7 +39,7 @@ Before returning, this function canonicalises the \fIkey\fP structure according .SH "RETURN VALUE" \fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP, \fBTERMKEY_RES_EOF\fP or \fBTERMKEY_RES_ERROR\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(2)-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 \fICtrl-C\fP. It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP(2)-driven asynchronous program, which may include mixed IO with other file handles. .PP .in +4n .nf diff --git a/man/termkey_new.3 b/man/termkey_new.3 index 6fad1ef..02e6774 100644 --- a/man/termkey_new.3 +++ b/man/termkey_new.3 @@ -19,7 +19,9 @@ Link with \fI\-ltermkey\fP. .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 -The constructor 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). +The constructor attempts to detect if the current locale is +.SM 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 initialise or set the state of the terminal before \fBtermkey_new\fP() returns. 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. Once initialised, the terminal can be stopped by \fBtermkey_stop\fP(3), and started again by \fBtermkey_start\fP(3). .SH VERSION CHECK MACRO diff --git a/man/termkey_strfkey.3 b/man/termkey_strfkey.3 index f712405..2bbf2ec 100644 --- a/man/termkey_strfkey.3 +++ b/man/termkey_strfkey.3 @@ -16,19 +16,19 @@ Link with \fI-ltermkey\fP. The \fIformat\fP argument specifies the format of the output, as a bitmask of the following constants: .TP .B TERMKEY_FORMAT_LONGMOD -Print full modifier names e.g. "Shift-" instead of abbreviating to "S-". +Print full modifier names e.g. "\f(CWShift-\fP" instead of abbreviating to "\f(CWS-\fP". .TP .B TERMKEY_FORMAT_CARETCTRL -If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "^X" rather than "Ctrl-X". +If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP". .TP .B TERMKEY_FORMAT_ALTISMETA -Use the name "Meta" or the letter "M" instead of "Alt" or "A". +Use the name "\f(CWMeta\fP" or the letter "\f(CWM\fP" instead of "\f(CWAlt\fP" or "\f(CWA\fP". .TP .B TERMKEY_FORMAT_WRAPBRACKET -If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>". +If the key event is a special key instead of unmodified Unicode, wrap it in "\f(CW<brackets>\fP". .TP .B TERMKEY_FORMAT_MOUSE_POS -If the event is a mouse event, include the position rendered as "@ (col,line)". +If the event is a mouse event, include the position rendered as "\f(CW@ (col,line)\fP". .PP The following shortcuts are provided for common combinations of format bits: .TP diff --git a/man/termkey_strpkey.3 b/man/termkey_strpkey.3 index 74665b8..4e4f5eb 100644 --- a/man/termkey_strpkey.3 +++ b/man/termkey_strpkey.3 @@ -16,13 +16,13 @@ Link with \fI-ltermkey\fP. The \fIformat\fP argument specifies the format expected in the string, as a bitmask of the following constants: .TP .B TERMKEY_FORMAT_LONGMOD -Expect full modifier names e.g. "Shift-" instead of abbreviating to "S-". +Expect full modifier names e.g. "\f(CWShift-\fP" instead of abbreviating to "\f(CWS-\fP". .TP .B TERMKEY_FORMAT_CARETCTRL -If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, accept it as "^X" rather than "Ctrl-X". +If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, accept it as "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP". .TP .B TERMKEY_FORMAT_ALTISMETA -Use the name "Meta" or the letter "M" instead of "Alt" or "A". +Use the name "\f(CWMeta\fP" or the letter "\f(CWM\fP" instead of "\f(CWAlt\fP" or "\f(CWA\fP". .PP Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). .PP diff --git a/man/termkey_waitkey.3.sh b/man/termkey_waitkey.3.sh index 5a219b4..7f11228 100644 --- a/man/termkey_waitkey.3.sh +++ b/man/termkey_waitkey.3.sh @@ -29,7 +29,7 @@ No key events are ready and the terminal has been closed, so no more will arrive .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. If this is called with terminal IO stopped, due to \fBtermkey_stop\fP(3) then \fIerrno\fP will be set to \fBEINVAL\fP. .SH EXAMPLE -The following example program prints details of every keypress until the user presses "Ctrl-C". +The following example program prints details of every keypress until the user presses \fICtrl-C\fP. .PP .in +4n .nf |