YASCREEN(3)

NAME

yascreen - Yet Another Screen Library (curses replacement for daemons and embedded apps)

SYNOPSIS

#include <yascreen.h>

DESCRIPTION

Main features

    •   small footprint

    •   does not have external dependencies

    •   allows both internal and external event loop

    •   allows stdin/stdout or external input/output (can work over socket)

    •   supports basic set of telnet sequences, making it suitable for built-in terminal interfaces for daemons

    •   supports a limited set of input keystroke sequences

    •   fully unicode compatible (parts of this depend on wcwidth in libc)

    •   supports utf8 verification of input

    •   supports utf8 input and wide character input

    •   supports non-utf8 input mode

    •   relies only on a limited subset of ansi/xterm ESC sequences, making it compatible with mostly all modern terminals (inspired by linenoise ⟨https://github.com/antirez/linenoise⟩)

    •   there is no curses API and ancient terminal compatibility, hence less bloat

    •   there is no autoconf - there is no need to have one

    •   clean API with opaque private data, usable from C/C++

    •   easy cross compilation setup (by setting CC, AR and RANLIB)

Current development is done on Linux, with additional testing on OpenBSD/FreeBSD; other platforms may need minimal fixes.

On *BSD a gmake is required to build.

Architecture

yascreen uses an opaque data structure, allocated by the library and dynamically resized when needed - yascreen_init(int sx, int sy) / yascreen_resize(yascreen *s, int sx, int sy). An application may specify (0,0) for both calls to let yascreen detect the size or use a fixed size. In case the terminal has zero size or does not support the TIOCGWINSZ ioctl, the size will default to 80x24.

There are two modes of operation - telnet protocol over socket or running in terminal. For sockets the event loop would typically be handled outside of the library while for terminals a built-in event loop may be used.

Modes of operation can be modified at runtime.

For terminal use signal handling (SIGWINCH) should always be handled by the application.

Example initialization for terminal and handling of SIGWINCH
    yascreen *s;
    int winch=0;
    void sigwinch(int sign) {
    	winch=1;
    }
    s=yascreen_init(0,0); // let yascreen get term size
    yascreen_term_set(s,YAS_NOBUFF|YAS_NOSIGN|YAS_NOECHO);
    signal(SIGWINCH,sigwinch);
    for (;;) { // main loop
    	if (winch) {
    		winch=0;
    		if (yascreen_resize(s,0,0))
    			// handle a fatal error - no memory
    		// get the new sizes and redraw
    		newsizex=yascreen_sx(s);
    		newsizey=yascreen_sy(s);
    	}
    	…
    	// option 1
    	// input is handled in external event loop and fed to yascreen via yascreen_feed
    	if (FD_ISSET(STDIN_FILENO,&r)&&sizeof c==read(STDIN_FILENO,&c,sizeof c))
    		yascreen_feed(s,c); // pump state machine with bytestream
    	// keys are processed only when available without delay/blocking
    	while ((ch=yascreen_getch_nowait(s))!=YAS_K_NONE) {
    		// handle processed keys
    	}
    	…
    	// option 2
    	// input is handled by yascreen and key or YAS_K_NONE is returned not longer than TIMEOUT ms
    	// note: if screen update is based on this, keypresses will force it
    	while ((ch=yascreen_getch_to(s,TIMEOUT))!=YAS_K_NONE) {
    		// handle processed keys
    	}
    	…
    	// option 3
    	// input is handled by yascreen and the following call will block until a key is pressed
    	if ((ch=yascreen_getch(s))!=YAS_K_NONE) {
    		// handle processed key
    	}
    }

For sockets input is handled like option 1 in the example above and yascreen needs to be provided with a callback for output.

In multiprocess mode daemons where stdin/stdout are redirected to a socket the same model from the example above can be used. Obviously SIGWINCH will work only for terminals and for sockets the screen size can get to be known either via telnet or ASNI sequences.

Example initialization for socket with external event loop and telnet sequences processing
    yascreen *s;
    s=yascreen_init(80,25); // there is no guarantee that screen size detection is supported on the remote end
    yascreen_setout(s,output_cb); // set callback for output
    yascreen_set_telnet(s,1); // enable processing of telnet sequences
    yascreen_init_telnet(s); // try to negotiate telnet options (regardless if telnet processing is enabled)
    yascreen_reqsize(s); // request initial screen size
    for (;;) { // main loop
    	…
    	yascreen_feed(s,c); // feed input from the socket to yascreen
    	// keys are processed only when available without delay/blocking
    	while ((ch=yascreen_getch_nowait(s))!=YAS_K_NONE) {
    		// handle processed keys
    		// screen size change is reported as a special keypress code:
    		if (ch==YAS_TELNET_SIZE||ch==YAS_SCREEN_SIZE) // screen size change reported via telnet or ANSI sequence
    			// redraw
    	}
    }

API Reference

Predefined constants and Helper macros

Internally style is kept into bitfields in a single integer variable - that includes foreground/background colors, style modifiers (bold, italic, underline, inverse and blink.

  Style codes
Name | Function
YAS_ITALIC | italic
YAS_UNDERL | underline
YAS_STRIKE | stikeout
YAS_INVERSE | inverse
YAS_BOLD | bold
YAS_BLINK | blink

  Color codes
Name | Color
YAS_BLACK | black
YAS_RED | red
YAS_GREEN | green
YAS_YELLOW | yellow
YAS_BLUE | blue
YAS_MAGENTA | magenta
YAS_CYAN | cyan
YAS_WHITE | white
YAS_FGCOLORDEF | default terminal foreground
YAS_BGCOLORDEF | default terminal background

  Helper macros
Name | Description
YAS_FG(attribute) | extract foreground color
YAS_BG(attribute) | extract background color
YAS_FGCOLOR(color) | shift simple color value into foreground color
YAS_BGCOLOR(color) | shift simple color value into background color
YAS_FGXCOLOR(color) | shift 256 palette color value into foreground color
YAS_BGXCOLOR(color) | shift 256 palette color value into background color

All of the above can be or'ed into attribute, provided that the bits for foreground/background color are all zeroes.

  Key codes

    •   Special, generated internally

Previous versions of the library used -1 and 0x100+ for these codes. In order to achieve unicode wide character compatibility and simpler API, the reserved Unicode range 0xf0000-0xffffd is used for the special codes both in narrow and wide character input modes.

There is a macro YAS_IS_CC(code) that will evaluate to non-zero for the special codes and to zero for normal characters. Note that all ASCII control characters in the range 0x00-0x7f are treated as normal ones.
Name | Value | Description
YAS_K_NONE | 0xf0000 | no key is available; in time limited mode means that the time limit expired
YAS_SCREEN_SIZE | 0xf0701 | notification for screen size change (may come because of telnet or ANSI sequence)
YAS_TELNET_SIZE | 0xf0702 | notification for a possible screen size change, reported via telnet without valid size data; the size should be redetected (e.g. with yascreen_reqsize)

    •   Normal keys
Name | Value | Description
YAS_K_NUL | 0x00 | Nul; on some terminals Ctrl-2
YAS_K_C_A | 0x01 | Ctrl-A
YAS_K_C_B | 0x02 | Ctrl-B
YAS_K_C_C | 0x03 | Ctrl-C
YAS_K_C_D | 0x04 | Ctrl-D
YAS_K_C_E | 0x05 | Ctrl-E
YAS_K_C_F | 0x06 | Ctrl-F
YAS_K_C_G | 0x07 | Ctrl-G
YAS_K_C_H | 0x08 | Ctrl-H; depends on terminal see YAS-K-BSP and YAS-K-C-8
YAS_K_C_I | 0x09 | Ctrl-I
YAS_K_TAB | 0x09 | Tab
YAS_K_C_J | 0x0a | Ctrl-J
YAS_K_C_K | 0x0b | Ctrl-K
YAS_K_C_L | 0x0c | Ctrl-L
YAS_K_C_M | 0x0d | Enter, Return, Ctrl-M; see below
YAS_K_RET | 0x0d | Enter, Return, Ctrl-M; see above
YAS_K_C_N | 0x0e | Ctrl-N
YAS_K_C_O | 0x0f | Ctrl-O
YAS_K_C_P | 0x10 | Ctrl-P
YAS_K_C_Q | 0x11 | Ctrl-Q
YAS_K_C_R | 0x12 | Ctrl-R
YAS_K_C_S | 0x13 | Ctrl-S
YAS_K_C_T | 0x14 | Ctrl-T
YAS_K_C_U | 0x15 | Ctrl-U
YAS_K_C_V | 0x16 | Ctrl-V
YAS_K_C_W | 0x17 | Ctrl-W
YAS_K_C_X | 0x18 | Ctrl-X
YAS_K_C_Y | 0x19 | Ctrl-Y
YAS_K_C_Z | 0x1a | Ctrl-Z
YAS_K_ESC | 0x1b | Esc, Ctrl-3; see below; All ANSI sequences start with Esc, this is returned after a timeout or double Esc
YAS_K_C_3 | 0x1b | Esc, Ctrl-3; see above; All ANSI sequences start with Esc, this is returned after a timeout or double Esc
YAS_K_C_4 | 0x1c | Ctrl-4
YAS_K_C_5 | 0x1d | Ctrl-5
YAS_K_C_6 | 0x1e | Ctrl-6
YAS_K_C_7 | 0x1f | Ctrl-7
YAS_K_SPACE | 0x20 | Space
YAS_K_EXCL | 0x21 | !
YAS_K_DQUOT | 0x22 | "
YAS_K_HASH | 0x23 | #
YAS_K_POUND | 0x24 | $
YAS_K_PERC | 0x25 | %
YAS_K_AND | 0x26 | Ampersand
YAS_K_QUOT | 0x27 | '
YAS_K_OBRA | 0x28 | (
YAS_K_CBRA | 0x29 | )
YAS_K_STAR | 0x2a | *
YAS_K_PLUS | 0x2b | +
YAS_K_COMMA | 0x2c | ,
YAS_K_MINUS | 0x2d | -
YAS_K_DOT | 0x2e | .
YAS_K_SLASH | 0x2f | /
YAS_K_0 | 0x30 | 0
YAS_K_1 | 0x31 | 1
YAS_K_2 | 0x32 | 2
YAS_K_3 | 0x33 | 3
YAS_K_4 | 0x34 | 4
YAS_K_5 | 0x35 | 5
YAS_K_6 | 0x36 | 6
YAS_K_7 | 0x37 | 7
YAS_K_8 | 0x38 | 8
YAS_K_9 | 0x39 | 9
YAS_K_COLON | 0x3a | :
YAS_K_SEMI | 0x3b | ;
YAS_K_LT | 0x3c | <
YAS_K_EQ | 0x3d | Equal
YAS_K_GT | 0x3e | >
YAS_K_QUEST | 0x3f | ?
YAS_K_AT | 0x40 | @
YAS_K_A | 0x41 | A
YAS_K_B | 0x42 | B
YAS_K_C | 0x43 | C
YAS_K_D | 0x44 | D
YAS_K_E | 0x45 | E
YAS_K_F | 0x46 | F
YAS_K_G | 0x47 | G
YAS_K_H | 0x48 | H
YAS_K_I | 0x49 | I
YAS_K_J | 0x4a | J
YAS_K_K | 0x4b | K
YAS_K_L | 0x4c | L
YAS_K_M | 0x4d | M
YAS_K_N | 0x4e | N
YAS_K_O | 0x4f | O
YAS_K_P | 0x50 | P
YAS_K_Q | 0x51 | Q
YAS_K_R | 0x52 | R
YAS_K_S | 0x53 | S
YAS_K_T | 0x54 | T
YAS_K_U | 0x55 | U
YAS_K_V | 0x56 | V
YAS_K_W | 0x57 | W
YAS_K_X | 0x58 | X
YAS_K_Y | 0x59 | Y
YAS_K_Z | 0x5a | Z
YAS_K_OSQ | 0x5b | OpenSquareBracket
YAS_K_BSLASH | 0x5c | Backslash
YAS_K_CSQ | 0x5d | CloseSquareBracket
YAS_K_CARRET | 0x5e | ^
YAS_K_USCORE | 0x5f | Underscore
YAS_K_BTICK | 0x60 | Backtick
YAS_K_a | 0x61 | a
YAS_K_b | 0x62 | b
YAS_K_c | 0x63 | c
YAS_K_d | 0x64 | d
YAS_K_e | 0x65 | e
YAS_K_f | 0x66 | f
YAS_K_g | 0x67 | g
YAS_K_h | 0x68 | h
YAS_K_i | 0x69 | i
YAS_K_j | 0x6a | j
YAS_K_k | 0x6b | k
YAS_K_l | 0x6c | l
YAS_K_m | 0x6d | m
YAS_K_n | 0x6e | n
YAS_K_o | 0x6f | o
YAS_K_p | 0x70 | p
YAS_K_q | 0x71 | q
YAS_K_r | 0x72 | r
YAS_K_s | 0x73 | s
YAS_K_t | 0x74 | t
YAS_K_u | 0x75 | u
YAS_K_v | 0x76 | v
YAS_K_w | 0x77 | w
YAS_K_x | 0x78 | x
YAS_K_y | 0x79 | y
YAS_K_z | 0x7a | z
YAS_K_OCUR | 0x7b | {
YAS_K_PIPE | 0x7c | Pipe
YAS_K_CCUR | 0x7d | }
YAS_K_TLD | 0x7e | Tilde
YAS_K_C_8 | 0x7f | Backspace; see below; depends on terminal see YAS-K-C-H
YAS_K_BSP | 0x7f | Backspace; see below; depends on terminal see YAS-K-C-H

    •   Extended keys, parsed from ANSI sequences
Name | Value | Description
YAS_K_F1 | 0xf0001 | F1
YAS_K_F2 | 0xf0002 | F2
YAS_K_F3 | 0xf0003 | F3
YAS_K_F4 | 0xf0004 | F4
YAS_K_F5 | 0xf0005 | F5
YAS_K_F6 | 0xf0006 | F6
YAS_K_F7 | 0xf0007 | F7
YAS_K_F8 | 0xf0008 | F8
YAS_K_F9 | 0xf0009 | F9
YAS_K_F10 | 0xf000a | F10
YAS_K_F11 | 0xf000b | F11
YAS_K_F12 | 0xf000c | F12
YAS_K_S_F1 | 0xf000d | Shift-F1
YAS_K_S_F2 | 0xf000e | Shift-F2
YAS_K_S_F3 | 0xf000f | Shift-F3
YAS_K_S_F4 | 0xf0010 | Shift-F4
YAS_K_S_F5 | 0xf0011 | Shift-F5
YAS_K_S_F6 | 0xf0012 | Shift-F6
YAS_K_S_F7 | 0xf0013 | Shift-F7
YAS_K_S_F8 | 0xf0014 | Shift-F8
YAS_K_S_F9 | 0xf0015 | Shift-F9
YAS_K_S_F10 | 0xf0016 | Shift-F10
YAS_K_S_F11 | 0xf0017 | Shift-F11
YAS_K_S_F12 | 0xf0018 | Shift-F12
YAS_K_C_F1 | 0xf0019 | Ctrl-F1
YAS_K_C_F2 | 0xf001a | Ctrl-F2
YAS_K_C_F3 | 0xf001b | Ctrl-F3
YAS_K_C_F4 | 0xf001c | Ctrl-F4
YAS_K_C_F5 | 0xf001d | Ctrl-F5
YAS_K_C_F6 | 0xf001e | Ctrl-F6
YAS_K_C_F7 | 0xf001f | Ctrl-F7
YAS_K_C_F8 | 0xf0020 | Ctrl-F8
YAS_K_C_F9 | 0xf0021 | Ctrl-F9
YAS_K_C_F10 | 0xf0022 | Ctrl-F10
YAS_K_C_F11 | 0xf0023 | Ctrl-F11
YAS_K_C_F12 | 0xf0024 | Ctrl-F12
YAS_K_A_F1 | 0xf0025 | Alt-F1
YAS_K_A_F2 | 0xf0026 | Alt-F2
YAS_K_A_F3 | 0xf0027 | Alt-F3
YAS_K_A_F4 | 0xf0028 | Alt-F4
YAS_K_A_F5 | 0xf0029 | Alt-F5
YAS_K_A_F6 | 0xf002a | Alt-F6
YAS_K_A_F7 | 0xf002b | Alt-F7
YAS_K_A_F8 | 0xf002c | Alt-F8
YAS_K_A_F9 | 0xf002d | Alt-F9
YAS_K_A_F10 | 0xf002e | Alt-F10
YAS_K_A_F11 | 0xf002f | Alt-F11
YAS_K_A_F12 | 0xf0030 | Alt-F12
YAS_K_LEFT | 0xf0031 | Left
YAS_K_UP | 0xf0032 | Up
YAS_K_DOWN | 0xf0033 | Down
YAS_K_RIGHT | 0xf0034 | Right
YAS_K_HOME | 0xf0035 | Home
YAS_K_END | 0xf0036 | End
YAS_K_PGUP | 0xf0037 | PageUp
YAS_K_PGDN | 0xf0038 | PageDown
YAS_K_INS | 0xf0039 | Insert
YAS_K_DEL | 0xf003a | Delete
YAS_K_C_LEFT | 0xf003b | Ctrl-Left
YAS_K_C_UP | 0xf003c | Ctrl-Up
YAS_K_C_DOWN | 0xf003d | Ctrl-Down
YAS_K_C_RIGHT | 0xf003e | Ctrl-Right
YAS_K_S_LEFT | 0xf003f | Shift-Left
YAS_K_S_UP | 0xf0040 | Shift-Up
YAS_K_S_DOWN | 0xf0041 | Shift-Down
YAS_K_S_RIGHT | 0xf0042 | Shift-Right
YAS_K_A_LEFT | 0xf0043 | Alt-Left
YAS_K_A_UP | 0xf0044 | Alt-Up
YAS_K_A_DOWN | 0xf0045 | Alt-Down
YAS_K_A_RIGHT | 0xf0046 | Alt-Right
YAS_K_S_TAB | 0xf0047 | Shift-Tab (Backtab)
YAS_K_C_HOME | 0xf0048 | Ctrl-Home
YAS_K_C_END | 0xf0049 | Ctrl-End
YAS_K_C_INS | 0xf004a | Ctrl-Insert
YAS_K_C_DEL | 0xf004b | Ctrl-Delete
YAS_K_C_PGUP | 0xf004c | Ctrl-PageUp
YAS_K_C_PGDN | 0xf004d | Ctrl-PageDown
YAS_K_S_HOME | 0xf004e | Shift-Home
YAS_K_S_END | 0xf004f | Shift-End
YAS_K_S_INS | 0xf0050 | Shift-Insert
YAS_K_S_DEL | 0xf0051 | Shift-Delete
YAS_K_S_PGUP | 0xf0052 | Shift-PageUp
YAS_K_S_PGDN | 0xf0053 | Shift-PageDown
YAS_K_A_HOME | 0xf0054 | Alt-Home
YAS_K_A_END | 0xf0055 | Alt-End
YAS_K_A_INS | 0xf0056 | Alt-Insert
YAS_K_A_DEL | 0xf0057 | Alt-Delete
YAS_K_A_PGUP | 0xf0058 | Alt-PageUp
YAS_K_A_PGDN | 0xf0059 | Alt-PageDown
YAS_K_KP5 | 0xf005a | Keypad 5 with NumLock off

F13-F20 (sent by the Linux console and some other terminals for Shift-F1 to Shift-F8) are reported as YAS_K_S_F1 to YAS_K_S_F8.

    •   Alt-<letter>

These codes are generated by a helper macro - YAS_K_ALT(keycode).
Name | Description
YAS_K_A_BT | Alt-Backtick
YAS_K_A_1 | Alt-1
YAS_K_A_2 | Alt-2
YAS_K_A_3 | Alt-3
YAS_K_A_4 | Alt-4
YAS_K_A_5 | Alt-5
YAS_K_A_6 | Alt-6
YAS_K_A_7 | Alt-7
YAS_K_A_8 | Alt-8
YAS_K_A_9 | Alt-9
YAS_K_A_0 | Alt-0
YAS_K_A_MINUS | Alt-Minus
YAS_K_A_EQ | Alt-=
YAS_K_A_BSP | Alt-Backspace
YAS_K_A_C_H | Alt-Backspace on terminals where Backspace sends ^H
YAS_K_A_TAB | Alt-Tab (if not used by the window manager)
YAS_K_A_RET | Alt-Enter
YAS_K_A_SPACE | Alt-Space
YAS_K_A_TLD | Alt-Tilde
YAS_K_A_EXCL | Alt-!
YAS_K_A_AT | Alt-@
YAS_K_A_HASH | Alt-#
YAS_K_A_POUND | Alt-$
YAS_K_A_PERC | Alt-%
YAS_K_A_CARRET | Alt-^
YAS_K_A_AND | Alt-Ampersand
YAS_K_A_STAR | Alt-Star
YAS_K_A_OBRA | Alt-(
YAS_K_A_CBRA | Alt-)
YAS_K_A_UND | Alt-_
YAS_K_A_PLUS | Alt-+
YAS_K_A_a | Alt-a
YAS_K_A_b | Alt-b
YAS_K_A_c | Alt-c
YAS_K_A_d | Alt-d
YAS_K_A_e | Alt-e
YAS_K_A_f | Alt-f
YAS_K_A_g | Alt-g
YAS_K_A_h | Alt-h
YAS_K_A_i | Alt-i
YAS_K_A_j | Alt-j
YAS_K_A_k | Alt-k
YAS_K_A_l | Alt-l
YAS_K_A_m | Alt-m
YAS_K_A_n | Alt-n
YAS_K_A_o | Alt-o
YAS_K_A_p | Alt-p
YAS_K_A_q | Alt-q
YAS_K_A_r | Alt-r
YAS_K_A_s | Alt-s
YAS_K_A_t | Alt-t
YAS_K_A_u | Alt-u
YAS_K_A_v | Alt-v
YAS_K_A_w | Alt-w
YAS_K_A_x | Alt-x
YAS_K_A_y | Alt-y
YAS_K_A_z | Alt-z
YAS_K_A_A | Alt-Shift-a
YAS_K_A_B | Alt-Shift-b
YAS_K_A_C | Alt-Shift-c
YAS_K_A_D | Alt-Shift-d
YAS_K_A_E | Alt-Shift-e
YAS_K_A_F | Alt-Shift-f
YAS_K_A_G | Alt-Shift-g
YAS_K_A_H | Alt-Shift-h
YAS_K_A_I | Alt-Shift-i
YAS_K_A_J | Alt-Shift-j
YAS_K_A_K | Alt-Shift-k
YAS_K_A_L | Alt-Shift-l
YAS_K_A_M | Alt-Shift-m
YAS_K_A_N | Alt-Shift-n
YAS_K_A_O | Alt-Shift-o; defined for completeness but cannot be received, because \eO is a key sequence prefix
YAS_K_A_P | Alt-Shift-p
YAS_K_A_Q | Alt-Shift-q
YAS_K_A_R | Alt-Shift-r
YAS_K_A_S | Alt-Shift-s
YAS_K_A_T | Alt-Shift-t
YAS_K_A_U | Alt-Shift-u
YAS_K_A_V | Alt-Shift-v
YAS_K_A_W | Alt-Shift-w
YAS_K_A_X | Alt-Shift-x
YAS_K_A_Y | Alt-Shift-y
YAS_K_A_Z | Alt-Shift-z

Functions

All functions in the API work with a pointer to an opaque yascreen structure.

The structure is allocated internally in the library by yascreen_init and it is the job of the user program to keep track of it.

The library is thread safe, as long as each struct yascreen object is accessed by a single thread.

  yascreen_init
    inline yascreen *yascreen_init(int sx,int sy);

allocate and initialize screen data

output defaults to stdout

in case output is a terminal and initial size is (0,0), the screen size is autodetected in case the autodetection fails or returns 0x0, it will default to 80x24

in case of error, returns NULL

  yascreen_ver
    inline const char *yascreen_ver(void);

returns a string with the library version

  yascreen_setout
    inline int yascreen_setout(yascreen *s,ssize_t (*out)(yascreen *s,const void *data,size_t len));

set callback that handles output

if out=NULL, the output goes to stdout

the callback may implement internal buffering, a flush is signalled by calling out with len=0

  yascreen_set_unicode
    inline void yascreen_set_unicode(yascreen *s,int on);

enable (on is non-zero) or disable (on=0) unicode input processing

by default unicode mode is on

changing the unicode input processing will flush all pending input

  yascreen_set_telnet
    inline void yascreen_set_telnet(yascreen *s,int on);

enable (on is non-zero) or disable (on=0) telnet sequence processing

by default telnet mode is off

  yascreen_init_telnet
    inline void yascreen_init_telnet(yascreen *s);

depending on telnet sequence processing, sends a set of telnet initialization sequences

  yascreen_resize
    inline int yascreen_resize(yascreen *s,int sx,int sy);

resize screen

should redraw afterwards

since allocation is involved, this may fail and return -1

  yascreen_free
    inline void yascreen_free(yascreen *s);

finish the lifecycle of struct yascreen - all internally allocated memory is freed

  yascreen_term_save
    inline void yascreen_term_save(yascreen *s);

save current terminal state on top of state stack

  yascreen_term_restore
    inline void yascreen_term_restore(yascreen *s);

restore previously saved terminal state from top of state stack

  yascreen_term_push
    inline void yascreen_term_push(yascreen *s);

push current terminal state to state stack

  yascreen_term_pop
    inline void yascreen_term_pop(yascreen *s);

pop and restore previously saved terminal state from state stack

  yascreen_term_set
    inline void yascreen_term_set(yascreen *s,int mode);

set terminal for proper screen operation

  mode is a bitmask, containing one of
Name | Value | Description
YAS_NOBUFF | 1 | turn off canonical mode (disable ICANON and IEXTEN)
YAS_NOSIGN | 2 | disable ISIG
YAS_NOECHO | 4 | disable local echo (ECHO)
YAS_ONLCR | 8 | ONLCR or OPOST

  yascreen_printxy
    inline int yascreen_printxy(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));

  yascreen_putsxy
    inline int yascreen_putsxy(yascreen *s,int x,int y,uint32_t attr,const char *str);

print at position, if data exceeds buffer, then it gets truncated

  yascreen_printxyu
    inline int yascreen_printxyu(yascreen *s,int x,int y,uint32_t attr,const char *format,...) __attribute__((format(printf,5,6)));

  yascreen_putsxyu
    inline int yascreen_putsxyu(yascreen *s,int x,int y,uint32_t attr,const char *str);

print at position, if data exceeds buffer, then it gets truncated

screen is immediately updated

  yascreen_update
    inline int yascreen_update(yascreen *s);

sync memory state to screen

since allocation is involved, this may fail and return -1

  yascreen_redraw
    inline void yascreen_redraw(yascreen *s);

set next update to be a full redraw

  yascreen_clear_mem
    inline void yascreen_clear_mem(yascreen *s,uint32_t attr);

clear memory buffer

all cells in the screen are set to Space, using attr for colors and style

  yascreen_cursor
    inline void yascreen_cursor(yascreen *s,int on);

hide (on=0) or show (on is non-zero) cusror

screen is updated immediately

  yascreen_cursor_xy
    inline void yascreen_cursor_xy(yascreen *s,int x,int y);

set cursor position

screen is updated immediately

  yascreen_altbuf
    inline void yascreen_altbuf(yascreen *s,int on);

switch between regular and alternative buffer

screen is updated immediately

  yascreen_clear
    inline void yascreen_clear(yascreen *s);

clear real screen, no change to memory buffers

  yascreen_clearln
    inline void yascreen_clearln(yascreen *s);

clear current line, no change to memory buffers

  yascreen_update_attr
    inline void yascreen_update_attr(yascreen *s,uint32_t oattr,uint32_t nattr);

apply difference between two attrs and output the optimized ANSI sequence to switch from oattr to nattr

if oattr=0xffffffff, the full ANSI sequence will be generated

no change to memory buffers

  yascreen_set_attr
    yascreen_set_attr(s,attr)

reset all attrs and set specific one (attr)

  yascreen_print
    inline int yascreen_print(yascreen *s,const char *format,...) __attribute__((format(printf,2,3)));

  yascreen_write
    inline int yascreen_write(yascreen *s,const char *str,int len);

  yascreen_puts
    inline int yascreen_puts(yascreen *s,const char *str);

  yascreen_clearln_s
    inline const char *yascreen_clearln_s(yascreen *s);

print in line mode

  yascreen_sx
    inline int yascreen_sx(yascreen *s);

get current x size

  yascreen_sy
    inline int yascreen_sy(yascreen *s);

get current y size

  yascreen_x
    inline int yascreen_x(yascreen *s);

get current x

  yascreen_y
    inline int yascreen_y(yascreen *s);

get current y

  yascreen_esc_to
    inline void yascreen_esc_to(yascreen *s,int timeout);

set timeout for single ESC key press

  yascreen_ckto
    inline void yascreen_ckto(yascreen *s);

in case of external event loop, this call will check for single ESC key

should be called regularly enough so that the above specified timeout is not extended too much

if not called often enough then single ESC will be yielded after longer timeout

if not called at all then single ESC will be yielded with next key press

  yascreen_willto
    inline uint64_t yascreen_willto(yascreen *s);

single ESC key and a timeout afterwards is quite the rare event

help the application to optimize its event loop by not constantly polling yascreen_ckto

yascreen_willto tells if there is a pending timeout and when

returns 0 if there is no pending timeout or the remaining time in milliseconds

  yascreen_getch_to
    inline int yascreen_getch_to(yascreen *s,int timeout);

wait for a key, return ASCII or extended keycode, wait no more than timeout in milliseconds

  yascreen_getch
    yascreen_getch(s)

get a key without timeout

this macro expands to yascreen_getch_to(s,0)

zero timeout=wait forever

  yascreen_getch_nowait
    yascreen_getch_nowait(s)

get a key, if available, return immediately

this macro expands to yascreen_getch_to(s,-1)

negative timeout=do not wait

  yascreen_ungetch
    inline void yascreen_ungetch(yascreen *s,int key);

put back key value in key buffer

the internal key buffer is dynamically allocated, hence there is no limit of how many key codes may be put back, but in case of memory allocation failure, the error will not be reported and the key will not be put into the buffer

  yascreen_pushch
    inline void yascreen_pushch(yascreen *s,int key);

push key value at end of key buffer

similar to yascreen_ungetch but the key code will be returned after all other key codes currently in the buffer

the internal key buffer is dynamically allocated, hence there is no limit of how many key codes may be put back, but in case of memory allocation failure, the error will not be reported and the key will not be put into the buffer

  yascreen_feed
    inline void yascreen_feed(yascreen *s,unsigned char c);

feed key sequence state machine with byte stream

this is useful to implement external event loop and read key codes by yascreen_getch_nowait until it returns YAS_K_NONE

  yascreen_peekch
    inline int yascreen_peekch(yascreen *s);

peek for key without removing it from input queue

  yascreen_getsize
    inline void yascreen_getsize(yascreen *s,int *sx,int *sy);

get last reported screen size

set both to 0 if there is none

this will yield valid result after YAS_SCREEN_SIZE is returned as keypress

  yascreen_reqsize
    inline void yascreen_reqsize(yascreen *s);

request terminal to report its size via ANSI sequence

  yascreen_set_hint_i
    inline void yascreen_set_hint_i(yascreen *s,int hint);

  yascreen_get_hint_i
    inline int yascreen_get_hint_i(yascreen *s);

  yascreen_set_hint_p
    inline void yascreen_set_hint_p(yascreen *s,void *hint);

  yascreen_get_hint_p
    inline void *yascreen_get_hint_p(yascreen *s);

get/set opaque hint values

integer and pointer hints are stored separately and both can be used at the same time

these are useful to link the yascreen instance to user program data

for example a single output callback may output to socket or a terminal, depending on the hint values

  yascreen_line_flush
    inline void yascreen_line_flush(yascreen *s,int on);

enable/disable auto flush for line and direct screen oriented operations

yascreen versions before 1.77 didn't use buffered output and would immediately send the output to the screen

disabling internal flush can help an application optimize the number of write calls at the cost of performing explicit flush after each group of operations

explicit flush example:
    yascreen_write(s,"",0);

  yascreen_getwch_to
    inline wchar_t yascreen_getwch_to(yascreen *s,int timeout);

wait for a key, return wide character or extended keycode, wait no more than timeout in milliseconds

yascreen_getwch_to does not work in non-unicode mode and will always return YAS_K_NONE

mixing the utf8 and wide character input modes will break on multibyte utf8 sequences and is not supported

  yascreen_getwch
    yascreen_getwch(s)

get a key as wide character without timeout

this macro expands to yascreen_getwch_to(s,0)

zero timeout=wait forever

yascreen_getwch does not work in non-unicode mode and will always return YAS_K_NONE

  yascreen_getwch_nowait
    yascreen_getwch_nowait(s)

get a key as a wide character, if available, return immediately

this macro expands to yascreen_getwch_to(s,-1)

negative timeout=do not wait

yascreen_getwch_nowait does not work in non-unicode mode and will always return YAS_K_NONE

  yascreen_ungetwch
    inline void yascreen_ungetwch(yascreen *s,wchar_t key);

put back wide character key value in key buffer

the internal key buffer is dynamically allocated, hence there is no limit of how many key codes may be put back, but in case of memory allocation failure, the error will not be reported and the key will not be put into the buffer

the internal key buffer contains utf8 and the wide character will be expanded to the appropriate utf8 sequence

yascreen_ungetwch does not do anything in non-unicode mode

  yascreen_peekwch
    inline wchar_t yascreen_peekwch(yascreen *s);

peek for key without removing it from input queue

yascreen_peekwch does not work in non-unicode mode and will always return YAS_K_NONE