1TERMKEY_WAITKEY(3) Library Functions Manual TERMKEY_WAITKEY(3)
2
6 termkey_waitkey - wait for and retrieve the next key event
7
9 #include <termkey.h>
10 TermKeyResult termkey_waitkey(TermKey *tk, TermKeyKey *key);
12 Link with -ltermkey.
14
16 termkey_waitkey() attempts to retrieve a single keypress event from the
17 termkey(7) instance buffer, and put it in the structure referred to by
18 key. If successful it will return TERMKEY_RES_KEY to indicate that the
19 structure now contains a new keypress event. If nothing is in the buf‐
20 fer it will block until one is available. If no events are ready and
21 the input stream is now closed, will return TERMKEY_RES_EOF. If no
22 filehandle is associated with this instance, TERMKEY_RES_ERROR is re‐
23 turned with errno set to EBADF.
24 Before returning, this function canonicalises the key structure accord‐
26 ing to the rules given for termkey_canonicalise(3).
27 Some keypresses generate multiple bytes from the terminal. Because
29 there may be network or other delays between the terminal and an appli‐
30 cation using termkey, termkey_waitkey() will attempt to wait for the
31 remaining bytes to arrive if it detects the start of a multibyte se‐
32 quence. If no more bytes arrive within a certain time, then the bytes
33 will be reported as they stand, even if this results in interpreting a
34 partially-complete Escape sequence as a literal Escape key followed by
35 some normal letters or other symbols. The amount of time to wait can be
36 set by termkey_set_waittime(3).
37
39 termkey_waitkey() returns one of the following constants:
40 TERMKEY_RES_KEY
42 A key event as been provided.
43 TERMKEY_RES_EOF
45 No key events are ready and the terminal has been closed, so no
46 more will arrive.
47 TERMKEY_RES_ERROR
49 An IO error occurred. errno will be preserved. If the error is
50 EINTR then this will only be returned if TERMKEY_FLAG_EINTR flag
51 is not set; if it is then the IO operation will be retried in‐
52 stead. If this is called with terminal IO stopped, due to
53 termkey_stop(3) then errno will be set to EINVAL.
54
56 The following example program prints details of every keypress until
57 the user presses Ctrl-C.
58 // we want optarg
60 #define _XOPEN_SOURCE 600
61 #include <stdio.h>
63 #include <unistd.h>
64 #include <errno.h>
65 #include "termkey.h"
67 int main(int argc, char *argv[])
69 {
70 TERMKEY_CHECK_VERSION;
71 int mouse = 0;
73 int mouse_proto = 0;
74 TermKeyFormat format = TERMKEY_FORMAT_VIM;
75 char buffer[50];
77 TermKey *tk;
78 int opt;
80 while((opt = getopt(argc, argv, "m::p:")) != -1) {
81 switch(opt) {
82 case 'm':
83 if(optarg)
84 mouse = atoi(optarg);
85 else
86 mouse = 1000;
87 break;
89 case 'p':
91 mouse_proto = atoi(optarg);
92 break;
93 default:
95 fprintf(stderr, "Usage: %s [-m]\n", argv[0]);
96 return 1;
97 }
98 }
99 tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL|TERMKEY_FLAG_CTRLC);
101 if(!tk) {
103 fprintf(stderr, "Cannot allocate termkey instance\n");
104 exit(1);
105 }
106 if(termkey_get_flags(tk) & TERMKEY_FLAG_UTF8)
108 printf("Termkey in UTF-8 mode\n");
109 else if(termkey_get_flags(tk) & TERMKEY_FLAG_RAW)
110 printf("Termkey in RAW mode\n");
111 TermKeyResult ret;
113 TermKeyKey key;
114 if(mouse) {
116 printf("\033[?%dhMouse mode active\n", mouse);
117 if(mouse_proto)
118 printf("\033[?%dh", mouse_proto);
119 }
120 while((ret = termkey_waitkey(tk, &key)) != TERMKEY_RES_EOF) {
122 if(ret == TERMKEY_RES_KEY) {
123 termkey_strfkey(tk, buffer, sizeof buffer, &key, format);
124 if(key.type == TERMKEY_TYPE_MOUSE) {
125 int line, col;
126 termkey_interpret_mouse(tk, &key, NULL, NULL, &line, &col);
127 printf("%s at line=%d, col=%d\n", buffer, line, col);
128 }
129 else if(key.type == TERMKEY_TYPE_POSITION) {
130 int line, col;
131 termkey_interpret_position(tk, &key, &line, &col);
132 printf("Cursor position report at line=%d, col=%d\n", line, col);
133 }
134 else if(key.type == TERMKEY_TYPE_MODEREPORT) {
135 int initial, mode, value;
136 termkey_interpret_modereport(tk, &key, &initial, &mode, &value);
137 printf("Mode report %s mode %d = %d\n", initial ? "DEC" : "ANSI", mode, value);
138 }
139 else if(key.type == TERMKEY_TYPE_UNKNOWN_CSI) {
140 long args[16];
141 size_t nargs = 16;
142 unsigned long command;
143 termkey_interpret_csi(tk, &key, args, &nargs, &command);
144 printf("Unrecognised CSI %c %ld;%ld %c%c\n", (char)(command >> 8), args[0], args[1], (char)(command >> 16), (char)command);
145 }
146 else {
147 printf("Key %s\n", buffer);
148 }
149 if(key.type == TERMKEY_TYPE_UNICODE &&
151 key.modifiers & TERMKEY_KEYMOD_CTRL &&
152 (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
153 break;
154 if(key.type == TERMKEY_TYPE_UNICODE &&
156 key.modifiers == 0 &&
157 key.code.codepoint == '?') {
158 // printf("\033[?6n"); // DECDSR 6 == request cursor position
159 printf("\033[?1$p"); // DECRQM == request mode, DEC origin mode
160 fflush(stdout);
161 }
162 }
163 else if(ret == TERMKEY_RES_ERROR) {
164 if(errno != EINTR) {
165 perror("termkey_waitkey");
166 break;
167 }
168 printf("Interrupted by signal\n");
169 }
170 }
171 if(mouse)
173 printf("\033[?%dlMouse mode deactivated\n", mouse);
174 termkey_destroy(tk);
176 }
177
179 This function is not available on Windows.
180
182 termkey_getkey(3), termkey_set_waittime(3), termkey(7)
183 TERMKEY_WAITKEY(3)