1YASCREEN(3) User-Manual YASCREEN(3)
2
6 yascreen - Yet Another Screen Library (curses replacement for daemons
7 and embedded apps)
8
12 #include <yascreen.h>
13
18 • small footprint
19 • does not have external dependencies
21 • allows both internal and external event loop
23 • allows stdin/stdout or external input/output (can work over
25 socket)
26 • supports basic set of telnet sequences, making it suitable for
28 built-in terminal interfaces for daemons
29 • supports a limited set of input keystroke sequences
31 • fully unicode compatible (parts of this depend on wcwidth in
33 libc)
34 • supports utf8 verification of input
36 • supports utf8 input and wide character input
38 • supports non-utf8 input mode
40 • relies only on a limited subset of ansi/xterm ESC sequences,
42 making it compatible with mostly all modern terminals (in‐
43 spired by linenoise ⟨https://github.com/antirez/linenoise⟩)
44 • there is no curses API and ancient terminal compatibility,
46 hence less bloat
47 • there is no autoconf - there is no need to have one
49 • clean API with opaque private data, usable from C/C++
51 • easy cross compilation setup (by setting CC, AR, STRIP and
53 RANLIB)
54 Current development is done on Linux, with additional testing on Open‐
58 BSD/FreeBSD; other platforms may need minimal fixes.
59 On *BSD a gmake is required to build.
62
65 yascreen uses an opaque data structure, allocated by the library and
66 dynamically resized when needed - yascreen_init(int sx, int sy) /
67 yascreen_resize(yascreen *s, int sx, int sy). An application may spec‐
68 ify (0,0) for both calls to let yascreen detect the size or use a fixed
69 size.
70 There are two modes of operation - telnet protocol over socket or run‐
73 ning in terminal. For sockets the event loop would typically be handled
74 outside of the library while for terminals a built-in event loop may be
75 used.
76 Modes of operation can be modified at runtime.
79 For terminal use signal handling (SIGWINCH) should always be handled by
82 the application.
83
86 yascreen *s;
87 int winch=0;
88 void sigwinch(int sign) {
90 winch=1;
91 }
92 s=yascreen_init(0,0); // let yascreen get term size
94 yascreen_term_set(s,YAS_NOBUFF|YAS_NOSIGN|YAS_NOECHO);
95 signal(SIGWINCH,sigwinch);
96 for (;;) { // main loop
98 if (winch) {
99 winch=0;
100 if (yascreen_resize(s,0,0))
101 // handle a fatal error - no memory
102 // get the new sizes and redraw
103 newsizex=yascreen_sx(s);
104 newsizey=yascreen_sy(s);
105 }
106 …
108 // option 1
109 // input is handled in external event loop and fed to yascreen via yascreen_feed
111 if (FD_ISSET(STDIN_FILENO,&r)&&sizeof c==read(STDIN_FILENO,&c,sizeof c))
112 yascreen_feed(s,c); // pump state machine with bytestream
113 // keys are processed only when available without delay/blocking
115 while ((ch=yascreen_getch_nowait(s))!=-1) {
116 // handle processed keys
117 }
118 …
120 // option 2
121 // input is handled by yascreen and key or -1 is returned not longer than TIMEOUT ms
123 // note: if screen update is based on this, keypresses will force it
124 while ((ch=yascreen_getch_to(s,TIMEOUT))!=-1) {
125 // handle processed keys
126 }
127 …
129 // option 3
130 // input is handled by yascreen and the following call will block until a key is pressed
132 if ((ch=yascreen_getch(s))!=-1) {
133 // handle processed key
134 }
135 }
136 For sockets input is handled like option 1 in the example above and
140 yascreen needs to be provided with a callback for output.
141 In multiprocess mode daemons where stdin/stdout are redirected to a
144 socket the same model from the example above can be used. Obviously
145 SIGWINCH will work only for terminals and for sockets the screen size
146 can get to be known either via telnet or ASNI sequences.
147
150 quences processing
151 yascreen *s;
152 s=yascreen_init(80,25); // there is no guarantee that screen size detection is supported on the remote end
154 yascreen_setout(s,output_cb); // set callback for output
155 yascreen_set_telnet(s,1); // enable processing of telnet sequences
156 yascreen_init_telnet(s); // try to negotiate telnet options (regardless if telnet processing is enabled)
157 yascreen_reqsize(s); // request initial screen size
158 for (;;) { // main loop
159 …
160 yascreen_feed(s,c); // feed input from the socket to yascreen
161 // keys are processed only when available without delay/blocking
163 while ((ch=yascreen_getch_nowait(s))!=-1) {
164 // handle processed keys
165 // screen size change is reported as a special keypress code:
167 if (ch==YAS_TELNET_SIZE||ch==YAS_SCREEN_SIZE) // screen size change reported via telnet or ANSI sequence
168 // redraw
169 }
170 }
171
178 Internally style is kept into bitfields in a single integer variable -
179 that includes foreground/background colors, style modifiers (bold,
180 italic, underline, inverse and blink.
181 Style codes
184 ┌────────────┬───────────┐
185 │Name │ Function │
186 ├────────────┼───────────┤
187 │YAS_ITALIC │ italic │
188 ├────────────┼───────────┤
189 │YAS_UNDERL │ underline │
190 ├────────────┼───────────┤
191 │YAS_STRIKE │ stikeout │
192 ├────────────┼───────────┤
193 │YAS_INVERSE │ inverse │
194 ├────────────┼───────────┤
195 │YAS_BOLD │ bold │
196 ├────────────┼───────────┤
197 │YAS_BLINK │ blink │
198 └────────────┴───────────┘
199 Color codes
201 ┌───────────────┬─────────────────────────────┐
202 │Name │ Color │
203 ├───────────────┼─────────────────────────────┤
204 │YAS_BLACK │ black │
205 ├───────────────┼─────────────────────────────┤
206 │YAS_RED │ red │
207 ├───────────────┼─────────────────────────────┤
208 │YAS_GREEN │ green │
209 ├───────────────┼─────────────────────────────┤
210 │YAS_YELLOW │ yellow │
211 ├───────────────┼─────────────────────────────┤
212 │YAS_BLUE │ blue │
213 ├───────────────┼─────────────────────────────┤
214 │YAS_MAGENTA │ magenta │
215 ├───────────────┼─────────────────────────────┤
216 │YAS_CYAN │ cyan │
217 ├───────────────┼─────────────────────────────┤
218 │YAS_WHITE │ white │
219 ├───────────────┼─────────────────────────────┤
220 │YAS_FGCOLORDEF │ default terminal foreground │
221 ├───────────────┼─────────────────────────────┤
222 │YAS_BGCOLORDEF │ default terminal background │
223 └───────────────┴─────────────────────────────┘
224 Helper macros
226 ┌────────────────────┬────────────────────────────┐
227 │Name │ Description │
228 ├────────────────────┼────────────────────────────┤
229 │YAS_FG(attribute) │ extract foreground color │
230 ├────────────────────┼────────────────────────────┤
231 │YAS_BG(attribute) │ extract background color │
232 ├────────────────────┼────────────────────────────┤
233 │YAS_FGCOLOR(color) │ shift simple color value │
234 │ │ into foreground color │
235 ├────────────────────┼────────────────────────────┤
236 │YAS_BGCOLOR(color) │ shift simple color value │
237 │ │ into background color │
238 ├────────────────────┼────────────────────────────┤
239 │YAS_FGXCOLOR(color) │ shift 256 palette color │
240 │ │ value into foreground │
241 │ │ color │
242 ├────────────────────┼────────────────────────────┤
243 │YAS_BGXCOLOR(color) │ shift 256 palette color │
244 │ │ value into background │
245 │ │ color │
246 └────────────────────┴────────────────────────────┘
247 All of the above can be or'ed into attribute, provided that the bits
249 for foreground/background color are all zeroes.
250 Key codes
253 • Special, generated internally
254 Previous versions of the library used -1 and 0x100+ for these codes. In
258 order to achieve unicode wide character compatibility and simpler API,
259 the reserved Unicode range 0xf0000-0xffffd is used for the special
260 codes both in narrow and wide character input modes.
261 There is a macro YAS_IS_CC(code) that will evaluate to non-zero for the
264 special codes and to zero for normal characters. Note that all ASCII
265 control characters in the range 0x00-0x7f are treated as normal ones.
266 ┌────────────────┬─────────┬─────────────────────┐
269 │Name │ Value │ Description │
270 ├────────────────┼─────────┼─────────────────────┤
271 │YAS_K_NONE │ 0xf0000 │ no key is avail‐ │
272 │ │ │ able; in time lim‐ │
273 │ │ │ ited mode means │
274 │ │ │ that the time limit │
275 │ │ │ expired │
276 ├────────────────┼─────────┼─────────────────────┤
277 │YAS_SCREEN_SIZE │ 0xf0701 │ notification for │
278 │ │ │ screen size change │
279 │ │ │ (may come because │
280 │ │ │ of telnet or ANSI │
281 │ │ │ sequence) │
282 ├────────────────┼─────────┼─────────────────────┤
283 │YAS_TELNET_SIZE │ 0xf0702 │ notification for │
284 │ │ │ screen size change; │
285 │ │ │ duplicates the │
286 │ │ │ above, may be used │
287 │ │ │ to differentiate │
288 │ │ │ how screen size │
289 │ │ │ change event was │
290 │ │ │ generated │
291 └────────────────┴─────────┴─────────────────────┘
292 • Normal keys
294 ┌─────────────┬───────┬───────────────────────────────┐
298 │Name │ Value │ Description │
299 ├─────────────┼───────┼───────────────────────────────┤
300 │YAS_K_NUL │ 0x00 │ Nul; on some terminals Ctrl-2 │
301 ├─────────────┼───────┼───────────────────────────────┤
302 │YAS_K_C_A │ 0x01 │ Ctrl-A │
303 ├─────────────┼───────┼───────────────────────────────┤
304 │YAS_K_C_B │ 0x02 │ Ctrl-B │
305 ├─────────────┼───────┼───────────────────────────────┤
306 │YAS_K_C_C │ 0x03 │ Ctrl-C │
307 ├─────────────┼───────┼───────────────────────────────┤
308 │YAS_K_C_D │ 0x04 │ Ctrl-D │
309 ├─────────────┼───────┼───────────────────────────────┤
310 │YAS_K_C_E │ 0x05 │ Ctrl-E │
311 ├─────────────┼───────┼───────────────────────────────┤
312 │YAS_K_C_F │ 0x06 │ Ctrl-F │
313 ├─────────────┼───────┼───────────────────────────────┤
314 │YAS_K_C_G │ 0x07 │ Ctrl-G │
315 ├─────────────┼───────┼───────────────────────────────┤
316 │YAS_K_C_H │ 0x08 │ Ctrl-H; depends on terminal │
317 │ │ │ see YAS-K-BSP and YAS-K-C-8 │
318 ├─────────────┼───────┼───────────────────────────────┤
319 │YAS_K_C_I │ 0x09 │ Ctrl-I │
320 ├─────────────┼───────┼───────────────────────────────┤
321 │YAS_K_TAB │ 0x09 │ Tab │
322 ├─────────────┼───────┼───────────────────────────────┤
323 │YAS_K_C_J │ 0x0a │ Ctrl-J │
324 ├─────────────┼───────┼───────────────────────────────┤
325 │YAS_K_C_K │ 0x0b │ Ctrl-K │
326 ├─────────────┼───────┼───────────────────────────────┤
327 │YAS_K_C_L │ 0x0c │ Ctrl-L │
328 ├─────────────┼───────┼───────────────────────────────┤
329 │YAS_K_C_M │ 0x0d │ Enter, Return, Ctrl-M; see │
330 │ │ │ below │
331 ├─────────────┼───────┼───────────────────────────────┤
332 │YAS_K_RET │ 0x0d │ Enter, Return, Ctrl-M; see │
333 │ │ │ above │
334 ├─────────────┼───────┼───────────────────────────────┤
335 │YAS_K_C_N │ 0x0e │ Ctrl-N │
336 ├─────────────┼───────┼───────────────────────────────┤
337 │YAS_K_C_O │ 0x0f │ Ctrl-O │
338 ├─────────────┼───────┼───────────────────────────────┤
339 │YAS_K_C_P │ 0x10 │ Ctrl-O │
340 ├─────────────┼───────┼───────────────────────────────┤
341 │YAS_K_C_Q │ 0x11 │ Ctrl-Q │
342 ├─────────────┼───────┼───────────────────────────────┤
343 │YAS_K_C_R │ 0x12 │ Ctrl-R │
344 ├─────────────┼───────┼───────────────────────────────┤
345 │YAS_K_C_S │ 0x13 │ Ctrl-S │
346 ├─────────────┼───────┼───────────────────────────────┤
347 │YAS_K_C_T │ 0x14 │ Ctrl-T │
348 ├─────────────┼───────┼───────────────────────────────┤
349 │YAS_K_C_U │ 0x15 │ Ctrl-U │
350 ├─────────────┼───────┼───────────────────────────────┤
351 │YAS_K_C_V │ 0x16 │ Ctrl-V │
352 ├─────────────┼───────┼───────────────────────────────┤
353 │YAS_K_C_W │ 0x17 │ Ctrl-W │
354 ├─────────────┼───────┼───────────────────────────────┤
355 │YAS_K_C_X │ 0x18 │ Ctrl-X │
356 ├─────────────┼───────┼───────────────────────────────┤
357 │YAS_K_C_Y │ 0x19 │ Ctrl-Y │
358 ├─────────────┼───────┼───────────────────────────────┤
359 │YAS_K_C_Z │ 0x1a │ Ctrl-Z │
360 ├─────────────┼───────┼───────────────────────────────┤
361 │YAS_K_ESC │ 0x1b │ Esc, Ctrl-3; see below; All │
362 │ │ │ ANSI sequences start with │
363 │ │ │ Esc, this is returned after a │
364 │ │ │ timeout or double Esc │
365 ├─────────────┼───────┼───────────────────────────────┤
366 │YAS_K_C_3 │ 0x1b │ Esc, Ctrl-3; see above; All │
367 │ │ │ ANSI sequences start with │
368 │ │ │ Esc, this is returned after a │
369 │ │ │ timeout or double Esc │
370 ├─────────────┼───────┼───────────────────────────────┤
371 │YAS_K_C_4 │ 0x1c │ Ctrl-4 │
372 ├─────────────┼───────┼───────────────────────────────┤
373 │YAS_K_C_5 │ 0x1d │ Ctrl-5 │
374 ├─────────────┼───────┼───────────────────────────────┤
375 │YAS_K_C_6 │ 0x1e │ Ctrl-6 │
376 ├─────────────┼───────┼───────────────────────────────┤
377 │YAS_K_C_7 │ 0x1f │ Ctrl-7 │
378 ├─────────────┼───────┼───────────────────────────────┤
379 │YAS_K_SPACE │ 0x20 │ Space │
380 ├─────────────┼───────┼───────────────────────────────┤
381 │YAS_K_EXCL │ 0x21 │ ! │
382 ├─────────────┼───────┼───────────────────────────────┤
383 │YAS_K_DQUOT │ 0x22 │ " │
384 ├─────────────┼───────┼───────────────────────────────┤
385 │YAS_K_HASH │ 0x23 │ # │
386 ├─────────────┼───────┼───────────────────────────────┤
387 │YAS_K_POUND │ 0x24 │ $ │
388 ├─────────────┼───────┼───────────────────────────────┤
389 │YAS_K_PERC │ 0x25 │ % │
390 ├─────────────┼───────┼───────────────────────────────┤
391 │YAS_K_AND │ 0x26 │ Ampersand │
392 ├─────────────┼───────┼───────────────────────────────┤
393 │YAS_K_QUOT │ 0x27 │ ' │
394 ├─────────────┼───────┼───────────────────────────────┤
395 │YAS_K_OBRA │ 0x28 │ ( │
396 ├─────────────┼───────┼───────────────────────────────┤
397 │YAS_K_CBRA │ 0x29 │ ) │
398 ├─────────────┼───────┼───────────────────────────────┤
399 │YAS_K_STAR │ 0x2a │ * │
400 ├─────────────┼───────┼───────────────────────────────┤
401 │YAS_K_PLUS │ 0x2b │ + │
402 ├─────────────┼───────┼───────────────────────────────┤
403 │YAS_K_COMMA │ 0x2c │ , │
404 ├─────────────┼───────┼───────────────────────────────┤
405 │YAS_K_MINUS │ 0x2d │ - │
406 ├─────────────┼───────┼───────────────────────────────┤
407 │YAS_K_DOT │ 0x2e │ . │
408 ├─────────────┼───────┼───────────────────────────────┤
409 │YAS_K_SLASH │ 0x2f │ / │
410 ├─────────────┼───────┼───────────────────────────────┤
411 │YAS_K_0 │ 0x30 │ 0 │
412 ├─────────────┼───────┼───────────────────────────────┤
413 │YAS_K_1 │ 0x31 │ 1 │
414 ├─────────────┼───────┼───────────────────────────────┤
415 │YAS_K_2 │ 0x32 │ 2 │
416 ├─────────────┼───────┼───────────────────────────────┤
417 │YAS_K_3 │ 0x33 │ 3 │
418 ├─────────────┼───────┼───────────────────────────────┤
419 │YAS_K_4 │ 0x34 │ 4 │
420 ├─────────────┼───────┼───────────────────────────────┤
421 │YAS_K_5 │ 0x35 │ 5 │
422 ├─────────────┼───────┼───────────────────────────────┤
423 │YAS_K_6 │ 0x36 │ 6 │
424 ├─────────────┼───────┼───────────────────────────────┤
425 │YAS_K_7 │ 0x37 │ 7 │
426 ├─────────────┼───────┼───────────────────────────────┤
427 │YAS_K_8 │ 0x38 │ 8 │
428 ├─────────────┼───────┼───────────────────────────────┤
429 │YAS_K_9 │ 0x39 │ 9 │
430 ├─────────────┼───────┼───────────────────────────────┤
431 │YAS_K_COLON │ 0x3a │ : │
432 ├─────────────┼───────┼───────────────────────────────┤
433 │YAS_K_SEMI │ 0x3b │ ; │
434 ├─────────────┼───────┼───────────────────────────────┤
435 │YAS_K_LT │ 0x3c │ < │
436 ├─────────────┼───────┼───────────────────────────────┤
437 │YAS_K_EQ │ 0x3d │ Equal │
438 ├─────────────┼───────┼───────────────────────────────┤
439 │YAS_K_GT │ 0x3e │ > │
440 ├─────────────┼───────┼───────────────────────────────┤
441 │YAS_K_QUEST │ 0x3f │ ? │
442 ├─────────────┼───────┼───────────────────────────────┤
443 │YAS_K_AT │ 0x40 │ @ │
444 ├─────────────┼───────┼───────────────────────────────┤
445 │YAS_K_A │ 0x41 │ A │
446 ├─────────────┼───────┼───────────────────────────────┤
447 │YAS_K_B │ 0x42 │ B │
448 ├─────────────┼───────┼───────────────────────────────┤
449 │YAS_K_C │ 0x43 │ C │
450 ├─────────────┼───────┼───────────────────────────────┤
451 │YAS_K_D │ 0x44 │ D │
452 ├─────────────┼───────┼───────────────────────────────┤
453 │YAS_K_E │ 0x45 │ E │
454 ├─────────────┼───────┼───────────────────────────────┤
455 │YAS_K_F │ 0x46 │ F │
456 ├─────────────┼───────┼───────────────────────────────┤
457 │YAS_K_G │ 0x47 │ G │
458 ├─────────────┼───────┼───────────────────────────────┤
459 │YAS_K_H │ 0x48 │ H │
460 ├─────────────┼───────┼───────────────────────────────┤
461 │YAS_K_I │ 0x49 │ I │
462 ├─────────────┼───────┼───────────────────────────────┤
463 │YAS_K_J │ 0x4a │ J │
464 ├─────────────┼───────┼───────────────────────────────┤
465 │YAS_K_K │ 0x4b │ K │
466 ├─────────────┼───────┼───────────────────────────────┤
467 │YAS_K_L │ 0x4c │ L │
468 ├─────────────┼───────┼───────────────────────────────┤
469 │YAS_K_M │ 0x4d │ M │
470 ├─────────────┼───────┼───────────────────────────────┤
471 │YAS_K_N │ 0x4e │ N │
472 ├─────────────┼───────┼───────────────────────────────┤
473 │YAS_K_O │ 0x4f │ O │
474 ├─────────────┼───────┼───────────────────────────────┤
475 │YAS_K_P │ 0x50 │ P │
476 ├─────────────┼───────┼───────────────────────────────┤
477 │YAS_K_Q │ 0x51 │ Q │
478 ├─────────────┼───────┼───────────────────────────────┤
479 │YAS_K_R │ 0x52 │ R │
480 ├─────────────┼───────┼───────────────────────────────┤
481 │YAS_K_S │ 0x53 │ S │
482 ├─────────────┼───────┼───────────────────────────────┤
483 │YAS_K_T │ 0x54 │ T │
484 ├─────────────┼───────┼───────────────────────────────┤
485 │YAS_K_U │ 0x55 │ U │
486 ├─────────────┼───────┼───────────────────────────────┤
487 │YAS_K_V │ 0x56 │ V │
488 ├─────────────┼───────┼───────────────────────────────┤
489 │YAS_K_W │ 0x57 │ W │
490 ├─────────────┼───────┼───────────────────────────────┤
491 │YAS_K_X │ 0x58 │ X │
492 ├─────────────┼───────┼───────────────────────────────┤
493 │YAS_K_Y │ 0x59 │ Y │
494 ├─────────────┼───────┼───────────────────────────────┤
495 │YAS_K_Z │ 0x5a │ Z │
496 ├─────────────┼───────┼───────────────────────────────┤
497 │YAS_K_OSQ │ 0x5b │ OpenSquareBracket │
498 ├─────────────┼───────┼───────────────────────────────┤
499 │YAS_K_BSLASH │ 0x5c │ Backslash │
500 ├─────────────┼───────┼───────────────────────────────┤
501 │YAS_K_CSQ │ 0x5d │ CloseSquareBracket │
502 ├─────────────┼───────┼───────────────────────────────┤
503 │YAS_K_CARRET │ 0x5e │ ^ │
504 ├─────────────┼───────┼───────────────────────────────┤
505 │YAS_K_USCORE │ 0x5f │ Underscore │
506 ├─────────────┼───────┼───────────────────────────────┤
507 │YAS_K_BTICK │ 0x60 │ Backtick │
508 ├─────────────┼───────┼───────────────────────────────┤
509 │YAS_K_a │ 0x61 │ a │
510 ├─────────────┼───────┼───────────────────────────────┤
511 │YAS_K_b │ 0x62 │ b │
512 ├─────────────┼───────┼───────────────────────────────┤
513 │YAS_K_c │ 0x63 │ c │
514 ├─────────────┼───────┼───────────────────────────────┤
515 │YAS_K_d │ 0x64 │ d │
516 ├─────────────┼───────┼───────────────────────────────┤
517 │YAS_K_e │ 0x65 │ e │
518 ├─────────────┼───────┼───────────────────────────────┤
519 │YAS_K_f │ 0x66 │ f │
520 ├─────────────┼───────┼───────────────────────────────┤
521 │YAS_K_g │ 0x67 │ g │
522 ├─────────────┼───────┼───────────────────────────────┤
523 │YAS_K_h │ 0x68 │ h │
524 ├─────────────┼───────┼───────────────────────────────┤
525 │YAS_K_i │ 0x69 │ i │
526 ├─────────────┼───────┼───────────────────────────────┤
527 │YAS_K_j │ 0x6a │ j │
528 ├─────────────┼───────┼───────────────────────────────┤
529 │YAS_K_k │ 0x6b │ k │
530 ├─────────────┼───────┼───────────────────────────────┤
531 │YAS_K_l │ 0x6c │ l │
532 ├─────────────┼───────┼───────────────────────────────┤
533 │YAS_K_m │ 0x6d │ m │
534 ├─────────────┼───────┼───────────────────────────────┤
535 │YAS_K_n │ 0x6e │ n │
536 ├─────────────┼───────┼───────────────────────────────┤
537 │YAS_K_o │ 0x6f │ o │
538 ├─────────────┼───────┼───────────────────────────────┤
539 │YAS_K_p │ 0x70 │ p │
540 ├─────────────┼───────┼───────────────────────────────┤
541 │YAS_K_q │ 0x71 │ q │
542 ├─────────────┼───────┼───────────────────────────────┤
543 │YAS_K_r │ 0x72 │ r │
544 ├─────────────┼───────┼───────────────────────────────┤
545 │YAS_K_s │ 0x73 │ s │
546 ├─────────────┼───────┼───────────────────────────────┤
547 │YAS_K_t │ 0x74 │ t │
548 ├─────────────┼───────┼───────────────────────────────┤
549 │YAS_K_u │ 0x75 │ u │
550 ├─────────────┼───────┼───────────────────────────────┤
551 │YAS_K_v │ 0x76 │ v │
552 ├─────────────┼───────┼───────────────────────────────┤
553 │YAS_K_w │ 0x77 │ w │
554 ├─────────────┼───────┼───────────────────────────────┤
555 │YAS_K_x │ 0x78 │ x │
556 ├─────────────┼───────┼───────────────────────────────┤
557 │YAS_K_y │ 0x79 │ y │
558 ├─────────────┼───────┼───────────────────────────────┤
559 │YAS_K_z │ 0x7a │ z │
560 ├─────────────┼───────┼───────────────────────────────┤
561 │YAS_K_OCUR │ 0x7b │ { │
562 ├─────────────┼───────┼───────────────────────────────┤
563 │YAS_K_PIPE │ 0x7c │ Pipe │
564 ├─────────────┼───────┼───────────────────────────────┤
565 │YAS_K_CCUR │ 0x7d │ } │
566 ├─────────────┼───────┼───────────────────────────────┤
567 │YAS_K_TLD │ 0x7e │ Tilde │
568 ├─────────────┼───────┼───────────────────────────────┤
569 │YAS_K_C_8 │ 0x7f │ Backspace; see below; depends │
570 │ │ │ on terminal see YAS-K-C-H │
571 ├─────────────┼───────┼───────────────────────────────┤
572 │YAS_K_BSP │ 0x7f │ Backspace; see below; depends │
573 │ │ │ on terminal see YAS-K-C-H │
574 └─────────────┴───────┴───────────────────────────────┘
575 • Extended keys, parsed from ANSI sequences
577 ┌──────────────┬─────────┬─────────────┐
581 │Name │ Value │ Description │
582 ├──────────────┼─────────┼─────────────┤
583 │YAS_K_F1 │ 0xf0001 │ F1 │
584 ├──────────────┼─────────┼─────────────┤
585 │YAS_K_F2 │ 0xf0002 │ F2 │
586 ├──────────────┼─────────┼─────────────┤
587 │YAS_K_F3 │ 0xf0003 │ F3 │
588 ├──────────────┼─────────┼─────────────┤
589 │YAS_K_F4 │ 0xf0004 │ F4 │
590 ├──────────────┼─────────┼─────────────┤
591 │YAS_K_F5 │ 0xf0005 │ F5 │
592 ├──────────────┼─────────┼─────────────┤
593 │YAS_K_F6 │ 0xf0006 │ F6 │
594 ├──────────────┼─────────┼─────────────┤
595 │YAS_K_F7 │ 0xf0007 │ F7 │
596 ├──────────────┼─────────┼─────────────┤
597 │YAS_K_F8 │ 0xf0008 │ F8 │
598 ├──────────────┼─────────┼─────────────┤
599 │YAS_K_F9 │ 0xf0009 │ F9 │
600 ├──────────────┼─────────┼─────────────┤
601 │YAS_K_F10 │ 0xf000a │ F10 │
602 ├──────────────┼─────────┼─────────────┤
603 │YAS_K_F11 │ 0xf000b │ F11 │
604 ├──────────────┼─────────┼─────────────┤
605 │YAS_K_F12 │ 0xf000c │ F12 │
606 ├──────────────┼─────────┼─────────────┤
607 │YAS_K_S_F1 │ 0xf000d │ Shift-F1 │
608 ├──────────────┼─────────┼─────────────┤
609 │YAS_K_S_F2 │ 0xf000e │ Shift-F2 │
610 ├──────────────┼─────────┼─────────────┤
611 │YAS_K_S_F3 │ 0xf000f │ Shift-F3 │
612 ├──────────────┼─────────┼─────────────┤
613 │YAS_K_S_F4 │ 0xf0010 │ Shift-F4 │
614 ├──────────────┼─────────┼─────────────┤
615 │YAS_K_S_F5 │ 0xf0011 │ Shift-F5 │
616 ├──────────────┼─────────┼─────────────┤
617 │YAS_K_S_F6 │ 0xf0012 │ Shift-F6 │
618 ├──────────────┼─────────┼─────────────┤
619 │YAS_K_S_F7 │ 0xf0013 │ Shift-F7 │
620 ├──────────────┼─────────┼─────────────┤
621 │YAS_K_S_F8 │ 0xf0014 │ Shift-F8 │
622 ├──────────────┼─────────┼─────────────┤
623 │YAS_K_S_F9 │ 0xf0015 │ Shift-F9 │
624 ├──────────────┼─────────┼─────────────┤
625 │YAS_K_S_F10 │ 0xf0016 │ Shift-F10 │
626 ├──────────────┼─────────┼─────────────┤
627 │YAS_K_S_F11 │ 0xf0017 │ Shift-F11 │
628 ├──────────────┼─────────┼─────────────┤
629 │YAS_K_S_F12 │ 0xf0018 │ Shift-F12 │
630 ├──────────────┼─────────┼─────────────┤
631 │YAS_K_C_F1 │ 0xf0019 │ Ctrl-F1 │
632 ├──────────────┼─────────┼─────────────┤
633 │YAS_K_C_F2 │ 0xf001a │ Ctrl-F2 │
634 ├──────────────┼─────────┼─────────────┤
635 │YAS_K_C_F3 │ 0xf001b │ Ctrl-F3 │
636 ├──────────────┼─────────┼─────────────┤
637 │YAS_K_C_F4 │ 0xf001c │ Ctrl-F4 │
638 ├──────────────┼─────────┼─────────────┤
639 │YAS_K_C_F5 │ 0xf001d │ Ctrl-F5 │
640 ├──────────────┼─────────┼─────────────┤
641 │YAS_K_C_F6 │ 0xf001e │ Ctrl-F6 │
642 ├──────────────┼─────────┼─────────────┤
643 │YAS_K_C_F7 │ 0xf001f │ Ctrl-F7 │
644 ├──────────────┼─────────┼─────────────┤
645 │YAS_K_C_F8 │ 0xf0020 │ Ctrl-F8 │
646 ├──────────────┼─────────┼─────────────┤
647 │YAS_K_C_F9 │ 0xf0021 │ Ctrl-F9 │
648 ├──────────────┼─────────┼─────────────┤
649 │YAS_K_C_F10 │ 0xf0022 │ Ctrl-F10 │
650 ├──────────────┼─────────┼─────────────┤
651 │YAS_K_C_F11 │ 0xf0023 │ Ctrl-F11 │
652 ├──────────────┼─────────┼─────────────┤
653 │YAS_K_C_F12 │ 0xf0024 │ Ctrl-F12 │
654 ├──────────────┼─────────┼─────────────┤
655 │YAS_K_A_F1 │ 0xf0025 │ Alt-F1 │
656 ├──────────────┼─────────┼─────────────┤
657 │YAS_K_A_F2 │ 0xf0026 │ Alt-F2 │
658 ├──────────────┼─────────┼─────────────┤
659 │YAS_K_A_F3 │ 0xf0027 │ Alt-F3 │
660 ├──────────────┼─────────┼─────────────┤
661 │YAS_K_A_F4 │ 0xf0028 │ Alt-F4 │
662 ├──────────────┼─────────┼─────────────┤
663 │YAS_K_A_F5 │ 0xf0029 │ Alt-F5 │
664 ├──────────────┼─────────┼─────────────┤
665 │YAS_K_A_F6 │ 0xf002a │ Alt-F6 │
666 ├──────────────┼─────────┼─────────────┤
667 │YAS_K_A_F7 │ 0xf002b │ Alt-F7 │
668 ├──────────────┼─────────┼─────────────┤
669 │YAS_K_A_F8 │ 0xf002c │ Alt-F8 │
670 ├──────────────┼─────────┼─────────────┤
671 │YAS_K_A_F9 │ 0xf002d │ Alt-F9 │
672 ├──────────────┼─────────┼─────────────┤
673 │YAS_K_A_F10 │ 0xf002e │ Alt-F10 │
674 ├──────────────┼─────────┼─────────────┤
675 │YAS_K_A_F11 │ 0xf002f │ Alt-F11 │
676 ├──────────────┼─────────┼─────────────┤
677 │YAS_K_A_F12 │ 0xf0030 │ Alt-F12 │
678 ├──────────────┼─────────┼─────────────┤
679 │YAS_K_LEFT │ 0xf0031 │ Left │
680 ├──────────────┼─────────┼─────────────┤
681 │YAS_K_UP │ 0xf0032 │ Up │
682 ├──────────────┼─────────┼─────────────┤
683 │YAS_K_DOWN │ 0xf0033 │ Down │
684 ├──────────────┼─────────┼─────────────┤
685 │YAS_K_RIGHT │ 0xf0034 │ Right │
686 ├──────────────┼─────────┼─────────────┤
687 │YAS_K_HOME │ 0xf0035 │ Home │
688 ├──────────────┼─────────┼─────────────┤
689 │YAS_K_END │ 0xf0036 │ End │
690 ├──────────────┼─────────┼─────────────┤
691 │YAS_K_PGUP │ 0xf0037 │ PageUp │
692 ├──────────────┼─────────┼─────────────┤
693 │YAS_K_PGDN │ 0xf0038 │ PageDown │
694 ├──────────────┼─────────┼─────────────┤
695 │YAS_K_INS │ 0xf0039 │ Insert │
696 ├──────────────┼─────────┼─────────────┤
697 │YAS_K_DEL │ 0xf003a │ Delete │
698 ├──────────────┼─────────┼─────────────┤
699 │YAS_K_C_LEFT │ 0xf003b │ Ctrl-Left │
700 ├──────────────┼─────────┼─────────────┤
701 │YAS_K_C_UP │ 0xf003c │ Ctrl-Up │
702 ├──────────────┼─────────┼─────────────┤
703 │YAS_K_C_DOWN │ 0xf003d │ Ctrl-Down │
704 ├──────────────┼─────────┼─────────────┤
705 │YAS_K_C_RIGHT │ 0xf003e │ Ctrl-Right │
706 ├──────────────┼─────────┼─────────────┤
707 │YAS_K_S_LEFT │ 0xf003f │ Shift-Left │
708 ├──────────────┼─────────┼─────────────┤
709 │YAS_K_S_UP │ 0xf0040 │ Shift-Up │
710 ├──────────────┼─────────┼─────────────┤
711 │YAS_K_S_DOWN │ 0xf0041 │ Shift-Down │
712 ├──────────────┼─────────┼─────────────┤
713 │YAS_K_S_RIGHT │ 0xf0042 │ Shift-Right │
714 └──────────────┴─────────┴─────────────┘
715 • Alt-<letter>
717 These codes are generated by a helper macro - YAS_K_ALT(keycode).
721 ┌───────────────┬───────────────┐
724 │Name │ Description │
725 ├───────────────┼───────────────┤
726 │YAS_K_A_BT │ Alt-Backtick │
727 ├───────────────┼───────────────┤
728 │YAS_K_A_1 │ Alt-1 │
729 ├───────────────┼───────────────┤
730 │YAS_K_A_2 │ Alt-2 │
731 ├───────────────┼───────────────┤
732 │YAS_K_A_3 │ Alt-3 │
733 ├───────────────┼───────────────┤
734 │YAS_K_A_4 │ Alt-4 │
735 ├───────────────┼───────────────┤
736 │YAS_K_A_5 │ Alt-5 │
737 ├───────────────┼───────────────┤
738 │YAS_K_A_6 │ Alt-6 │
739 ├───────────────┼───────────────┤
740 │YAS_K_A_7 │ Alt-7 │
741 ├───────────────┼───────────────┤
742 │YAS_K_A_8 │ Alt-8 │
743 ├───────────────┼───────────────┤
744 │YAS_K_A_9 │ Alt-9 │
745 ├───────────────┼───────────────┤
746 │YAS_K_A_0 │ Alt-0 │
747 ├───────────────┼───────────────┤
748 │YAS_K_A_MINUS │ Alt-Minus │
749 ├───────────────┼───────────────┤
750 │YAS_K_A_EQ │ Alt-= │
751 ├───────────────┼───────────────┤
752 │YAS_K_A_BSP │ Alt-Backspace │
753 ├───────────────┼───────────────┤
754 │YAS_K_A_TLD │ Alt-Tilde │
755 ├───────────────┼───────────────┤
756 │YAS_K_A_EXCL │ Alt-! │
757 ├───────────────┼───────────────┤
758 │YAS_K_A_AT │ Alt-@ │
759 ├───────────────┼───────────────┤
760 │YAS_K_A_HASH │ Alt-# │
761 ├───────────────┼───────────────┤
762 │YAS_K_A_POUND │ Alt-$ │
763 ├───────────────┼───────────────┤
764 │YAS_K_A_PERC │ Alt-% │
765 ├───────────────┼───────────────┤
766 │YAS_K_A_CARRET │ Alt-^ │
767 ├───────────────┼───────────────┤
768 │YAS_K_A_AND │ Alt-Ampersand │
769 ├───────────────┼───────────────┤
770 │YAS_K_A_STAR │ Alt-Star │
771 ├───────────────┼───────────────┤
772 │YAS_K_A_OBRA │ Alt-( │
773 ├───────────────┼───────────────┤
774 │YAS_K_A_CBRA │ Alt-) │
775 ├───────────────┼───────────────┤
776 │YAS_K_A_UND │ Alt-_ │
777 ├───────────────┼───────────────┤
778 │YAS_K_A_PLUS │ Alt-+ │
779 ├───────────────┼───────────────┤
780 │YAS_K_A_a │ Alt-a │
781 ├───────────────┼───────────────┤
782 │YAS_K_A_b │ Alt-b │
783 ├───────────────┼───────────────┤
784 │YAS_K_A_c │ Alt-c │
785 ├───────────────┼───────────────┤
786 │YAS_K_A_d │ Alt-d │
787 ├───────────────┼───────────────┤
788 │YAS_K_A_e │ Alt-e │
789 ├───────────────┼───────────────┤
790 │YAS_K_A_f │ Alt-f │
791 ├───────────────┼───────────────┤
792 │YAS_K_A_g │ Alt-g │
793 ├───────────────┼───────────────┤
794 │YAS_K_A_h │ Alt-h │
795 ├───────────────┼───────────────┤
796 │YAS_K_A_i │ Alt-i │
797 ├───────────────┼───────────────┤
798 │YAS_K_A_j │ Alt-j │
799 ├───────────────┼───────────────┤
800 │YAS_K_A_k │ Alt-k │
801 ├───────────────┼───────────────┤
802 │YAS_K_A_l │ Alt-l │
803 ├───────────────┼───────────────┤
804 │YAS_K_A_m │ Alt-m │
805 ├───────────────┼───────────────┤
806 │YAS_K_A_n │ Alt-n │
807 ├───────────────┼───────────────┤
808 │YAS_K_A_o │ Alt-o │
809 ├───────────────┼───────────────┤
810 │YAS_K_A_p │ Alt-p │
811 ├───────────────┼───────────────┤
812 │YAS_K_A_q │ Alt-q │
813 ├───────────────┼───────────────┤
814 │YAS_K_A_r │ Alt-r │
815 ├───────────────┼───────────────┤
816 │YAS_K_A_s │ Alt-s │
817 ├───────────────┼───────────────┤
818 │YAS_K_A_t │ Alt-t │
819 ├───────────────┼───────────────┤
820 │YAS_K_A_u │ Alt-u │
821 ├───────────────┼───────────────┤
822 │YAS_K_A_v │ Alt-v │
823 ├───────────────┼───────────────┤
824 │YAS_K_A_w │ Alt-w │
825 ├───────────────┼───────────────┤
826 │YAS_K_A_x │ Alt-x │
827 ├───────────────┼───────────────┤
828 │YAS_K_A_y │ Alt-y │
829 ├───────────────┼───────────────┤
830 │YAS_K_A_z │ Alt-z │
831 └───────────────┴───────────────┘
832
834 All functions in the API work with a pointer to an opaque yascreen
835 structure.
836 The structure is allocated internally in the library by yascreen_init
839 and it is the job of the user program to keep track of it.
840 The library is thread safe, as long as each struct yascreen object is
843 accessed by a single thread.
844 yascreen_init
847 inline yascreen *yascreen_init(int sx,int sy);
848 allocate and initialize screen data
852 output defaults to stdout
855 in case output is a terminal and initial size is (0,0), the screen size
858 is autodetected
859 in case of error, returns NULL
862 yascreen_ver
865 inline const char *yascreen_ver(void);
866 returns a string with the library version
870 yascreen_setout
873 inline int yascreen_setout(yascreen *s,ssize_t (*out)(yascreen *s,const void *data,size_t len));
874 set callback that handles output
878 if out=NULL, the output goes to stdout
881 the callback may implement internal buffering, a flush is signalled by
884 calling out with len=0
885 yascreen_set_unicode
888 inline void yascreen_set_unicode(yascreen *s,int on);
889 enable (on is non-zero) or disable (on=0) unicode input processing
893 by default unicode mode is on
896 changing the unicode input processing will flush all pending input
899 yascreen_set_telnet
902 inline void yascreen_set_telnet(yascreen *s,int on);
903 enable (on is non-zero) or disable (on=0) telnet sequence processing
907 by default telnet mode is off
910 yascreen_init_telnet
913 inline void yascreen_init_telnet(yascreen *s);
914 depending on telnet sequence processing, sends a set of telnet initial‐
918 ization sequences
919 yascreen_resize
922 inline int yascreen_resize(yascreen *s,int sx,int sy);
923 resize screen
927 should redraw afterwards
930 since allocation is involved, this may fail and return -1
933 yascreen_free
936 inline void yascreen_free(yascreen *s);
937 finish the lifecycle of struct yascreen - all internally allocated mem‐
941 ory is freed
942 yascreen_term_save
945 inline void yascreen_term_save(yascreen *s);
946 save current terminal state on top of state stack
950 yascreen_term_restore
953 inline void yascreen_term_restore(yascreen *s);
954 restore previously saved terminal state from top of state stack
958 yascreen_term_push
961 inline void yascreen_term_push(yascreen *s);
962 push current terminal state to state stack
966 yascreen_term_pop
969 inline void yascreen_term_pop(yascreen *s);
970 pop and restore previously saved terminal state from state stack
974 yascreen_term_set
977 inline void yascreen_term_set(yascreen *s,int mode);
978 set terminal for proper screen operation
982 mode is a bitmask, containing one of
985 ┌───────────┬───────┬───────────────────────────┐
986 │Name │ Value │ Description │
987 ├───────────┼───────┼───────────────────────────┤
988 │YAS_NOBUFF │ 1 │ turn off canonical mode │
989 │ │ │ (disable ICANON and IEX‐ │
990 │ │ │ TEN) │
991 ├───────────┼───────┼───────────────────────────┤
992 │YAS_NOSIGN │ 2 │ disable ISIG │
993 ├───────────┼───────┼───────────────────────────┤
994 │YAS_NOECHO │ 4 │ disable local echo (ECHO) │
995 ├───────────┼───────┼───────────────────────────┤
996 │YAS_ONLCR │ 8 │ ONLCR or OPOST │
997 └───────────┴───────┴───────────────────────────┘
998 yascreen_printxy
1000 inline int yascreen_printxy(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));
1001 yascreen_putsxy
1005 inline int yascreen_putsxy(yascreen *s,int x,int y,uint32_t attr,const char *str);
1006 print at position, if data exceeds buffer, then it gets truncated
1010 yascreen_printxyu
1013 inline int yascreen_printxyu(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));
1014 yascreen_putsxyu
1018 inline int yascreen_putsxyu(yascreen *s,int x,int y,uint32_t attr,const char *str);
1019 print at position, if data exceeds buffer, then it gets truncated
1023 screen is immediately updated
1026 yascreen_update
1029 inline int yascreen_update(yascreen *s);
1030 sync memory state to screen
1034 since allocation is involved, this may fail and return -1
1037 yascreen_redraw
1040 inline void yascreen_redraw(yascreen *s);
1041 set next update to be a full redraw
1045 yascreen_clear_mem
1048 inline void yascreen_clear_mem(yascreen *s,uint32_t attr);
1049 clear memory buffer
1053 all cells in the screen are set to Space, using attr for colors and
1056 style
1057 yascreen_cursor
1060 inline void yascreen_cursor(yascreen *s,int on);
1061 hide (on=0) or show (on is non-zero) cusror
1065 screen is updated immediately
1068 yascreen_cursor_xy
1071 inline void yascreen_cursor_xy(yascreen *s,int x,int y);
1072 set cursor position
1076 screen is updated immediately
1079 yascreen_altbuf
1082 inline void yascreen_altbuf(yascreen *s,int on);
1083 switch between regular and alternative buffer
1087 screen is updated immediately
1090 yascreen_clear
1093 inline void yascreen_clear(yascreen *s);
1094 clear real screen, no change to memory buffers
1098 yascreen_clearln
1101 inline void yascreen_clearln(yascreen *s);
1102 clear current line, no change to memory buffers
1106 yascreen_update_attr
1109 inline void yascreen_update_attr(yascreen *s,uint32_t oattr,uint32_t nattr);
1110 apply difference between two attrs and output the optimized ANSI se‐
1114 quence to switch from oattr to nattr
1115 if oattr=0xffffffff, the full ANSI sequence will be generated
1118 no change to memory buffers
1121 yascreen_set_attr
1124 yascreen_set_attr(s,attr)
1125 reset all attrs and set specific one (attr)
1129 yascreen_print
1132 inline int yascreen_print(yascreen *s,const char *format,...) __attribute__((format(printf,2,3)));
1133 yascreen_write
1137 inline int yascreen_write(yascreen *s,const char *str,int len);
1138 yascreen_puts
1142 inline int yascreen_puts(yascreen *s,const char *str);
1143 yascreen_clearln_s
1147 inline const char *yascreen_clearln_s(yascreen *s);
1148 print in line mode
1152 yascreen_sx
1155 inline int yascreen_sx(yascreen *s);
1156 get current x size
1160 yascreen_sy
1163 inline int yascreen_sy(yascreen *s);
1164 get current y size
1168 yascreen_x
1171 inline int yascreen_x(yascreen *s);
1172 get current x
1176 yascreen_y
1179 inline int yascreen_y(yascreen *s);
1180 get current y
1184 yascreen_esc_to
1187 inline void yascreen_esc_to(yascreen *s,int timeout);
1188 set timeout for single ESC key press
1192 yascreen_ckto
1195 inline void yascreen_ckto(yascreen *s);
1196 in case of external event loop, this call will check for single ESC key
1200 should be called regularly enough so that the above specified timeout
1203 is not extended too much
1204 if not called often enough then single ESC will be yielded after longer
1207 timeout
1208 if not called at all then single ESC will be yielded with next key
1211 press
1212 yascreen_getch_to
1215 inline int yascreen_getch_to(yascreen *s,int timeout);
1216 wait for a key, return ASCII or extended keycode, wait no more than
1220 timeout in milliseconds
1221 yascreen_getch
1224 yascreen_getch(s)
1225 get a key without timeout
1229 this macro expands to yascreen_getch_to(s,0)
1232 zero timeout=wait forever
1235 yascreen_getch_nowait
1238 yascreen_getch_nowait(s)
1239 get a key, if available, return immediately
1243 this macro expands to yascreen_getch_to(s,-1)
1246 negative timeout=do not wait
1249 yascreen_ungetch
1252 inline void yascreen_ungetch(yascreen *s,int key);
1253 put back key value in key buffer
1257 the internal key buffer is dynamically allocated, hence there is no
1260 limit of how many key codes may be put back, but in case of memory al‐
1261 location failure, the error will not be reported and the key will not
1262 be put into the buffer
1263 yascreen_pushch
1266 inline void yascreen_pushch(yascreen *s,int key);
1267 push key value at end of key buffer
1271 similar to yascreen_ungetch but the key code will be returned after all
1274 other key codes currently in the buffer
1275 the internal key buffer is dynamically allocated, hence there is no
1278 limit of how many key codes may be put back, but in case of memory al‐
1279 location failure, the error will not be reported and the key will not
1280 be put into the buffer
1281 yascreen_feed
1284 inline void yascreen_feed(yascreen *s,unsigned char c);
1285 feed key sequence state machine with byte stream
1289 this is useful to implement external event loop and read key codes by
1292 yascreen_getch_nowait until it returns -1
1293 yascreen_peekch
1296 inline int yascreen_peekch(yascreen *s);
1297 peek for key without removing it from input queue
1301 yascreen_getsize
1304 inline void yascreen_getsize(yascreen *s,int *sx,int *sy);
1305 get last reported screen size
1309 set both to 0 if there is none
1312 this will yield valid result after YAS_SCREEN_SIZE is returned as key‐
1315 press
1316 yascreen_reqsize
1319 inline void yascreen_reqsize(yascreen *s);
1320 request terminal to report its size via ANSI sequence
1324 yascreen_set_hint_i
1327 inline void yascreen_set_hint_i(yascreen *s,int hint);
1328 yascreen_get_hint_i
1332 inline int yascreen_get_hint_i(yascreen *s);
1333 yascreen_set_hint_p
1337 inline void yascreen_set_hint_p(yascreen *s,void *hint);
1338 yascreen_get_hint_p
1342 inline void *yascreen_get_hint_p(yascreen *s);
1343 get/set opaque hint values
1347 integer and pointer hints are stored separately and both can be used at
1350 the same time
1351 these are useful to link the yascreen instance to user program data
1354 for example a single output callback may output to socket or a termi‐
1357 nal, depending on the hint values
1358 yascreen_line_flush
1361 inline void yascreen_line_flush(yascreen *s,int on);
1362 enable/disable auto flush for line and direct screen oriented opera‐
1366 tions
1367 yascreen versions before 1.77 didn't use buffered output and would im‐
1370 mediately send the output to the screen
1371 disabling internal flush can help an application optimize the number of
1374 write calls at the cost of performing explicit flush after each group
1375 of operations
1376 explicit flush example:
1379 yascreen_write(s,"",0);
1382 yascreen_getwch_to
1386 inline wchar_t yascreen_getwch_to(yascreen *s,int timeout);
1387 wait for a key, return wide character or extended keycode, wait no more
1391 than timeout in milliseconds
1392 yascreen_getwch_to does not work in non-unicode mode and will always
1395 return YAS_K_NONE
1396 mixing the utf8 and wide character input modes will break on multibyte
1399 utf8 sequences and is not supported
1400 yascreen_getwch
1403 yascreen_getwch(s)
1404 get a key as wide character without timeout
1408 this macro expands to yascreen_getwch_to(s,0)
1411 zero timeout=wait forever
1414 yascreen_getwch does not work in non-unicode mode and will always re‐
1417 turn YAS_K_NONE
1418 yascreen_getwch_nowait
1421 yascreen_getwch_nowait(s)
1422 get a key as a wide character, if available, return immediately
1426 this macro expands to yascreen_getwch_to(s,-1)
1429 negative timeout=do not wait
1432 yascreen_getwch_nowait does not work in non-unicode mode and will al‐
1435 ways return YAS_K_NONE
1436 yascreen_ungetwch
1439 inline void yascreen_ungetwch(yascreen *s,wchar_t key);
1440 put back wide character key value in key buffer
1444 the internal key buffer is dynamically allocated, hence there is no
1447 limit of how many key codes may be put back, but in case of memory al‐
1448 location failure, the error will not be reported and the key will not
1449 be put into the buffer
1450 the internal key buffer contains utf8 and the wide character will be
1453 expanded to the appropriate utf8 sequence
1454 yascreen_ungetwch does not do anything in non-unicode mode
1457 yascreen_peekwch
1460 inline wchar_t yascreen_peekwch(yascreen *s);
1461 peek for key without removing it from input queue
1465 yascreen_peekwch does not work in non-unicode mode and will always re‐
1468 turn YAS_K_NONE
1469yascreen September 30, 2020 YASCREEN(3)