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 · relies only on a limited subset of ansi/xterm ESC sequences,
38 making it compatible with mostly all modern terminals
39 (inspired by linenoise ⟨https://github.com/antirez/linenoise⟩)
40 · there is no curses API and ancient terminal compatibility,
42 hence less bloat
43 · there is no autoconf - there is no need to have one
45 · clean API with opaque private data, usable from C/C++
47 · easy cross compilation setup (by setting CC, AR, STRIP and
49 RANLIB)
50 Current development is done on Linux, with additional testing on Open‐
54 BSD/FreeBSD; other platforms may need minimal fixes.
55 On *BSD a gmake is required to build.
58
61 yascreen uses an opaque data structure, allocated by the library and
62 dynamically resized when needed - yascreen_init(int sx, int sy) /
63 yascreen_resize(yascreen *s, int sx, int sy). An application may spec‐
64 ify (0,0) for both calls to let yascreen detect the size or use a fixed
65 size.
66 There are two modes of operation - telnet protocol over socket or run‐
69 ning in terminal. For sockets the event loop would typically be handled
70 outside of the library while for terminals a built-in event loop may be
71 used.
72 Modes of operation can be modified at runtime.
75 For terminal use signal handling (SIGWINCH) should always be handled by
78 the application.
79
82 yascreen *s;
83 int winch=0;
84 void sigwinch(int sign) {
86 winch=1;
87 }
88 s=yascreen_init(0,0); // let yascreen get term size
90 yascreen_term_set(s,YAS_NOBUFF|YAS_NOSIGN|YAS_NOECHO);
91 signal(SIGWINCH,sigwinch);
92 for (;;) { // main loop
94 if (winch) {
95 winch=0;
96 if (yascreen_resize(s,0,0))
97 // handle a fatal error - no memory
98 // get the new sizes and redraw
99 newsizex=yascreen_sx(s);
100 newsizey=yascreen_sy(s);
101 }
102 …
104 // option 1
105 // input is handled in external event loop and fed to yascreen via yascreen_feed
107 if (FD_ISSET(STDIN_FILENO,r)sizeof c==read(STDIN_FILENO,c,sizeof c))
108 yascreen_feed(s,c); // pump state machine with bytestream
109 // keys are processed only when available without delay/blocking
111 while ((ch=yascreen_getch_nowait(s))!=-1) {
112 // handle processed keys
113 }
114 …
116 // option 2
117 // input is handled by yascreen and key or -1 is returned not longer than TIMEOUT ms
119 // note: if screen update is based on this, keypresses will force it
120 while ((ch=yascreen_getch_to(s,TIMEOUT))!=-1) {
121 // handle processed keys
122 }
123 …
125 // option 3
126 // input is handled by yascreen and the following call will block until a key is pressed
128 if ((ch=yascreen_getch(s))!=-1) {
129 // handle processed key
130 }
131 }
132 For sockets input is handled like option 1 in the example above and
136 yascreen needs to be provided with a callback for output.
137 In multiprocess mode daemons where stdin/stdout are redirected to a
140 socket the same model from the example above can be used. Obviously
141 SIGWINCH will work only for terminals and for sockets the screen size
142 can get to be known either via telnet or ASNI sequences.
143
146 sequences processing
147 yascreen *s;
148 s=yascreen_init(80,25); // there is no guarantee that screen size detection is supported on the remote end
150 yascreen_setout(s,output_cb); // set callback for output
151 yascreen_set_telnet(s,1); // enable processing of telnet sequences
152 yascreen_init_telnet(s); // try to negotiate telnet options (regardless if telnet processing is enabled)
153 yascreen_reqsize(s); // request initial screen size
154 for (;;) { // main loop
155 …
156 yascreen_feed(s,c); // feed input from the socket to yascreen
157 // keys are processed only when available without delay/blocking
159 while ((ch=yascreen_getch_nowait(s))!=-1) {
160 // handle processed keys
161 // screen size change is reported as a special keypress code:
163 if (ch==YAS_TELNET_SIZE||ch==YAS_SCREEN_SIZE) // screen size change reported via telnet or ANSI sequence
164 // redraw
165 }
166 }
167
174 Internally style is kept into bitfields in a single integer variable -
175 that includes foreground/background colors, style modifiers (bold,
176 italic, underline, inverse and blink.
177 Style codes
180 ┌────────────┬───────────┐
183 │Name │ Function │
184 ├────────────┼───────────┤
185 │YAS_ITALIC │ italic │
186 ├────────────┼───────────┤
187 │YAS_UNDERL │ underline │
188 ├────────────┼───────────┤
189 │YAS_STRIKE │ stikeout │
190 ├────────────┼───────────┤
191 │YAS_INVERSE │ inverse │
192 ├────────────┼───────────┤
193 │YAS_BOLD │ bold │
194 ├────────────┼───────────┤
195 │YAS_BLINK │ blink │
196 └────────────┴───────────┘
197 Color codes
199 ┌───────────────┬─────────────────────────────┐
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 ┌────────────────────┬────────────────────────────┐
229 │Name │ Description │
230 ├────────────────────┼────────────────────────────┤
231 │YAS_FG(attribute) │ extract foreground color │
232 ├────────────────────┼────────────────────────────┤
233 │YAS_BG(attribute) │ extract background color │
234 ├────────────────────┼────────────────────────────┤
235 │YAS_FGCOLOR(color) │ shift simple color value │
236 │ │ into foreground color │
237 ├────────────────────┼────────────────────────────┤
238 │YAS_BGCOLOR(color) │ shift simple color value │
239 │ │ into background color │
240 ├────────────────────┼────────────────────────────┤
241 │YAS_FGXCOLOR(color) │ shift 256 palette color │
242 │ │ value into foreground │
243 │ │ color │
244 ├────────────────────┼────────────────────────────┤
245 │YAS_BGXCOLOR(color) │ shift 256 palette color │
246 │ │ value into background │
247 │ │ color │
248 └────────────────────┴────────────────────────────┘
249 All of the above can be or'ed into attribute, provided that the bits
251 for foreground/background color are all zeroes.
252 Key codes
255 · Special, generated internally
258 ┌────────────────┬───────┬─────────────────────┐
262 │Name │ Value │ Description │
263 ├────────────────┼───────┼─────────────────────┤
264 │YAS_K_NONE │ -1 │ no key is avail‐ │
265 │ │ │ able; in time lim‐ │
266 │ │ │ ited mode means │
267 │ │ │ that the time limit │
268 │ │ │ expired │
269 ├────────────────┼───────┼─────────────────────┤
270 │YAS_SCREEN_SIZE │ 0x800 │ notification for │
271 │ │ │ screen size change │
272 │ │ │ (may come because │
273 │ │ │ of telnet or ANSI │
274 │ │ │ sequence) │
275 ├────────────────┼───────┼─────────────────────┤
276 │YAS_TELNET_SIZE │ 0x801 │ notification for │
277 │ │ │ screen size change; │
278 │ │ │ duplicates the │
279 │ │ │ above, may be used │
280 │ │ │ to differentiate │
281 │ │ │ how screen size │
282 │ │ │ change event was │
283 │ │ │ generated │
284 └────────────────┴───────┴─────────────────────┘
285 · Normal keys
287 ┌─────────────┬───────┬───────────────────────────────┐
291 │Name │ Value │ Description │
292 ├─────────────┼───────┼───────────────────────────────┤
293 │YAS_K_NUL │ 0x00 │ Nul; on some terminals Ctrl-2 │
294 ├─────────────┼───────┼───────────────────────────────┤
295 │YAS_K_C_A │ 0x01 │ Ctrl-A │
296 ├─────────────┼───────┼───────────────────────────────┤
297 │YAS_K_C_B │ 0x02 │ Ctrl-B │
298 ├─────────────┼───────┼───────────────────────────────┤
299 │YAS_K_C_C │ 0x03 │ Ctrl-C │
300 ├─────────────┼───────┼───────────────────────────────┤
301 │YAS_K_C_D │ 0x04 │ Ctrl-D │
302 ├─────────────┼───────┼───────────────────────────────┤
303 │YAS_K_C_E │ 0x05 │ Ctrl-E │
304 ├─────────────┼───────┼───────────────────────────────┤
305 │YAS_K_C_F │ 0x06 │ Ctrl-F │
306 ├─────────────┼───────┼───────────────────────────────┤
307 │YAS_K_C_G │ 0x07 │ Ctrl-G │
308 ├─────────────┼───────┼───────────────────────────────┤
309 │YAS_K_C_H │ 0x08 │ Ctrl-H; depends on terminal │
310 │ │ │ see YAS_K_BSP, YAS_K_C_8 │
311 ├─────────────┼───────┼───────────────────────────────┤
312 │YAS_K_C_I │ 0x09 │ Ctrl-I │
313 ├─────────────┼───────┼───────────────────────────────┤
314 │YAS_K_TAB │ 0x09 │ Tab │
315 ├─────────────┼───────┼───────────────────────────────┤
316 │YAS_K_C_J │ 0x0a │ Ctrl-J │
317 ├─────────────┼───────┼───────────────────────────────┤
318 │YAS_K_C_K │ 0x0b │ Ctrl-K │
319 ├─────────────┼───────┼───────────────────────────────┤
320 │YAS_K_C_L │ 0x0c │ Ctrl-L │
321 ├─────────────┼───────┼───────────────────────────────┤
322 │YAS_K_C_M │ 0x0d │ Enter, Return, Ctrl-M; see │
323 │ │ │ below │
324 ├─────────────┼───────┼───────────────────────────────┤
325 │YAS_K_RET │ 0x0d │ Enter, Return, Ctrl-M; see │
326 │ │ │ above │
327 ├─────────────┼───────┼───────────────────────────────┤
328 │YAS_K_C_N │ 0x0e │ Ctrl-N │
329 ├─────────────┼───────┼───────────────────────────────┤
330 │YAS_K_C_O │ 0x0f │ Ctrl-O │
331 ├─────────────┼───────┼───────────────────────────────┤
332 │YAS_K_C_P │ 0x10 │ Ctrl-O │
333 ├─────────────┼───────┼───────────────────────────────┤
334 │YAS_K_C_Q │ 0x11 │ Ctrl-Q │
335 ├─────────────┼───────┼───────────────────────────────┤
336 │YAS_K_C_R │ 0x12 │ Ctrl-R │
337 ├─────────────┼───────┼───────────────────────────────┤
338 │YAS_K_C_S │ 0x13 │ Ctrl-S │
339 ├─────────────┼───────┼───────────────────────────────┤
340 │YAS_K_C_T │ 0x14 │ Ctrl-T │
341 ├─────────────┼───────┼───────────────────────────────┤
342 │YAS_K_C_U │ 0x15 │ Ctrl-U │
343 ├─────────────┼───────┼───────────────────────────────┤
344 │YAS_K_C_V │ 0x16 │ Ctrl-V │
345 ├─────────────┼───────┼───────────────────────────────┤
346 │YAS_K_C_W │ 0x17 │ Ctrl-W │
347 ├─────────────┼───────┼───────────────────────────────┤
348 │YAS_K_C_X │ 0x18 │ Ctrl-X │
349 ├─────────────┼───────┼───────────────────────────────┤
350 │YAS_K_C_Y │ 0x19 │ Ctrl-Y │
351 ├─────────────┼───────┼───────────────────────────────┤
352 │YAS_K_C_Z │ 0x1a │ Ctrl-Z │
353 ├─────────────┼───────┼───────────────────────────────┤
354 │YAS_K_ESC │ 0x1b │ Esc, Ctrl-3; see below; All │
355 │ │ │ ANSI sequences start with │
356 │ │ │ Esc, this is return after a │
357 │ │ │ timeout or double Esc │
358 ├─────────────┼───────┼───────────────────────────────┤
359 │YAS_K_C_3 │ 0x1b │ Esc, Ctrl-3; see above; All │
360 │ │ │ ANSI sequences start with │
361 │ │ │ Esc, this is return after a │
362 │ │ │ timeout or double Esc │
363 ├─────────────┼───────┼───────────────────────────────┤
364 │YAS_K_C_4 │ 0x1c │ Ctrl-4 │
365 ├─────────────┼───────┼───────────────────────────────┤
366 │YAS_K_C_5 │ 0x1d │ Ctrl-5 │
367 ├─────────────┼───────┼───────────────────────────────┤
368 │YAS_K_C_6 │ 0x1e │ Ctrl-6 │
369 ├─────────────┼───────┼───────────────────────────────┤
370 │YAS_K_C_7 │ 0x1f │ Ctrl-7 │
371 ├─────────────┼───────┼───────────────────────────────┤
372 │YAS_K_SPACE │ 0x20 │ Space │
373 ├─────────────┼───────┼───────────────────────────────┤
374 │YAS_K_EXCL │ 0x21 │ ! │
375 ├─────────────┼───────┼───────────────────────────────┤
376 │YAS_K_DQUOT │ 0x22 │ " │
377 ├─────────────┼───────┼───────────────────────────────┤
378 │YAS_K_HASH │ 0x23 │ # │
379 ├─────────────┼───────┼───────────────────────────────┤
380 │YAS_K_POUND │ 0x24 │ $ │
381 ├─────────────┼───────┼───────────────────────────────┤
382 │YAS_K_PERC │ 0x25 │ % │
383 ├─────────────┼───────┼───────────────────────────────┤
384 │YAS_K_AND │ 0x26 │ Ampersand │
385 ├─────────────┼───────┼───────────────────────────────┤
386 │YAS_K_QUOT │ 0x27 │ ' │
387 ├─────────────┼───────┼───────────────────────────────┤
388 │YAS_K_OBRA │ 0x28 │ ( │
389 ├─────────────┼───────┼───────────────────────────────┤
390 │YAS_K_CBRA │ 0x29 │ ) │
391 ├─────────────┼───────┼───────────────────────────────┤
392 │YAS_K_STAR │ 0x2a │ * │
393 ├─────────────┼───────┼───────────────────────────────┤
394 │YAS_K_PLUS │ 0x2b │ + │
395 ├─────────────┼───────┼───────────────────────────────┤
396 │YAS_K_COMMA │ 0x2c │ , │
397 ├─────────────┼───────┼───────────────────────────────┤
398 │YAS_K_MINUS │ 0x2d │ - │
399 ├─────────────┼───────┼───────────────────────────────┤
400 │YAS_K_DOT │ 0x2e │ . │
401 ├─────────────┼───────┼───────────────────────────────┤
402 │YAS_K_SLASH │ 0x2f │ / │
403 ├─────────────┼───────┼───────────────────────────────┤
404 │YAS_K_0 │ 0x30 │ 0 │
405 ├─────────────┼───────┼───────────────────────────────┤
406 │YAS_K_1 │ 0x31 │ 1 │
407 ├─────────────┼───────┼───────────────────────────────┤
408 │YAS_K_2 │ 0x32 │ 2 │
409 ├─────────────┼───────┼───────────────────────────────┤
410 │YAS_K_3 │ 0x33 │ 3 │
411 ├─────────────┼───────┼───────────────────────────────┤
412 │YAS_K_4 │ 0x34 │ 4 │
413 ├─────────────┼───────┼───────────────────────────────┤
414 │YAS_K_5 │ 0x35 │ 5 │
415 ├─────────────┼───────┼───────────────────────────────┤
416 │YAS_K_6 │ 0x36 │ 6 │
417 ├─────────────┼───────┼───────────────────────────────┤
418 │YAS_K_7 │ 0x37 │ 7 │
419 ├─────────────┼───────┼───────────────────────────────┤
420 │YAS_K_8 │ 0x38 │ 8 │
421 ├─────────────┼───────┼───────────────────────────────┤
422 │YAS_K_9 │ 0x39 │ 9 │
423 ├─────────────┼───────┼───────────────────────────────┤
424 │YAS_K_COLON │ 0x3a │ : │
425 ├─────────────┼───────┼───────────────────────────────┤
426 │YAS_K_SEMI │ 0x3b │ ; │
427 ├─────────────┼───────┼───────────────────────────────┤
428 │YAS_K_LT │ 0x3c │ < │
429 ├─────────────┼───────┼───────────────────────────────┤
430 │YAS_K_EQ │ 0x3d │ = │
431 ├─────────────┼───────┼───────────────────────────────┤
432 │YAS_K_GT │ 0x3e │ > │
433 ├─────────────┼───────┼───────────────────────────────┤
434 │YAS_K_QUEST │ 0x3f │ ? │
435 ├─────────────┼───────┼───────────────────────────────┤
436 │YAS_K_AT │ 0x40 │ @ │
437 ├─────────────┼───────┼───────────────────────────────┤
438 │YAS_K_A │ 0x41 │ A │
439 ├─────────────┼───────┼───────────────────────────────┤
440 │YAS_K_B │ 0x42 │ B │
441 ├─────────────┼───────┼───────────────────────────────┤
442 │YAS_K_C │ 0x43 │ C │
443 ├─────────────┼───────┼───────────────────────────────┤
444 │YAS_K_D │ 0x44 │ D │
445 ├─────────────┼───────┼───────────────────────────────┤
446 │YAS_K_E │ 0x45 │ E │
447 ├─────────────┼───────┼───────────────────────────────┤
448 │YAS_K_F │ 0x46 │ F │
449 ├─────────────┼───────┼───────────────────────────────┤
450 │YAS_K_G │ 0x47 │ G │
451 ├─────────────┼───────┼───────────────────────────────┤
452 │YAS_K_H │ 0x48 │ H │
453 ├─────────────┼───────┼───────────────────────────────┤
454 │YAS_K_I │ 0x49 │ I │
455 ├─────────────┼───────┼───────────────────────────────┤
456 │YAS_K_J │ 0x4a │ J │
457 ├─────────────┼───────┼───────────────────────────────┤
458 │YAS_K_K │ 0x4b │ K │
459 ├─────────────┼───────┼───────────────────────────────┤
460 │YAS_K_L │ 0x4c │ L │
461 ├─────────────┼───────┼───────────────────────────────┤
462 │YAS_K_M │ 0x4d │ M │
463 ├─────────────┼───────┼───────────────────────────────┤
464 │YAS_K_N │ 0x4e │ N │
465 ├─────────────┼───────┼───────────────────────────────┤
466 │YAS_K_O │ 0x4f │ O │
467 ├─────────────┼───────┼───────────────────────────────┤
468 │YAS_K_P │ 0x50 │ P │
469 ├─────────────┼───────┼───────────────────────────────┤
470 │YAS_K_Q │ 0x51 │ Q │
471 ├─────────────┼───────┼───────────────────────────────┤
472 │YAS_K_R │ 0x52 │ R │
473 ├─────────────┼───────┼───────────────────────────────┤
474 │YAS_K_S │ 0x53 │ S │
475 ├─────────────┼───────┼───────────────────────────────┤
476 │YAS_K_T │ 0x54 │ T │
477 ├─────────────┼───────┼───────────────────────────────┤
478 │YAS_K_U │ 0x55 │ U │
479 ├─────────────┼───────┼───────────────────────────────┤
480 │YAS_K_V │ 0x56 │ V │
481 ├─────────────┼───────┼───────────────────────────────┤
482 │YAS_K_W │ 0x57 │ W │
483 ├─────────────┼───────┼───────────────────────────────┤
484 │YAS_K_X │ 0x58 │ X │
485 ├─────────────┼───────┼───────────────────────────────┤
486 │YAS_K_Y │ 0x59 │ Y │
487 ├─────────────┼───────┼───────────────────────────────┤
488 │YAS_K_Z │ 0x5a │ Z │
489 ├─────────────┼───────┼───────────────────────────────┤
490 │YAS_K_OSQ │ 0x5b │ [ │
491 ├─────────────┼───────┼───────────────────────────────┤
492 │YAS_K_BSLASH │ 0x5c │ \ │
493 ├─────────────┼───────┼───────────────────────────────┤
494 │YAS_K_CSQ │ 0x5d │ ] │
495 ├─────────────┼───────┼───────────────────────────────┤
496 │YAS_K_CARRET │ 0x5e │ ^ │
497 ├─────────────┼───────┼───────────────────────────────┤
498 │YAS_K_USCORE │ 0x5f │ _ │
499 ├─────────────┼───────┼───────────────────────────────┤
500 │YAS_K_BTICK │ 0x60 │ ` │
501 ├─────────────┼───────┼───────────────────────────────┤
502 │YAS_K_a │ 0x61 │ a │
503 ├─────────────┼───────┼───────────────────────────────┤
504 │YAS_K_b │ 0x62 │ b │
505 ├─────────────┼───────┼───────────────────────────────┤
506 │YAS_K_c │ 0x63 │ c │
507 ├─────────────┼───────┼───────────────────────────────┤
508 │YAS_K_d │ 0x64 │ d │
509 ├─────────────┼───────┼───────────────────────────────┤
510 │YAS_K_e │ 0x65 │ e │
511 ├─────────────┼───────┼───────────────────────────────┤
512 │YAS_K_f │ 0x66 │ f │
513 ├─────────────┼───────┼───────────────────────────────┤
514 │YAS_K_g │ 0x67 │ g │
515 ├─────────────┼───────┼───────────────────────────────┤
516 │YAS_K_h │ 0x68 │ h │
517 ├─────────────┼───────┼───────────────────────────────┤
518 │YAS_K_i │ 0x69 │ i │
519 ├─────────────┼───────┼───────────────────────────────┤
520 │YAS_K_j │ 0x6a │ j │
521 ├─────────────┼───────┼───────────────────────────────┤
522 │YAS_K_k │ 0x6b │ k │
523 ├─────────────┼───────┼───────────────────────────────┤
524 │YAS_K_l │ 0x6c │ l │
525 ├─────────────┼───────┼───────────────────────────────┤
526 │YAS_K_m │ 0x6d │ m │
527 ├─────────────┼───────┼───────────────────────────────┤
528 │YAS_K_n │ 0x6e │ n │
529 ├─────────────┼───────┼───────────────────────────────┤
530 │YAS_K_o │ 0x6f │ o │
531 ├─────────────┼───────┼───────────────────────────────┤
532 │YAS_K_p │ 0x70 │ p │
533 ├─────────────┼───────┼───────────────────────────────┤
534 │YAS_K_q │ 0x71 │ q │
535 ├─────────────┼───────┼───────────────────────────────┤
536 │YAS_K_r │ 0x72 │ r │
537 ├─────────────┼───────┼───────────────────────────────┤
538 │YAS_K_s │ 0x73 │ s │
539 ├─────────────┼───────┼───────────────────────────────┤
540 │YAS_K_t │ 0x74 │ t │
541 ├─────────────┼───────┼───────────────────────────────┤
542 │YAS_K_u │ 0x75 │ u │
543 ├─────────────┼───────┼───────────────────────────────┤
544 │YAS_K_v │ 0x76 │ v │
545 ├─────────────┼───────┼───────────────────────────────┤
546 │YAS_K_w │ 0x77 │ w │
547 ├─────────────┼───────┼───────────────────────────────┤
548 │YAS_K_x │ 0x78 │ x │
549 ├─────────────┼───────┼───────────────────────────────┤
550 │YAS_K_y │ 0x79 │ y │
551 ├─────────────┼───────┼───────────────────────────────┤
552 │YAS_K_z │ 0x7a │ z │
553 ├─────────────┼───────┼───────────────────────────────┤
554 │YAS_K_OCUR │ 0x7b │ { │
555 ├─────────────┼───────┼───────────────────────────────┤
556 │YAS_K_PIPE │ 0x7c │ | │
557 ├─────────────┼───────┼───────────────────────────────┤
558 │YAS_K_CCUR │ 0x7d │ } │
559 ├─────────────┼───────┼───────────────────────────────┤
560 │YAS_K_TLD │ 0x7e │ Tilde │
561 ├─────────────┼───────┼───────────────────────────────┤
562 │YAS_K_C_8 │ 0x7f │ Backspace; see below; depends │
563 │ │ │ on terminal see YAS_K_C_H │
564 ├─────────────┼───────┼───────────────────────────────┤
565 │YAS_K_BSP │ 0x7f │ Backspace; see below; depends │
566 │ │ │ on terminal see YAS_K_C_H │
567 └─────────────┴───────┴───────────────────────────────┘
568 · Extended keys, parsed from ANSI sequences
570 ┌──────────────┬───────┬─────────────┐
574 │Name │ Value │ Description │
575 ├──────────────┼───────┼─────────────┤
576 │YAS_K_F1 │ 0x100 │ F1 │
577 ├──────────────┼───────┼─────────────┤
578 │YAS_K_F2 │ 0x101 │ F2 │
579 ├──────────────┼───────┼─────────────┤
580 │YAS_K_F3 │ 0x102 │ F3 │
581 ├──────────────┼───────┼─────────────┤
582 │YAS_K_F4 │ 0x103 │ F4 │
583 ├──────────────┼───────┼─────────────┤
584 │YAS_K_F5 │ 0x104 │ F5 │
585 ├──────────────┼───────┼─────────────┤
586 │YAS_K_F6 │ 0x105 │ F6 │
587 ├──────────────┼───────┼─────────────┤
588 │YAS_K_F7 │ 0x106 │ F7 │
589 ├──────────────┼───────┼─────────────┤
590 │YAS_K_F8 │ 0x107 │ F8 │
591 ├──────────────┼───────┼─────────────┤
592 │YAS_K_F9 │ 0x108 │ F9 │
593 ├──────────────┼───────┼─────────────┤
594 │YAS_K_F10 │ 0x109 │ F10 │
595 ├──────────────┼───────┼─────────────┤
596 │YAS_K_F11 │ 0x10a │ F11 │
597 ├──────────────┼───────┼─────────────┤
598 │YAS_K_F12 │ 0x10b │ F12 │
599 ├──────────────┼───────┼─────────────┤
600 │YAS_K_S_F1 │ 0x10c │ Shift-F1 │
601 ├──────────────┼───────┼─────────────┤
602 │YAS_K_S_F2 │ 0x10d │ Shift-F2 │
603 ├──────────────┼───────┼─────────────┤
604 │YAS_K_S_F3 │ 0x10e │ Shift-F3 │
605 ├──────────────┼───────┼─────────────┤
606 │YAS_K_S_F4 │ 0x10f │ Shift-F4 │
607 ├──────────────┼───────┼─────────────┤
608 │YAS_K_S_F5 │ 0x110 │ Shift-F5 │
609 ├──────────────┼───────┼─────────────┤
610 │YAS_K_S_F6 │ 0x111 │ Shift-F6 │
611 ├──────────────┼───────┼─────────────┤
612 │YAS_K_S_F7 │ 0x112 │ Shift-F7 │
613 ├──────────────┼───────┼─────────────┤
614 │YAS_K_S_F8 │ 0x113 │ Shift-F8 │
615 ├──────────────┼───────┼─────────────┤
616 │YAS_K_S_F9 │ 0x114 │ Shift-F9 │
617 ├──────────────┼───────┼─────────────┤
618 │YAS_K_S_F10 │ 0x115 │ Shift-F10 │
619 ├──────────────┼───────┼─────────────┤
620 │YAS_K_S_F11 │ 0x116 │ Shift-F11 │
621 ├──────────────┼───────┼─────────────┤
622 │YAS_K_S_F12 │ 0x117 │ Shift-F12 │
623 ├──────────────┼───────┼─────────────┤
624 │YAS_K_C_F1 │ 0x118 │ Ctrl-F1 │
625 ├──────────────┼───────┼─────────────┤
626 │YAS_K_C_F2 │ 0x119 │ Ctrl-F2 │
627 ├──────────────┼───────┼─────────────┤
628 │YAS_K_C_F3 │ 0x11a │ Ctrl-F3 │
629 ├──────────────┼───────┼─────────────┤
630 │YAS_K_C_F4 │ 0x11b │ Ctrl-F4 │
631 ├──────────────┼───────┼─────────────┤
632 │YAS_K_C_F5 │ 0x11c │ Ctrl-F5 │
633 ├──────────────┼───────┼─────────────┤
634 │YAS_K_C_F6 │ 0x11d │ Ctrl-F6 │
635 ├──────────────┼───────┼─────────────┤
636 │YAS_K_C_F7 │ 0x11e │ Ctrl-F7 │
637 ├──────────────┼───────┼─────────────┤
638 │YAS_K_C_F8 │ 0x11f │ Ctrl-F8 │
639 ├──────────────┼───────┼─────────────┤
640 │YAS_K_C_F9 │ 0x120 │ Ctrl-F9 │
641 ├──────────────┼───────┼─────────────┤
642 │YAS_K_C_F10 │ 0x121 │ Ctrl-F10 │
643 ├──────────────┼───────┼─────────────┤
644 │YAS_K_C_F11 │ 0x122 │ Ctrl-F11 │
645 ├──────────────┼───────┼─────────────┤
646 │YAS_K_C_F12 │ 0x123 │ Ctrl-F12 │
647 ├──────────────┼───────┼─────────────┤
648 │YAS_K_A_F1 │ 0x124 │ Alt-F1 │
649 ├──────────────┼───────┼─────────────┤
650 │YAS_K_A_F2 │ 0x125 │ Alt-F2 │
651 ├──────────────┼───────┼─────────────┤
652 │YAS_K_A_F3 │ 0x126 │ Alt-F3 │
653 ├──────────────┼───────┼─────────────┤
654 │YAS_K_A_F4 │ 0x127 │ Alt-F4 │
655 ├──────────────┼───────┼─────────────┤
656 │YAS_K_A_F5 │ 0x128 │ Alt-F5 │
657 ├──────────────┼───────┼─────────────┤
658 │YAS_K_A_F6 │ 0x129 │ Alt-F6 │
659 ├──────────────┼───────┼─────────────┤
660 │YAS_K_A_F7 │ 0x12a │ Alt-F7 │
661 ├──────────────┼───────┼─────────────┤
662 │YAS_K_A_F8 │ 0x12b │ Alt-F8 │
663 ├──────────────┼───────┼─────────────┤
664 │YAS_K_A_F9 │ 0x12c │ Alt-F9 │
665 ├──────────────┼───────┼─────────────┤
666 │YAS_K_A_F10 │ 0x12d │ Alt-F10 │
667 ├──────────────┼───────┼─────────────┤
668 │YAS_K_A_F11 │ 0x12e │ Alt-F11 │
669 ├──────────────┼───────┼─────────────┤
670 │YAS_K_A_F12 │ 0x12f │ Alt-F12 │
671 ├──────────────┼───────┼─────────────┤
672 │YAS_K_LEFT │ 0x130 │ Left │
673 ├──────────────┼───────┼─────────────┤
674 │YAS_K_UP │ 0x131 │ Up │
675 ├──────────────┼───────┼─────────────┤
676 │YAS_K_DOWN │ 0x132 │ Down │
677 ├──────────────┼───────┼─────────────┤
678 │YAS_K_RIGHT │ 0x133 │ Right │
679 ├──────────────┼───────┼─────────────┤
680 │YAS_K_HOME │ 0x134 │ Home │
681 ├──────────────┼───────┼─────────────┤
682 │YAS_K_END │ 0x135 │ End │
683 ├──────────────┼───────┼─────────────┤
684 │YAS_K_PGUP │ 0x136 │ PageUp │
685 ├──────────────┼───────┼─────────────┤
686 │YAS_K_PGDN │ 0x137 │ PageDown │
687 ├──────────────┼───────┼─────────────┤
688 │YAS_K_INS │ 0x138 │ Insert │
689 ├──────────────┼───────┼─────────────┤
690 │YAS_K_DEL │ 0x139 │ Delete │
691 ├──────────────┼───────┼─────────────┤
692 │YAS_K_C_LEFT │ 0x13a │ Ctrl-Left │
693 ├──────────────┼───────┼─────────────┤
694 │YAS_K_C_UP │ 0x13b │ Ctrl-Up │
695 ├──────────────┼───────┼─────────────┤
696 │YAS_K_C_DOWN │ 0x13c │ Ctrl-Down │
697 ├──────────────┼───────┼─────────────┤
698 │YAS_K_C_RIGHT │ 0x13d │ Ctrl-Right │
699 └──────────────┴───────┴─────────────┘
700 · Alt-<letter>
702 These codes are generated by a helper macro - YAS_K_ALT(keycode).
706 ┌───────────────┬───────────────┐
709 │Name │ Description │
710 ├───────────────┼───────────────┤
711 │YAS_K_A_BT │ Alt-Backtick │
712 ├───────────────┼───────────────┤
713 │YAS_K_A_1 │ Alt-1 │
714 ├───────────────┼───────────────┤
715 │YAS_K_A_2 │ Alt-2 │
716 ├───────────────┼───────────────┤
717 │YAS_K_A_3 │ Alt-3 │
718 ├───────────────┼───────────────┤
719 │YAS_K_A_4 │ Alt-4 │
720 ├───────────────┼───────────────┤
721 │YAS_K_A_5 │ Alt-5 │
722 ├───────────────┼───────────────┤
723 │YAS_K_A_6 │ Alt-6 │
724 ├───────────────┼───────────────┤
725 │YAS_K_A_7 │ Alt-7 │
726 ├───────────────┼───────────────┤
727 │YAS_K_A_8 │ Alt-8 │
728 ├───────────────┼───────────────┤
729 │YAS_K_A_9 │ Alt-9 │
730 ├───────────────┼───────────────┤
731 │YAS_K_A_0 │ Alt-0 │
732 ├───────────────┼───────────────┤
733 │YAS_K_A_MINUS │ Alt-Minus │
734 ├───────────────┼───────────────┤
735 │YAS_K_A_EQ │ Alt-= │
736 ├───────────────┼───────────────┤
737 │YAS_K_A_BSP │ Alt-Backspace │
738 ├───────────────┼───────────────┤
739 │YAS_K_A_TLD │ Alt-Tilde │
740 ├───────────────┼───────────────┤
741 │YAS_K_A_EXCL │ Alt-! │
742 ├───────────────┼───────────────┤
743 │YAS_K_A_AT │ Alt-@ │
744 ├───────────────┼───────────────┤
745 │YAS_K_A_HASH │ Alt-# │
746 ├───────────────┼───────────────┤
747 │YAS_K_A_POUND │ Alt-$ │
748 ├───────────────┼───────────────┤
749 │YAS_K_A_PERC │ Alt-% │
750 ├───────────────┼───────────────┤
751 │YAS_K_A_CARRET │ Alt-^ │
752 ├───────────────┼───────────────┤
753 │YAS_K_A_AND │ Alt-Ampersand │
754 ├───────────────┼───────────────┤
755 │YAS_K_A_STAR │ Alt-* │
756 ├───────────────┼───────────────┤
757 │YAS_K_A_OBRA │ Alt-( │
758 ├───────────────┼───────────────┤
759 │YAS_K_A_CBRA │ Alt-) │
760 ├───────────────┼───────────────┤
761 │YAS_K_A_UND │ Alt-_ │
762 ├───────────────┼───────────────┤
763 │YAS_K_A_PLUS │ Alt-+ │
764 ├───────────────┼───────────────┤
765 │YAS_K_A_a │ Alt-a │
766 ├───────────────┼───────────────┤
767 │YAS_K_A_b │ Alt-b │
768 ├───────────────┼───────────────┤
769 │YAS_K_A_c │ Alt-c │
770 ├───────────────┼───────────────┤
771 │YAS_K_A_d │ Alt-d │
772 ├───────────────┼───────────────┤
773 │YAS_K_A_e │ Alt-e │
774 ├───────────────┼───────────────┤
775 │YAS_K_A_f │ Alt-f │
776 ├───────────────┼───────────────┤
777 │YAS_K_A_g │ Alt-g │
778 ├───────────────┼───────────────┤
779 │YAS_K_A_h │ Alt-h │
780 ├───────────────┼───────────────┤
781 │YAS_K_A_i │ Alt-i │
782 ├───────────────┼───────────────┤
783 │YAS_K_A_j │ Alt-j │
784 ├───────────────┼───────────────┤
785 │YAS_K_A_k │ Alt-k │
786 ├───────────────┼───────────────┤
787 │YAS_K_A_l │ Alt-l │
788 ├───────────────┼───────────────┤
789 │YAS_K_A_m │ Alt-m │
790 ├───────────────┼───────────────┤
791 │YAS_K_A_n │ Alt-n │
792 ├───────────────┼───────────────┤
793 │YAS_K_A_o │ Alt-o │
794 ├───────────────┼───────────────┤
795 │YAS_K_A_p │ Alt-p │
796 ├───────────────┼───────────────┤
797 │YAS_K_A_q │ Alt-q │
798 ├───────────────┼───────────────┤
799 │YAS_K_A_r │ Alt-r │
800 ├───────────────┼───────────────┤
801 │YAS_K_A_s │ Alt-s │
802 ├───────────────┼───────────────┤
803 │YAS_K_A_t │ Alt-t │
804 ├───────────────┼───────────────┤
805 │YAS_K_A_u │ Alt-u │
806 ├───────────────┼───────────────┤
807 │YAS_K_A_v │ Alt-v │
808 ├───────────────┼───────────────┤
809 │YAS_K_A_w │ Alt-w │
810 ├───────────────┼───────────────┤
811 │YAS_K_A_x │ Alt-x │
812 ├───────────────┼───────────────┤
813 │YAS_K_A_y │ Alt-y │
814 ├───────────────┼───────────────┤
815 │YAS_K_A_z │ Alt-z │
816 └───────────────┴───────────────┘
817
819 All functions in the API work with a pointer to an opaque yascreen
820 structure.
821 The structure is allocated internally in the library by yascreen_init
824 and it is the job of the user program to keep track of it.
825 The library is thread safe, as long as each struct yascreen object is
828 accessed by a single thread.
829 yascreen_init
832 inline yascreen *yascreen_init(int sx,int sy);
833 allocate and initialize screen data output defaults to stdout in case
837 output is a terminal and initial size is (0,0), the screen size is
838 autodetected
839 in case of error, returns NULL
842 yascreen_ver
845 inline const char *yascreen_ver(void);
846 returns a string with the library version
850 yascreen_setout
853 inline int yascreen_setout(yascreen *s,ssize_t (*out)(yascreen *s,const void *data,size_t len));
854 set callback that handles output if out=NULL, the output goes to stdout
858 the callback may implement internal buffering, a flush is signalled by
861 calling out with len=0
862 yascreen_set_telnet
865 inline void yascreen_set_telnet(yascreen *s,int on);
866 enable (on is non-zero) or disable (on=0) telnet sequence processing
870 yascreen_init_telnet
873 inline void yascreen_init_telnet(yascreen *s);
874 depending on telnet sequence processing, sends a set of telnet initial‐
878 ization sequences
879 yascreen_resize
882 inline int yascreen_resize(yascreen *s,int sx,int sy);
883 resize screen should redraw afterwards since allocation is involved,
887 this may fail and return -1
888 yascreen_free
891 inline void yascreen_free(yascreen *s);
892 finish the lifecycle of struct yascreen - all internally allocated mem‐
896 ory is freed
897 yascreen_term_save
900 inline void yascreen_term_save(yascreen *s);
901 save current terminal state on top of state stack
905 yascreen_term_restore
908 inline void yascreen_term_restore(yascreen *s);
909 restore previously saved terminal state from top of state stack
913 yascreen_term_push
916 inline void yascreen_term_push(yascreen *s);
917 push current terminal state to state stack
921 yascreen_term_pop
924 inline void yascreen_term_pop(yascreen *s);
925 pop and restore previously saved terminal state from state stack
929 yascreen_term_set
932 inline void yascreen_term_set(yascreen *s,int mode);
933 set terminal for proper screen operation
937 mode is a bitmask, containing one of
940 ┌───────────┬───────┬─────────────────────┐
941 │Name │ Value │ Description │
942 ├───────────┼───────┼─────────────────────┤
943 │YAS_NOBUFF │ 1 │ turn off canonical │
944 │ │ │ mode (disable │
945 │ │ │ ICANON and IEXTEN) │
946 ├───────────┼───────┼─────────────────────┤
947 │YAS_NOSIGN │ 2 │ disable ISIG │
948 ├───────────┼───────┼─────────────────────┤
949 │YAS_NOECHO │ 4 │ disable local echo │
950 │ │ │ (ECHO) │
951 ├───────────┼───────┼─────────────────────┤
952 │YAS_ONLCR │ 8 │ ONLCR|OPOST │
953 └───────────┴───────┴─────────────────────┘
954 yascreen_printxy
956 inline int yascreen_printxy(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));
957 yascreen_putsxy
961 inline int yascreen_putsxy(yascreen *s,int x,int y,uint32_t attr,const char *str);
962 print at position, if data exceeds buffer, then it gets truncated
966 yascreen_printxyu
969 inline int yascreen_printxyu(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));
970 yascreen_putsxyu
974 inline int yascreen_putsxyu(yascreen *s,int x,int y,uint32_t attr,const char *str);
975 print at position, if data exceeds buffer, then it gets truncated
979 screen is immediately updated
980 yascreen_update
983 inline int yascreen_update(yascreen *s);
984 sync memory state to screen since allocation is involved, this may fail
988 and return -1
989 yascreen_redraw
992 inline void yascreen_redraw(yascreen *s);
993 set next update to be a full redraw
997 yascreen_clear_mem
1000 inline void yascreen_clear_mem(yascreen *s,uint32_t attr);
1001 clear memory buffer all cells in the screen are set to Space, using
1005 attr for colors and style
1006 yascreen_cursor
1009 inline void yascreen_cursor(yascreen *s,int on);
1010 hide (on=0) or show (on is non-zero) cusror screen is updated immedi‐
1014 ately
1015 yascreen_cursor_xy
1018 inline void yascreen_cursor_xy(yascreen *s,int x,int y);
1019 set cursor position screen is updated immediately
1023 yascreen_altbuf
1026 inline void yascreen_altbuf(yascreen *s,int on);
1027 switch between regular and alternative buffer screen is updated immedi‐
1031 ately
1032 yascreen_clear
1035 inline void yascreen_clear(yascreen *s);
1036 clear real screen, no change to memory buffers
1040 yascreen_clearln
1043 inline void yascreen_clearln(yascreen *s);
1044 clear current line, no change to memory buffers
1048 yascreen_update_attr
1051 inline void yascreen_update_attr(yascreen *s,uint32_t oattr,uint32_t nattr);
1052 apply difference between two attrs and output the optimized ANSI
1056 sequence to switch from oattr to nattr if oattr=0xffffffff, the full
1057 ANSI sequence will be generated no change to memory buffers
1058 yascreen_set_attr
1061 yascreen_set_attr(s,attr)
1062 reset all attrs and set specific one (attr)
1066 yascreen_print
1069 inline int yascreen_print(yascreen *s,const char *format,...) __attribute__((format(printf,2,3)));
1070 yascreen_write
1074 inline int yascreen_write(yascreen *s,const char *str,int len);
1075 yascreen_puts
1079 inline int yascreen_puts(yascreen *s,const char *str);
1080 yascreen_clearln_s
1084 inline const char *yascreen_clearln_s(yascreen *s);
1085 print in line mode
1089 yascreen_sx
1092 inline int yascreen_sx(yascreen *s);
1093 get current x size
1097 yascreen_sy
1100 inline int yascreen_sy(yascreen *s);
1101 get current y size
1105 yascreen_x
1108 inline int yascreen_x(yascreen *s);
1109 get current x
1113 yascreen_y
1116 inline int yascreen_y(yascreen *s);
1117 get current y
1121 yascreen_esc_to
1124 inline void yascreen_esc_to(yascreen *s,int timeout);
1125 set timeout for single ESC key press
1129 yascreen_ckto
1132 inline void yascreen_ckto(yascreen *s);
1133 in case of external event loop, this call will check for single ESC key
1137 should be called regularly enough so that the above specified timeout
1138 is not extended too much if not called often enough then single ESC
1139 will be yielded after longer timeout if not called at all then single
1140 ESC will be yielded with next key press
1141 yascreen_getch_to
1144 inline int yascreen_getch_to(yascreen *s,int timeout);
1145 wait for a key, return ASCII or extended keycode, wait no more than
1149 timeout in milliseconds
1150 yascreen_getch
1153 yascreen_getch(s)
1154 get a key without timeout this macro expands to yascreen_getch_to(s,0)
1158 zero timeout=wait forever
1159 yascreen_getch_nowait
1162 yascreen_getch_nowait(s)
1163 get a key, if available, return immediately this macro expands to
1167 yascreen_getch_to(s,-1) negative timeout=do not wait
1168 yascreen_ungetch
1171 inline void yascreen_ungetch(yascreen *s,int key);
1172 put back key value in key buffer the internal key buffer is dynamically
1176 allocated, hence there is no limit of how many key codes may be put
1177 back, but in case of memory allocation failure, the error will not be
1178 reported and the key will not be put into the buffer
1179 yascreen_pushch
1182 inline void yascreen_pushch(yascreen *s,int key);
1183 push key value at end of key buffer similar to yascreen_ungetch but the
1187 key code will be returned after all other key codes currently in the
1188 buffer the internal key buffer is dynamically allocated, hence there is
1189 no limit of how many key codes may be put back, but in case of memory
1190 allocation failure, the error will not be reported and the key will not
1191 be put into the buffer
1192 yascreen_feed
1195 inline void yascreen_feed(yascreen *s,unsigned char c);
1196 feed key sequence state machine with byte stream this is useful to
1200 implement external event loop and read key codes by
1201 yascreen_getch_nowait until it returns -1
1202 yascreen_peekch
1205 inline int yascreen_peekch(yascreen *s);
1206 peek for key without removing it from input queue
1210 yascreen_getsize
1213 inline void yascreen_getsize(yascreen *s,int *sx,int *sy);
1214 get last reported screen size set both to 0 if there is none this will
1218 yield valid result after YAS_SCREEN_SIZE is returned as keypress
1219 yascreen_reqsize
1222 inline void yascreen_reqsize(yascreen *s);
1223 request terminal to report its size via ANSI sequence
1227 yascreen_set_hint_i
1230 inline void yascreen_set_hint_i(yascreen *s,int hint);
1231 yascreen_get_hint_i
1235 inline int yascreen_get_hint_i(yascreen *s);
1236 yascreen_set_hint_p
1240 inline void yascreen_set_hint_p(yascreen *s,void *hint);
1241 yascreen_get_hint_p
1245 inline void *yascreen_get_hint_p(yascreen *s);
1246 get/set opaque hint values integer and pointer hints are stored sepa‐
1250 rately and both can be used at the same time
1251 these are useful to link the yascreen instance to user program data
1254 for example a single output callback may output to socket or a termi‐
1257 nal, depending on the hint values
1258 yascreen_line_flush
1261 inline void yascreen_line_flush(yascreen *s,int on);
1262 enable/disable auto flush for line and direct screen oriented opera‐
1266 tions
1267 yascreen versions before 1.77 didn't use buffered output and would
1270 immediately send the output to the screen
1271 disabling internal flush can help an application optimize the number of
1274 write calls at the cost of performing explicit flush after each group
1275 of operations
1276 explicit flush example:
1279 yascreen_write(s,"",0);
1282yascreen September 30, 2020 YASCREEN(3)