diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/also | 9 | ||||
| -rw-r--r-- | man/termkey.7 | 145 | ||||
| -rw-r--r-- | man/termkey_advisereadable.3 | 33 | ||||
| -rw-r--r-- | man/termkey_canonicalise.3 | 22 | ||||
| -rw-r--r-- | man/termkey_get_buffer_remaining.3 | 23 | ||||
| -rw-r--r-- | man/termkey_get_fd.3 | 19 | ||||
| -rw-r--r-- | man/termkey_get_keyname.3 | 20 | ||||
| -rw-r--r-- | man/termkey_getkey.3.sh | 56 | ||||
| -rw-r--r-- | man/termkey_interpret_csi.3 | 28 | ||||
| -rw-r--r-- | man/termkey_interpret_modereport.3 | 26 | ||||
| -rw-r--r-- | man/termkey_interpret_mouse.3 | 41 | ||||
| -rw-r--r-- | man/termkey_interpret_position.3 | 26 | ||||
| -rw-r--r-- | man/termkey_keycmp.3 | 22 | ||||
| -rw-r--r-- | man/termkey_keyname2sym.3 | 22 | ||||
| -rw-r--r-- | man/termkey_lookup_keyname.3 | 23 | ||||
| -rw-r--r-- | man/termkey_new.3 | 48 | ||||
| -rw-r--r-- | man/termkey_push_bytes.3 | 23 | ||||
| -rw-r--r-- | man/termkey_set_buffer_size.3 | 22 | ||||
| -rw-r--r-- | man/termkey_set_canonflags.3 | 21 | ||||
| -rw-r--r-- | man/termkey_set_flags.3 | 21 | ||||
| -rw-r--r-- | man/termkey_set_waittime.3 | 22 | ||||
| -rw-r--r-- | man/termkey_start.3 | 25 | ||||
| -rw-r--r-- | man/termkey_strfkey.3 | 59 | ||||
| -rw-r--r-- | man/termkey_strpkey.3 | 45 | ||||
| -rw-r--r-- | man/termkey_waitkey.3.sh | 45 |
25 files changed, 0 insertions, 846 deletions
diff --git a/man/also b/man/also deleted file mode 100644 index 611ca45..0000000 --- a/man/also +++ /dev/null @@ -1,9 +0,0 @@ -termkey_destroy.3 = termkey_new.3 -termkey_new_abstract.3 = termkey_new.3 -termkey_get_flags.3 = termkey_set_flags.3 -termkey_get_canonflags.3 = termkey_set_canonflags.3 -termkey_get_buffer_size.3 = termkey_set_buffer_size.3 -termkey_get_waittime.3 = termkey_set_waittime.3 -termkey_getkey_force.3 = termkey_getkey.3 -termkey_stop.3 = termkey_start.3 -termkey_is_started.3 = termkey_start.3 diff --git a/man/termkey.7 b/man/termkey.7 deleted file mode 100644 index deae880..0000000 --- a/man/termkey.7 +++ /dev/null @@ -1,145 +0,0 @@ -.TH TERMKEY 7 -.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 -.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 -Each instance of a \fBtermkey\fP structure may be used in one of three ways by the program. It may be used synchronously, blocking to wait for keypresses from a filehandle. It may be used asynchronously, returning keypresses if they are available, while co-operating with a non-blocking program. Or it may be used abstractly, interpreting key press bytes fed to it directly by the containing program. -.PP -To obtain the next key event synchronously, a program may call \fBtermkey_waitkey\fP(3). This will either return an event from its internal buffer, or block until a key is available, returning it when it is ready. It behaves similarly to \fBgetc\fP(3), \fBfgetc\fP(3), or similar, except that it understands and returns entire key press events, rather than single bytes. -.PP -To work with an asynchronous program, two other functions are used. \fBtermkey_advisereadable\fP(3) informs a \fBtermkey\fP instance that more bytes of input may be available from its file handle, so it should call \fBread\fP(2) to obtain them. The program can then call \fBtermkey_getkey\fP(3) to extract key press events out of the internal buffer, in a way similar to \fBtermkey_waitkey\fP(). -.PP -Finally, bytes of input can be fed into the \fBtermkey\fP instance directly, by calling \fBtermkey_push_bytes\fP(3). This may be useful if the bytes have already been read from the terminal by the application, or even in situations that don't directly involve a terminal filehandle. Because of these situations, it is possible to construct a \fBtermkey\fP instance not associated with a file handle, by passing -1 as the file descriptor. -.PP -A \fBtermkey\fP instance contains a buffer of pending bytes that have been read but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP(3) returns the number of bytes of buffer space currently free in the instance. \fBtermkey_set_buffer_size\fP(3) and \fBtermkey_get_buffer_size\fP(3) can be used to control and return the total size of this buffer. -.SS Key Events -Key events are stored in structures. Each structure holds details of one key event. This 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 */ - } 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. -.TP -.B TERMKEY_TYPE_MOUSE -a mouse button press, release, or movement. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_mouse\fP(3) may be used to interpret it. -.TP -.B TERMKEY_TYPE_POSITION -a cursor position report. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_position\fP(3) may be used to interpret it. -.TP -.B TERMKEY_TYPE_MODEREPORT -an ANSI or DEC mode value report. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_modereport\fP(3) may be used to interpret it. -.TP -.B TERMKEY_TYPE_UNKNOWN_CSI -an unrecognised CSI sequence. The \fIcode\fP structure should be considered opaque; \fBtermkey_interpret_csi\fP(3) may be used 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 -Key events that represent special keys (\fItype\fP is \fBTERMKEY_TYPE_KEYSYM\fP) have with them as symbolic value that identifies the special key, in \fIcode.sym\fP. \fBtermkey_get_keyname\fP(3) may be used to turn this symbolic value into a string, and \fBtermkey_lookup_keyname\fP(3) may be used to turn string names into symbolic values. -.PP -A pair of functions are also provided to convert between key events and strings. \fBtermkey_strfkey\fP(3) converts a key event into a string, and \fBtermkey_strpkey\fP(3) parses a string turning it into a key event. -.PP -Key events may be compared for equallity or ordering by using \fBtermkey_keycmp\fP(3). -.SS Control Flags -Details of the behaviour of a \fBtermkey\fP instance are controlled by two bitmasks of flags. \fBtermkey_set_flags\fP(3) and \fBtermkey_get_flags\fP(3) set or return the flags used to control the general behaviour, and \fBtermkey_set_canonflags\fP(3) and \fBtermkey_get_canonflags\fP(3) set or return the flags that control the key value canonicalisation behaviour performed by \fBtermkey_canonicalise\fP(3). -.PP -The following control flags are recognised. -.TP -.B TERMKEY_FLAG_NOINTERPRET -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 -.SM ASCII -codes they would represent. -.TP -.B TERMKEY_FLAG_RAW -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 -.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 -.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. Setting or clearing this flag in fact sets or clears the \fBTERMKEY_CANON_SPACESYMBOL\fP canonicalisation flag. -.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 -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 \f(CWU+0020\fP Unicode codepoint. -.TP -.B TERMKEY_CANON_DELBS -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 -.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 -.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 ? 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. Note that only a DEC CPR sequence (\f(CWCSI ? R\fP) is recognised, and not the non-DEC prefixed \f(CWCSI R\fP because the latter could be interpreted as the \f(CWF3\fP function key instead. -.SS Mode Reports -The \fBTERMKEY_TYPE_MODEREPORT\fP event type indicates an ANSI or DEC mode report. This is typically sent by a terminal in response to the Request Mode command (\f(CWCSI $p\fP or \f(CWCSI ? $p\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_modereport\fP(3) passing the event structure and pointers to integers to store the result in. -.SS Unrecognised CSIs -The \fBTERMKEY_TYPE_UNKNOWN_CSI\fP event type indicates a CSI sequence that the \fBtermkey\fP does not recognise. It will have been extracted from the stream, but is available to the application to inspect by calling \fBtermkey_interpret_csi\fP(3). It is important that if the application wishes to inspect this sequence it is done immediately, before any other IO operations on the \fBtermkey\fP instance (specifically, before calling \fBtermkey_waitkey\fP() or \fBtermkey_getkey\fP() again), otherwise the buffer space consumed by the sequence will be overwritten. Other types of key event do not suffer this limitation as the \fBTermKeyKey\fP structure is sufficient to contain all the information required. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_waitkey (3), -.BR termkey_getkey (3) diff --git a/man/termkey_advisereadable.3 b/man/termkey_advisereadable.3 deleted file mode 100644 index 2c02c41..0000000 --- a/man/termkey_advisereadable.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH TERMKEY_ADVISEREADABLE 3 -.SH NAME -termkey_advisereadable \- read more bytes from the underlying terminal -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_advisereadable(TermKey *" tk ); -.fi -.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. -.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 -For synchronous usage, \fBtermkey_waitkey\fP(3) performs the input blocking task. -.SH "RETURN VALUE" -\fBtermkey_advisereadable\fP() returns one of the following constants: -.TP -.B TERMKEY_RES_AGAIN -At least one byte was read. -.TP -.B TERMKEY_RES_NONE -No nore bytes were read. -.TP -.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_getkey (3), -.BR termkey_waitkey (3), -.BR termkey_set_waittime (3), -.BR termkey (7) diff --git a/man/termkey_canonicalise.3 b/man/termkey_canonicalise.3 deleted file mode 100644 index 47fb21f..0000000 --- a/man/termkey_canonicalise.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH TERMKEY_CANONICALISE 3 -.SH NAME -termkey_canonicalise \- canonicalise a key event -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "void termkey_canonicalise(TermKey *" tk ", TermKeyKey *" key ); -.fi -.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. -.PP -See \fBtermkey\fP(7) for a list of canonicalisation flags. -.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) diff --git a/man/termkey_get_buffer_remaining.3 b/man/termkey_get_buffer_remaining.3 deleted file mode 100644 index d207865..0000000 --- a/man/termkey_get_buffer_remaining.3 +++ /dev/null @@ -1,23 +0,0 @@ -.TH TERMKEY_GET_BUFFER_REMAINING 3 -.SH NAME -termkey_get_buffer_remaining \- returns the free buffer space -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "size_t termkey_get_buffer_remaining(TermKey *" tk "); -.fi -.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). -.PP -.SH "RETURN VALUE" -\fBtermkey_get_buffer_remaining\fP() returns a size in bytes. -.SH "SEE ALSO" -.BR termkey_push_bytes (3), -.BR termkey_advisereadable (3), -.BR termkey_set_buffer_size (3), -.BR termkey_get_buffer_size (3), -.BR termkey_getkey (3), -.BR termkey (7) diff --git a/man/termkey_get_fd.3 b/man/termkey_get_fd.3 deleted file mode 100644 index 86b60b6..0000000 --- a/man/termkey_get_fd.3 +++ /dev/null @@ -1,19 +0,0 @@ -.TH TERMKEY_GET_FD 3 -.SH NAME -termkey_get_fd \- obtain the file descriptor for the terminal -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "int termkey_get_fd(TermKey *" tk ); -.fi -.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. -.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) diff --git a/man/termkey_get_keyname.3 b/man/termkey_get_keyname.3 deleted file mode 100644 index 14f1426..0000000 --- a/man/termkey_get_keyname.3 +++ /dev/null @@ -1,20 +0,0 @@ -.TH TERMKEY_GET_KEYNAME 3 -.SH NAME -termkey_get_keyname \- return a string name for a symbolic key -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "const char *termkey_get_keyname(TermKey *" tk ", TermKeySym " sym ); -.fi -.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 \fIsym\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). -.SH "RETURN VALUE" -\fBtermkey_get_key\fP() returns a pointer to a string. -.SH "SEE ALSO" -.BR termkey_lookup_keyname (3), -.BR termkey_keyname2sym (3), -.BR termkey_strfkey (3), -.BR termkey (7) diff --git a/man/termkey_getkey.3.sh b/man/termkey_getkey.3.sh deleted file mode 100644 index 32d296d..0000000 --- a/man/termkey_getkey.3.sh +++ /dev/null @@ -1,56 +0,0 @@ -# vim:ft=nroff -cat <<EOF -.TH TERMKEY_GETKEY 3 -.SH NAME -termkey_getkey, termkey_getkey_force \- retrieve the next key event -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_getkey(TermKey *" tk ", TermKeyKey *" key ); -.BI "TermKeyResult termkey_getkey_force(TermKey *" tk ", TermKeyKey *" key ); -.fi -.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: -.in -.TP -.B TERMKEY_RES_KEY -a complete keypress was removed from the buffer, and has been placed in the \fIkey\fP structure. -.TP -.B TERMKEY_RES_AGAIN -a partial keypress event was found in the buffer, but it does not yet contain all the bytes required. An indication of what \fBtermkey_getkey_force\fP() would return has been placed in the \fIkey\fP structure. -.TP -.B TERMKEY_RES_NONE -no bytes are waiting in the buffer. -.TP -.B TERMKEY_RES_EOF - no bytes are ready and the input stream is now closed. -.TP -.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 \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 -Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\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, \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 \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 -EOF -sed "s/\\\\/\\\\\\\\/g" demo-async.c -cat <<EOF -.in -.fi -.SH "SEE ALSO" -.BR termkey_advisereadable (3), -.BR termkey_waitkey (3), -.BR termkey_get_waittime (3), -.BR termkey (7) -EOF diff --git a/man/termkey_interpret_csi.3 b/man/termkey_interpret_csi.3 deleted file mode 100644 index 0939d40..0000000 --- a/man/termkey_interpret_csi.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH TERMKEY_INTERPRET_CSI 3 -.SH NAME -termkey_interpret_csi \- interpret unrecognised CSI sequence -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_interpret_csi(TermKey *" tk ", const TermKeyKey *" key ", " -.BI " long *" args "[], size_t *" nargs ", unsigned long *" cmd ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_interpret_csi\fP() fills in variables in the passed pointers according to the unrecognised CSI sequence event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_UNKNOWN_CSI\fP. Note that it is important to call this function as soon as possible after obtaining a \fBTERMKEY_TYPE_CSI\fP key event; specifically, before calling \fBtermkey_getkey\fP() or \fBtermkey_waitkey\fP() again, as a subsequent call will overwrite the buffer space currently containing this sequence. -.PP -The \fIargs\fP array will be filled with the numerical arguments of the CSI sequence. The number of elements available in this array should be given as the initial value of the value pointed to by \fInargs\fP, which will be adjusted to give the number of arguments actually found when the function returns. The \fIcmd\fP variable will contain the CSI command value. If a leading byte was found (such as '\f(CW?\fP') then it will be bitwise-ored with the command value, shifted up by 8 bits. If an intermediate byte was found (such as '\f(CW$\fP') then it will be bitwise-ored with the command value, shifted up by 16 bits. -.nf -.sp - *cmd = command | (initial << 8) | (intermediate << 16); -.fi -.SH "RETURN VALUE" -If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_UNKNOWN_CSI\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above. -.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_waitkey (3), -.BR termkey_getkey (3), -.BR termkey (7) diff --git a/man/termkey_interpret_modereport.3 b/man/termkey_interpret_modereport.3 deleted file mode 100644 index d778655..0000000 --- a/man/termkey_interpret_modereport.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH TERMKEY_INTERPRET_MODEREPORT 3 -.SH NAME -termkey_interpret_modereport \- interpret opaque mode report data -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_interpret_modereport(TermKey *" tk ", const TermKeyKey *" key ", " -.BI " int *" initial ", int *" mode ", int *" value ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_interpret_modereport\fP() fills in variables in the passed pointers according to the mode report event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_MODEREPORT\fP. -.PP -Any pointer may instead be given as \fBNULL\fP to not return that value. -.PP -The \fIinitial\fP variable will be filled with 0 for an ANSI mode report, or \f(CW'?'\fP for a DEC mode report. The \fImode\fP variable will be filled with the number of the mode, and \fIvalue\fP will be filled with the value from the report. -.SH "RETURN VALUE" -If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_MODEREPORT\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above. -.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_waitkey (3), -.BR termkey_getkey (3), -.BR termkey (7) diff --git a/man/termkey_interpret_mouse.3 b/man/termkey_interpret_mouse.3 deleted file mode 100644 index dbc0c74..0000000 --- a/man/termkey_interpret_mouse.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH TERMKEY_INTERPRET_MOUSE 3 -.SH NAME -termkey_interpret_mouse \- interpret opaque mouse event data -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_interpret_mouse(TermKey *" tk ", const TermKeyKey *" key ", " -.BI " TermKeyMouseEvent *" ev ", int *" button ", int *" line ", int *" col ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_interpret_mouse\fP() fills in variables in the passed pointers according to the mouse event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_MOUSE\fP. -.PP -Any pointer may instead be given as \fBNULL\fP to not return that value. -.PP -The \fIev\fP variable will take one of the following values: -.in -.TP -.B TERMKEY_MOUSE_UNKNOWN -an unknown mouse event. -.TP -.B TERMKEY_MOUSE_PRESS -a mouse button was pressed; \fIbutton\fP will contain its number. -.TP -.B TERMKEY_MOUSE_DRAG -the mouse was moved while holding a button; \fIbutton\fP will contain its number. -.TP -.B TERMKEY_MOUSE_RELEASE -a mouse button was released, or the mouse was moved while no button was pressed. If known, \fIbutton\fP will contain the number of the button released. Not all terminals can report this, so it may be 0 instead. -.PP -The \fIline\fP and \fIcol\fP variables will be filled in with the mouse position, indexed from 1. Note that due to the limited number of bytes in the \fBTermKeyKey\fP structure, the line and column numbers are limited to 2047 and 4095 respectively. -.SH "RETURN VALUE" -If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_MOUSE\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above. -.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_waitkey (3), -.BR termkey_getkey (3), -.BR termkey (7) diff --git a/man/termkey_interpret_position.3 b/man/termkey_interpret_position.3 deleted file mode 100644 index e4fb091..0000000 --- a/man/termkey_interpret_position.3 +++ /dev/null @@ -1,26 +0,0 @@ -.TH TERMKEY_INTERPRET_POSITION 3 -.SH NAME -termkey_interpret_position \- interpret opaque cursor position event data -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_interpret_position(TermKey *" tk ", const TermKeyKey *" key ", " -.BI " int *" line ", int *" col ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_interpret_position\fP() fills in variables in the passed pointers according to the cursor position report event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_POSITION\fP. -.PP -Any pointer may instead be given as \fBNULL\fP to not return that value. -.PP -The \fIline\fP and \fIcol\fP variables will be filled in with the cursor position, indexed from 1. Note that due to the limited number of bytes in the \fBTermKeyKey\fP structure, the line and column numbers are limited to 2047 and 4095 respectively. -.SH "RETURN VALUE" -If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_POSITION\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above. -.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_waitkey (3), -.BR termkey_getkey (3), -.BR termkey (7) diff --git a/man/termkey_keycmp.3 b/man/termkey_keycmp.3 deleted file mode 100644 index 9001815..0000000 --- a/man/termkey_keycmp.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH TERMKEY_KEYCMP 3 -.SH NAME -termkey_keycmp \- compare two key events -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "int termkey_keycmp(TermKey *" tk ", const TermKeyKey *" key1 ", -.BI " const TermKeyKey *" key2 ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_keycmp\fP() compares two key structures and applies a total ordering, returning a value that is negative, zero, or positive, to indicate if the given structures are increasing, identical, or decreasing. Before comparison, copies of both referenced structures are taken, and canonicalised according to the rules for \fBtermkey_canonicalise\fP(3). -.PP -Two structures of differing type are ordered \fBTERMKEY_TYPE_UNICODE\fP, \fBTERMKEY_TYPE_KEYSYM\fP, \fBTERMKEY_TYPE_FUNCTION\fP, \fBTERMKEY_TYPE_MOUSE\fP. Unicode structures are ordered by codepoint, keysym structures are ordered by keysym number, function structures are ordered by function key number, and mouse structures are ordered opaquely by an unspecified but consistent ordering. Within these values, keys different in modifier bits are ordered by the modifiers. -.SH "RETURN VALUE" -\fBtermkey_keycmp\fP() returns an integer greater than, equal to, or less than zero to indicate the relation between the two given key structures. -.SH "SEE ALSO" -.BR termkey_strpkey (3), -.BR termkey_canonicalise (3), -.BR termkey (7) diff --git a/man/termkey_keyname2sym.3 b/man/termkey_keyname2sym.3 deleted file mode 100644 index cd75140..0000000 --- a/man/termkey_keyname2sym.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH TERMKEY_KEYNAME2SYM 3 -.SH NAME -termkey_keyname2sym \- look up a symbolic key value for a string name -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeySym termkey_keyname2sym(TermKey *" tk ", const char *" keyname ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_keyname2sym\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. If the given name is not found, \fBTERMKEY_SYM_UNKNOWN\fP is returned instead. This function is the inverse of \fBtermkey_get_keyname\fP(3), and is a more specific form of \fBtermkey_lookup_keyname\fP(3) which only recognises names as complete strings. -.PP -Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running. -.SH "RETURN VALUE" -\fBtermkey_keyname2sym\fP() returns a symbolic key constant, or \fBTERMKEY_SYM_UNKNOWN\fP. -.SH "SEE ALSO" -.BR termkey_get_keyname (3), -.BR termkey_lookup_keyname (3), -.BR termkey_strpkey (3), -.BR termkey (7) diff --git a/man/termkey_lookup_keyname.3 b/man/termkey_lookup_keyname.3 deleted file mode 100644 index 4525a95..0000000 --- a/man/termkey_lookup_keyname.3 +++ /dev/null @@ -1,23 +0,0 @@ -.TH TERMKEY_LOOKUP_KEYNAME 3 -.SH NAME -termkey_lookup_keyname \- look up a symbolic key value for a string name -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "char *termkey_lookup_keyname(TermKey *" tk ", const char *" keyname ", -.BI " TermKeySym *" sym "); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_lookup_keyname\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. The symbolic value is written to the variable addressed by \fIsym\fP. This function is a more general form of \fBtermkey_keyname2sym\fP(3) because it can recognise a symbolic key name within a longer string, returning a pointer to the remainder of the input after the key name. -.PP -Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running. -.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_get_keyname (3), -.BR termkey_keyname2sym (3), -.BR termkey_strpkey (3), -.BR termkey (7) diff --git a/man/termkey_new.3 b/man/termkey_new.3 deleted file mode 100644 index 02e6774..0000000 --- a/man/termkey_new.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH TERMKEY_NEW 3 -.SH NAME -termkey_new, termkey_destroy \- create or destroy new termkey instance -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TERMKEY_CHECK_VERSION;" -.BI "TermKey *termkey_new(int " fd ", int " flags ); -.BI "TermKey *termkey_new_abstract(const char *" term ", int " flags ); -.BI "void termkey_destroy(TermKey *" tk ); -.fi -.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. -.PP -\fBtermkey_new_abstract\fP() creates a new \fBtermkey\fP() instance with no file handle associated. As this is usually done for handling other sources of terminal byte input, it also takes a string indicating the termtype to use. -.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 -.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 -Before calling any functions in the \fBtermkey\fP library, an application should use the \fBTERMKEY_CHECK_VERSION\fP macro to check that the loaded version of the library is compatible with the version it was compiled against. This should be done early on, ideally just after entering its \fBmain\fP() function. -.SH "RETURN VALUE" -If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure. \fBtermkey_destroy\fP() returns no value. -.SH ERRORS -.TP -.B ENOENT -No driver was able to recognise the given terminal type. -.TP -.B ENOMEM -A call to \fBmalloc\fP(3) failed to allocate memory. -.PP -Additionally, \fBtermkey_new\fP() may fail if \fBfstat\fP(2) or \fBwrite\fP(2) fails on the given file handle. -.SH "SEE ALSO" -.BR termkey_waitkey (3), -.BR termkey_advisereadable (3), -.BR termkey_getkey (3), -.BR termkey_get_flags (3), -.BR termkey_get_fd (3), -.BR termkey_get_buffer_remaining (3), -.BR termkey_get_buffer_size (3), -.BR termkey (7) diff --git a/man/termkey_push_bytes.3 b/man/termkey_push_bytes.3 deleted file mode 100644 index 3761034..0000000 --- a/man/termkey_push_bytes.3 +++ /dev/null @@ -1,23 +0,0 @@ -.TH TERMKEY_PUSH_BYTES 3 -.SH NAME -termkey_push_bytes \- supply more bytes to the input buffer -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "size_t termkey_push_bytes(TermKey *" tk ", const char *" bytes ", size_t " len "); -.fi -.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. -.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. -.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_getkey (3), -.BR termkey_advisereadable (3), -.BR termkey (7) diff --git a/man/termkey_set_buffer_size.3 b/man/termkey_set_buffer_size.3 deleted file mode 100644 index b3023fb..0000000 --- a/man/termkey_set_buffer_size.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH TERMKEY_SET_BUFFER_SIZE 3 -.SH NAME -termkey_set_buffer_size, termkey_get_buffer_size \- control the buffer size -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "int termkey_set_buffer_size(TermKey *" tk ", size_t " size ); -.BI "size_t termkey_get_buffer_size(TermKey *" tk ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_set_buffer_size\fP() changes the size of the buffer space in the \fBtermkey\fP(7) instance to that given by \fIsize\fP. Any bytes pending in the buffer will be preserved when resizing, though they will be truncated if the new size is smaller than the total number of bytes in the buffer. -.PP -\fBtermkey_get_buffer_size\fP() returns the size of the buffer set by the last call to \fBtermkey_set_buffer_size\fP(), or the default initial size of 256 bytes. -.SH "RETURN VALUE" -\fBtermkey_set_buffer_size\fP() returns a true value, or zero if an error occurs. \fBtermkey_get_buffer_size\fP() returns the current buffer size in bytes. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_get_buffer_remaining (3), -.BR termkey (7) diff --git a/man/termkey_set_canonflags.3 b/man/termkey_set_canonflags.3 deleted file mode 100644 index 027bd37..0000000 --- a/man/termkey_set_canonflags.3 +++ /dev/null @@ -1,21 +0,0 @@ -.TH TERMKEY_SET_CANONFLAGS 3 -.SH NAME -termkey_set_canonflags, termkey_get_canonflags \- control the canonicalisation flags -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "void termkey_set_canonflags(TermKey *" tk ", int " newflags ); -.BI "int termkey_get_canonflags(TermKey *" tk ); -.fi -.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. -.PP -\fBtermkey_get_canonflags\fP() returns the value set by the last call to \fBtermkey_set_canonflags\fP(). -.SH "RETURN VALUE" -\fBtermkey_set_canonflags\fP() returns no value. \fBtermkey_get_canonflags\fP() returns the current canonicalisation flags. -.SH "SEE ALSO" -.BR termkey_canonicalise (3), -.BR termkey (7) diff --git a/man/termkey_set_flags.3 b/man/termkey_set_flags.3 deleted file mode 100644 index 10bdcac..0000000 --- a/man/termkey_set_flags.3 +++ /dev/null @@ -1,21 +0,0 @@ -.TH TERMKEY_SET_FLAGS 3 -.SH NAME -termkey_set_flags, termkey_get_flags \- control the operational flags -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "void termkey_set_flags(TermKey *" tk ", int " newflags ); -.BI "int termkey_get_flags(TermKey *" tk ); -.fi -.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. -.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. -.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) diff --git a/man/termkey_set_waittime.3 b/man/termkey_set_waittime.3 deleted file mode 100644 index 972c03f..0000000 --- a/man/termkey_set_waittime.3 +++ /dev/null @@ -1,22 +0,0 @@ -.TH TERMKEY_SET_WAITTIME 3 -.SH NAME -termkey_set_waittime, termkey_get_waittime \- control the wait time for multibyte sequences -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "void termkey_set_waittime(TermKey *" tk ", int " msec ); -.BI "int termkey_get_waittime(TermKey *" tk ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_set_waittime\fP() sets the number of miliseconds that \fBtermkey_waitkey\fP(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one. -.PP -\fBtermkey_get_waittime\fP() returns the value set by the last call to \fBtermkey_set_waittime\fP(), or the default value if a different has not been set. -.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_getkey (3), -.BR termkey_waitkey (3), -.BR termkey (7) diff --git a/man/termkey_start.3 b/man/termkey_start.3 deleted file mode 100644 index 1de0edf..0000000 --- a/man/termkey_start.3 +++ /dev/null @@ -1,25 +0,0 @@ -.TH TERMKEY_START 3 -.SH NAME -termkey_start, termkey_stop, termkey_is_started \- enable or disable terminal operations -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "int termkey_start(TermKey *" tk ); -.BI "int termkey_stop(TermKey *" tk ); -.sp -.BI "int termkey_is_started(TermKey *" tk ); -.fi -.sp -Link with \fI\-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_start\fP() enables the terminal IO operations of the given \fBtermkey\fP(7) instance, including sending a terminal control sequence and setting the \fBtermios\fP(3) modes required. -.PP -\fBtermkey_stop\fP() disables terminal IO operations, by reversing the steps taken by \fBtermkey_start\fP(). A newly-constructed \fBtermkey\fP instance will have terminal IO enabled already. -.PP -\fBtermkey_is_started\fP() enquires whether terminal IO is currently enabled. -.SH "RETURN VALUE" -If successful, \fBtermkey_start\fP() and \fBtermkey_stop\fP() return a true value. On failure, zero is returned with \fIerrno\fP set to indicate the failure. \fBtermkey_is_started\fP() returns true or false to indicate whether terminal IO is currently enabled. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey (7) diff --git a/man/termkey_strfkey.3 b/man/termkey_strfkey.3 deleted file mode 100644 index 68b301e..0000000 --- a/man/termkey_strfkey.3 +++ /dev/null @@ -1,59 +0,0 @@ -.TH TERMKEY_STRFKEY 3 -.SH NAME -termkey_strfkey \- format a string representing a key event -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "size_t termkey_strfkey(TermKey *" tk ", char *" buffer ", size_t " len ", -.BI " TermKeyKey *" key ", TermKeyFormat " format ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_strfkey\fP() formats a string buffer to contain a human-readable representation of a key event. It fills the \fIbuffer\fP in a way analogous to the \fBsnprintf\fP(3) or \fBstrftime\fP(3) standard library functions. This function used to be called \fBtermkey_snprint_key\fP() but was renamed after version 0.6. -.PP -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. "\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 "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP". -.TP -.B TERMKEY_FORMAT_ALTISMETA -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 "\f(CW<brackets>\fP". -.TP -.B TERMKEY_FORMAT_SPACEMOD -Use spaces instead of hyphens to separate the modifier name(s) from the base key name. -.TP -.B TERMKEY_FORMAT_LOWERMOD -Use lowercase for the modifier name. -.TP -.B TERMKEY_FORMAT_LOWERSPACE -Use lowercase with spaces in for the key name instead of camelCase (for example "\f(CWpage down\fP" instead of "\f(CWPageDown\fP"). -.TP -.B TERMKEY_FORMAT_MOUSE_POS -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 -.B TERMKEY_FORMAT_VIM -Shortcut to set \fBALTISMETA\fP and \fBWRAPBRACKET\fP, to give an output close to the format the \fIvim\fP editor uses. -.TP -.B TERMKEY_FORMAT_URWID -Shortcut to set \fBALTISMETA\fP, \fBLONGMOD\fP, \fBLOWERMOD\fP, \fBSPACEMOD\fP and \fBLOWERSPACE\fP, to give an output close to the format the \fIurwid\fP python library uses. -.PP -When formatting a \fBTERMKEY_TYPE_UNICODE\fP key structure, this function uses the \fIutf8\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 \fIcode.number\fP member. This can be convenient when the key structure is being constructed programatically by user code. -.SH "RETURN VALUE" -\fBtermkey_strfkey\fP() returns the number of characters written to \fIbuffer\fP. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_getkey (3), -.BR termkey_waitkey (3), -.BR termkey_get_keyname (3), -.BR termkey_strpkey (3), -.BR termkey (7) diff --git a/man/termkey_strpkey.3 b/man/termkey_strpkey.3 deleted file mode 100644 index fd90e0e..0000000 --- a/man/termkey_strpkey.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH TERMKEY_STRPKEY 3 -.SH NAME -termkey_strpkey \- parse a string representing a key event -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "char *termkey_strpkey(TermKey *" tk ", const char *" str ", -.BI " TermKeyKey *" key ", TermKeyFormat " format ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_strpkey\fP(3) parses a string buffer containing a human-readable representation of a key event. It fills the \fIkey\fP structure from the results of this parsing, similar to the \fBstrptime\fP(3) standard library function. -.PP -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. "\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 "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP". -.TP -.B TERMKEY_FORMAT_ALTISMETA -Expect the name "\f(CWMeta\fP" or the letter "\f(CWM\fP" instead of "\f(CWAlt\fP" or "\f(CWA\fP". -.TP -.B TERMKEY_FORMAT_SPACEMOD -Expect spaces instead of hyphens to separate the modifer name(s) from the base key name. -.TP -.B TERMKEY_FORMAT_LOWERMOD -Expect lowercase for the modifier name. -.TP -.B TERMKEY_FORMAT_LOWERSPACE -Expect lowercase with spaces in for the key name instead of camelCase (for example "\f(CWpage down\fP" instead of "\f(CWPageDown\fP"). -.PP -Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3). -.PP -The \fBTERMKEY_FORMAT_WRAPBRACKET\fP and \fBTERMKEY_FORMAT_MOUSE_POS\fP options are currently not supported by \fBtermkey_strpkey\fP(). When returning a \fBTERMKEY_TYPE_UNICODE\fP key structure, this function will fill in the \fIutf8\fP member. -.SH "RETURN VALUE" -After a successful parse, \fBtermkey_strpkey\fP() returns a pointer to the first character of the input it did not consume. If the input string contains more characters then this will point at the first character beyond. If the entire input string was consumed, then this will point at a null byte. If \fBtermkey_strpkey\fP() fails to parse, it returns \fBNULL\fP. After a failed parse, the \fIkey\fP structure may contain partial or invalid results. The structure will only be valid if the function returns a non-\fBNULL\fP result. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_strfkey (3), -.BR termkey_keycmp (3), -.BR termkey (7) diff --git a/man/termkey_waitkey.3.sh b/man/termkey_waitkey.3.sh deleted file mode 100644 index 7f11228..0000000 --- a/man/termkey_waitkey.3.sh +++ /dev/null @@ -1,45 +0,0 @@ -# vim:ft=nroff -cat <<EOF -.TH TERMKEY_WAITKEY 3 -.SH NAME -termkey_waitkey \- wait for and retrieve the next key event -.SH SYNOPSIS -.nf -.B #include <termkey.h> -.sp -.BI "TermKeyResult termkey_waitkey(TermKey *" tk ", TermKeyKey *" key ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_waitkey\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. 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). -.SH "RETURN VALUE" -\fBtermkey_waitkey\fP() returns one of the following constants: -.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_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 \fICtrl-C\fP. -.PP -.in +4n -.nf -EOF -sed "s/\\\\/\\\\\\\\/g" demo.c -cat <<EOF -.in -.fi -.SH "SEE ALSO" -.BR termkey_getkey (3), -.BR termkey_set_waittime (3), -.BR termkey (7) -EOF |