1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.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 occurred. \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
// we want optarg
#define _XOPEN_SOURCE 600
#include <stdio.h>
#include <unistd.h>
#include <errno.h>
#include "termkey.h"
int main(int argc, char *argv[])
{
TERMKEY_CHECK_VERSION;
int mouse = 0;
int mouse_proto = 0;
TermKeyFormat format = TERMKEY_FORMAT_VIM;
char buffer[50];
TermKey *tk;
int opt;
while((opt = getopt(argc, argv, "m::p:")) != -1) {
switch(opt) {
case 'm':
if(optarg)
mouse = atoi(optarg);
else
mouse = 1000;
break;
case 'p':
mouse_proto = atoi(optarg);
break;
default:
fprintf(stderr, "Usage: %s [-m]\\n", argv[0]);
return 1;
}
}
tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL|TERMKEY_FLAG_CTRLC);
if(!tk) {
fprintf(stderr, "Cannot allocate termkey instance\\n");
exit(1);
}
if(termkey_get_flags(tk) & TERMKEY_FLAG_UTF8)
printf("Termkey in UTF-8 mode\\n");
else if(termkey_get_flags(tk) & TERMKEY_FLAG_RAW)
printf("Termkey in RAW mode\\n");
TermKeyResult ret;
TermKeyKey key;
if(mouse) {
printf("\\033[?%dhMouse mode active\\n", mouse);
if(mouse_proto)
printf("\\033[?%dh", mouse_proto);
}
while((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
if(ret == TERMKEY_RES_KEY) {
termkey_strfkey(tk, buffer, sizeof buffer, &key, format);
if(key.type == TERMKEY_TYPE_MOUSE) {
int line, col;
termkey_interpret_mouse(tk, &key, NULL, NULL, &line, &col);
printf("%s at line=%d, col=%d\\n", buffer, line, col);
}
else if(key.type == TERMKEY_TYPE_POSITION) {
int line, col;
termkey_interpret_position(tk, &key, &line, &col);
printf("Cursor position report at line=%d, col=%d\\n", line, col);
}
else if(key.type == TERMKEY_TYPE_MODEREPORT) {
int initial, mode, value;
termkey_interpret_modereport(tk, &key, &initial, &mode, &value);
printf("Mode report %s mode %d = %d\\n", initial ? "DEC" : "ANSI", mode, value);
}
else if(key.type == TERMKEY_TYPE_UNKNOWN_CSI) {
long args[16];
size_t nargs = 16;
unsigned long command;
termkey_interpret_csi(tk, &key, args, &nargs, &command);
printf("Unrecognised CSI %c %ld;%ld %c%c\\n", (char)(command >> 8), args[0], args[1], (char)(command >> 16), (char)command);
}
else {
printf("Key %s\\n", buffer);
}
if(key.type == TERMKEY_TYPE_UNICODE &&
key.modifiers & TERMKEY_KEYMOD_CTRL &&
(key.code.codepoint == 'C' || key.code.codepoint == 'c'))
break;
if(key.type == TERMKEY_TYPE_UNICODE &&
key.modifiers == 0 &&
key.code.codepoint == '?') {
// printf("\\033[?6n"); // DECDSR 6 == request cursor position
printf("\\033[?1$p"); // DECRQM == request mode, DEC origin mode
fflush(stdout);
}
}
else if(ret == TERMKEY_RES_ERROR) {
if(errno != EINTR) {
perror("termkey_waitkey");
break;
}
printf("Interrupted by signal\\n");
}
}
if(mouse)
printf("\\033[?%dlMouse mode deactivated\\n", mouse);
termkey_destroy(tk);
}
.in
.fi
.SH COMPATIBILITY
This function is not available on Windows.
.SH "SEE ALSO"
.BR termkey_getkey (3),
.BR termkey_set_waittime (3),
.BR termkey (7)
|
