1TERMKEY_WAITKEY(3)         Library Functions Manual         TERMKEY_WAITKEY(3)
2
3
4

NAME

6       termkey_waitkey - wait for and retrieve the next key event
7

SYNOPSIS

9       #include <termkey.h>
10
11       TermKeyResult termkey_waitkey(TermKey *tk, TermKeyKey *key);
12
13       Link with -ltermkey.
14

DESCRIPTION

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
25       Before returning, this function canonicalises the key structure accord‐
26       ing to the rules given for termkey_canonicalise(3).
27
28       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

RETURN VALUE

39       termkey_waitkey() returns one of the following constants:
40
41       TERMKEY_RES_KEY
42              A key event as been provided.
43
44       TERMKEY_RES_EOF
45              No  key events are ready and the terminal has been closed, so no
46              more will arrive.
47
48       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

EXAMPLE

56       The following example program prints details of  every  keypress  until
57       the user presses Ctrl-C.
58
59           // we want optarg
60           #define _XOPEN_SOURCE 600
61
62           #include <stdio.h>
63           #include <unistd.h>
64           #include <errno.h>
65
66           #include "termkey.h"
67
68           int main(int argc, char *argv[])
69           {
70             TERMKEY_CHECK_VERSION;
71
72             int mouse = 0;
73             int mouse_proto = 0;
74             TermKeyFormat format = TERMKEY_FORMAT_VIM;
75
76             char buffer[50];
77             TermKey *tk;
78
79             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
88                 break;
89
90               case 'p':
91                 mouse_proto = atoi(optarg);
92                 break;
93
94               default:
95                 fprintf(stderr, "Usage: %s [-m]\n", argv[0]);
96                 return 1;
97               }
98             }
99
100             tk = termkey_new(0, TERMKEY_FLAG_SPACESYMBOL|TERMKEY_FLAG_CTRLC);
101
102             if(!tk) {
103               fprintf(stderr, "Cannot allocate termkey instance\n");
104               exit(1);
105             }
106
107             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
112             TermKeyResult ret;
113             TermKeyKey key;
114
115             if(mouse) {
116               printf("\033[?%dhMouse mode active\n", mouse);
117               if(mouse_proto)
118                 printf("\033[?%dh", mouse_proto);
119             }
120
121             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
150                 if(key.type == TERMKEY_TYPE_UNICODE &&
151                    key.modifiers & TERMKEY_KEYMOD_CTRL &&
152                    (key.code.codepoint == 'C' || key.code.codepoint == 'c'))
153                   break;
154
155                 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
172             if(mouse)
173               printf("\033[?%dlMouse mode deactivated\n", mouse);
174
175             termkey_destroy(tk);
176           }
177

COMPATIBILITY

179       This function is not available on Windows.
180

SEE ALSO

182       termkey_getkey(3), termkey_set_waittime(3), termkey(7)
183
184
185
186                                                            TERMKEY_WAITKEY(3)
Impressum