From 9aaf16888c9bd1ab63f0336f6becca87525118c6 Mon Sep 17 00:00:00 2001 From: Paul LeoNerd Evans Date: Thu, 6 Nov 2008 19:40:28 +0000 Subject: Include demo.c and demo-async.c in the manpages under an EXAMPLE section --- Makefile | 7 ++++- termkey_getkey.3 | 74 --------------------------------------------- termkey_getkey.3.sh | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++ termkey_waitkey.3 | 31 ------------------- termkey_waitkey.3.sh | 42 ++++++++++++++++++++++++++ 5 files changed, 133 insertions(+), 106 deletions(-) delete mode 100644 termkey_getkey.3 create mode 100644 termkey_getkey.3.sh delete mode 100644 termkey_waitkey.3 create mode 100644 termkey_waitkey.3.sh diff --git a/Makefile b/Makefile index 8fcceef..5a08630 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,7 @@ ifeq ($(DEBUG),1) CFLAGS_DEBUG=-ggdb -DDEBUG endif -all: demo demo-async +all: demo demo-async doc demo: libtermkey.so demo.c $(CC) $(CFLAGS) $(CFLAGS_DEBUG) -o $@ $^ @@ -29,6 +29,11 @@ libtermkey.so: termkey.o driver-csi.o driver-ti.o %.o: %.c termkey.h termkey-internal.h $(CC) $(CFLAGS) $(CFLAGS_DEBUG) -Wall -std=c99 -fPIC -o $@ -c $< +doc: termkey_waitkey.3 termkey_getkey.3 + +%.3: %.3.sh + sh $< >$@ + .PHONY: clean clean: rm -f *.o demo diff --git a/termkey_getkey.3 b/termkey_getkey.3 deleted file mode 100644 index f77caa0..0000000 --- a/termkey_getkey.3 +++ /dev/null @@ -1,74 +0,0 @@ -.TH TERMKEY_GETKEY 3 -.SH NAME -termkey_getkey, termkey_getkey_force \- retrieve the next key event -.SH SYNOPSIS -.nf -.B #include -.sp -.BI "termkey_result termkey_getkey(termkey_t *" tk ", termkey_key *" key ); -.br -.BI "termkey_result termkey_getkey_force(termkey_t *" tk ", termkey_key *" key ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_getkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will return \fBTERMKEY_RES_NONE\fP. If the buffer contains a partial keypress event which does not yet contain all the bytes required, it will return \fBTERMKEY_RES_AGAIN\fP. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. -.PP -\fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters. -.PP -Neither of these functions will block or perform any IO operations on the underlying filehandle. 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(). -.PP -The \fItermkey_key\fP structure is defined as follows: -.PP -.in +4n -.nf -typedef struct { - termkey_type type; - union { - long codepoint; /* TERMKEY_TYPE_UNICODE */ - int number; /* TERMKEY_TYPE_FUNCTION */ - termkey_keysym sym; /* TERMKEY_TYPE_KEYSYM */ - } code; - int modifiers; - char utf8[7]; -} termkey_key; -.fi -.in -.PP -The \fItype\fP field indicates the type of event, and determines which of the members of the \fIcode\fP union is valid. It will be one of the following constants: -.TP -.B TERMKEY_TYPE_UNICODE -a Unicode codepoint -.TP -.B TERMKEY_TYPE_FUNCTION -a numbered function key -.TP -.B TERMKEY_TYPE_KEYSYM -a symbolic key -.PP -The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP. -.PP -The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_UNICODE\fP. It should not be read for other events. -.PP -To convert the \fIsym\fP to a symbolic name, see \fBtermkey_get_keyname\fP(3) function. It may instead be easier to convert the entire key event structure to a string, using \fBtermkey_snprint_key\fP(3). -.SH "RETURN VALUE" -\fBtermkey_getkey\fP() and \fBtermkey_getkey_force\fP() return one of the following constants: -.TP -.B TERMKEY_RES_NONE -No key event is ready. -.TP -.B TERMKEY_RES_KEY -A key event as been provided. -.TP -.B TERMKEY_RES_EOF -No key events are ready and the terminal has been closed, so no more will arrive. -.TP -.B TERMKEY_RES_AGAIN -No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP(). -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_advisereadable (3), -.BR termkey_waitkey (3), -.BR termkey_setwaittime (3), -.BR termkey_get_keyname (3), -.BR termkey_snprint_key (3) diff --git a/termkey_getkey.3.sh b/termkey_getkey.3.sh new file mode 100644 index 0000000..1b78948 --- /dev/null +++ b/termkey_getkey.3.sh @@ -0,0 +1,85 @@ +# vim:ft=nroff +cat < +.sp +.BI "termkey_result termkey_getkey(termkey_t *" tk ", termkey_key *" key ); +.br +.BI "termkey_result termkey_getkey_force(termkey_t *" tk ", termkey_key *" key ); +.fi +.sp +Link with \fI-ltermkey\fP. +.SH DESCRIPTION +\fBtermkey_getkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will return \fBTERMKEY_RES_NONE\fP. If the buffer contains a partial keypress event which does not yet contain all the bytes required, it will return \fBTERMKEY_RES_AGAIN\fP. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. +.PP +\fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters. +.PP +Neither of these functions will block or perform any IO operations on the underlying filehandle. 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(). +.PP +The \fItermkey_key\fP structure is defined as follows: +.PP +.in +4n +.nf +typedef struct { + termkey_type type; + union { + long codepoint; /* TERMKEY_TYPE_UNICODE */ + int number; /* TERMKEY_TYPE_FUNCTION */ + termkey_keysym sym; /* TERMKEY_TYPE_KEYSYM */ + } code; + int modifiers; + char utf8[7]; +} termkey_key; +.fi +.in +.PP +The \fItype\fP field indicates the type of event, and determines which of the members of the \fIcode\fP union is valid. It will be one of the following constants: +.TP +.B TERMKEY_TYPE_UNICODE +a Unicode codepoint +.TP +.B TERMKEY_TYPE_FUNCTION +a numbered function key +.TP +.B TERMKEY_TYPE_KEYSYM +a symbolic key +.PP +The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP. +.PP +The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_UNICODE\fP. It should not be read for other events. +.PP +To convert the \fIsym\fP to a symbolic name, see \fBtermkey_get_keyname\fP(3) function. It may instead be easier to convert the entire key event structure to a string, using \fBtermkey_snprint_key\fP(3). +.SH "RETURN VALUE" +\fBtermkey_getkey\fP() and \fBtermkey_getkey_force\fP() return one of the following constants: +.TP +.B TERMKEY_RES_NONE +No key event is ready. +.TP +.B TERMKEY_RES_KEY +A key event as been provided. +.TP +.B TERMKEY_RES_EOF +No key events are ready and the terminal has been closed, so no more will arrive. +.TP +.B TERMKEY_RES_AGAIN +No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP(). +.SH EXAMPLE +The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles. +.PP +.in +4n +`sed i.br demo-async.c` +.in +.nf +.fi +.SH "SEE ALSO" +.BR termkey_new (3), +.BR termkey_advisereadable (3), +.BR termkey_waitkey (3), +.BR termkey_setwaittime (3), +.BR termkey_get_keyname (3), +.BR termkey_snprint_key (3) +EOF diff --git a/termkey_waitkey.3 b/termkey_waitkey.3 deleted file mode 100644 index 9079dcb..0000000 --- a/termkey_waitkey.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH TERMKEY_WAITKEY 3 -.SH NAME -termkey_waitkey \- wait for and retrieve the next key event -.SH SYNOPSIS -.nf -.B #include -.sp -.BI "termkey_result termkey_waitkey(termkey_t *" tk ", termkey_key *" key ); -.fi -.sp -Link with \fI-ltermkey\fP. -.SH DESCRIPTION -\fBtermkey_waitkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. -.PP -For details of the \fBtermkey_key\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_setwaittime\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. -.SH "SEE ALSO" -.BR termkey_new (3), -.BR termkey_getkey (3), -.BR termkey_setwaittime (3), -.BR termkey_get_keyname (3), -.BR termkey_snprint_key (3) diff --git a/termkey_waitkey.3.sh b/termkey_waitkey.3.sh new file mode 100644 index 0000000..c14bbd7 --- /dev/null +++ b/termkey_waitkey.3.sh @@ -0,0 +1,42 @@ +# vim:ft=nroff +cat < +.sp +.BI "termkey_result termkey_waitkey(termkey_t *" tk ", termkey_key *" key ); +.fi +.sp +Link with \fI-ltermkey\fP. +.SH DESCRIPTION +\fBtermkey_waitkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP. +.PP +For details of the \fBtermkey_key\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_setwaittime\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. +.SH EXAMPLE +The following example program prints details of every keypress until the user presses "Ctrl-C". +.PP +.in +4n +`sed i.br demo.c` +.in +.nf +.fi +.SH "SEE ALSO" +.BR termkey_new (3), +.BR termkey_getkey (3), +.BR termkey_setwaittime (3), +.BR termkey_get_keyname (3), +.BR termkey_snprint_key (3) +EOF -- cgit v1.2.3-70-g09d2