aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul LeoNerd Evans <leonerd@leonerd.org.uk>2008-12-10 00:38:21 +0000
committerPaul LeoNerd Evans <leonerd@leonerd.org.uk>2008-12-10 00:38:21 +0000
commit696c1455998a8282b23155449eda880aab157858 (patch)
tree7331221c1b9695a95e4c5ed2a7a435477ef715ac
parentef669c134d9352d88ae020803c7ee280083523f8 (diff)
downloadtermo-696c1455998a8282b23155449eda880aab157858.tar.gz
termo-696c1455998a8282b23155449eda880aab157858.tar.xz
termo-696c1455998a8282b23155449eda880aab157858.zip
Make termkey_getkey() set a peeked key structure if it returns TERMKEY_RET_AGAIN
-rw-r--r--termkey.c5
-rw-r--r--termkey_getkey.3.sh29
2 files changed, 20 insertions, 14 deletions
diff --git a/termkey.c b/termkey.c
index b40059d..4df1294 100644
--- a/termkey.c
+++ b/termkey.c
@@ -679,6 +679,11 @@ termkey_result termkey_getkey(termkey_t *tk, termkey_key *key)
if(ret == TERMKEY_RES_KEY)
eat_bytes(tk, nbytes);
+ if(ret == TERMKEY_RES_AGAIN)
+ /* Call peekkey() again in force mode to obtain whatever it can */
+ (void)peekkey(tk, key, 1, &nbytes);
+ /* Don't eat it yet though */
+
return ret;
}
diff --git a/termkey_getkey.3.sh b/termkey_getkey.3.sh
index 00d9013..8a6a372 100644
--- a/termkey_getkey.3.sh
+++ b/termkey_getkey.3.sh
@@ -14,7 +14,20 @@ termkey_getkey, termkey_getkey_force \- retrieve the next key event
.sp
Link with \fI-ltermkey\fP.
.SH DESCRIPTION
-\fBtermkey_getkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. 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.
+\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
+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(3)\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.
.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
@@ -54,19 +67,7 @@ The \fIutf8\fP field is only set on events whose \fItype\fP is \fBTERMKEY_TYPE_U
.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().
+\fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP or \fBTERMKEY_RES_EOF\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP.
.SH EXAMPLE
The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles.
.PP