yascreen - Man Page

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

Synopsis

#include <yascreen.h>

Description

Main features

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.

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))!=-1) {
		// handle processed keys
	}

	…
	// option 2

	// input is handled by yascreen and key or -1 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))!=-1) {
		// 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))!=-1) {
		// 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))!=-1) {
		// 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

NameFunction
YAS_ITALICitalic
YAS_UNDERLunderline
YAS_STRIKEstikeout
YAS_INVERSEinverse
YAS_BOLDbold
YAS_BLINKblink

Color codes

NameColor
YAS_BLACKblack
YAS_REDred
YAS_GREENgreen
YAS_YELLOWyellow
YAS_BLUEblue
YAS_MAGENTAmagenta
YAS_CYANcyan
YAS_WHITEwhite
YAS_FGCOLORDEFdefault terminal foreground
YAS_BGCOLORDEFdefault terminal background

Helper macros

NameDescription
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

NameValueDescription
YAS_K_NONE-1no key is available; in time limited mode means that the time limit expired
YAS_SCREEN_SIZE0x800notification for screen size change (may come because of telnet or ANSI sequence)
YAS_TELNET_SIZE0x801notification for screen size change; duplicates the above, may be used to differentiate how screen size change event was generated
NameValueDescription
YAS_K_NUL0x00Nul; on some terminals Ctrl-2
YAS_K_C_A0x01Ctrl-A
YAS_K_C_B0x02Ctrl-B
YAS_K_C_C0x03Ctrl-C
YAS_K_C_D0x04Ctrl-D
YAS_K_C_E0x05Ctrl-E
YAS_K_C_F0x06Ctrl-F
YAS_K_C_G0x07Ctrl-G
YAS_K_C_H0x08Ctrl-H; depends on terminal see YAS_K_BSP, YAS_K_C_8
YAS_K_C_I0x09Ctrl-I
YAS_K_TAB0x09Tab
YAS_K_C_J0x0aCtrl-J
YAS_K_C_K0x0bCtrl-K
YAS_K_C_L0x0cCtrl-L
YAS_K_C_M0x0dEnter, Return, Ctrl-M; see below
YAS_K_RET0x0dEnter, Return, Ctrl-M; see above
YAS_K_C_N0x0eCtrl-N
YAS_K_C_O0x0fCtrl-O
YAS_K_C_P0x10Ctrl-O
YAS_K_C_Q0x11Ctrl-Q
YAS_K_C_R0x12Ctrl-R
YAS_K_C_S0x13Ctrl-S
YAS_K_C_T0x14Ctrl-T
YAS_K_C_U0x15Ctrl-U
YAS_K_C_V0x16Ctrl-V
YAS_K_C_W0x17Ctrl-W
YAS_K_C_X0x18Ctrl-X
YAS_K_C_Y0x19Ctrl-Y
YAS_K_C_Z0x1aCtrl-Z
YAS_K_ESC0x1bEsc, Ctrl-3; see below; All ANSI sequences start with Esc, this is return after a timeout or double Esc
YAS_K_C_30x1bEsc, Ctrl-3; see above; All ANSI sequences start with Esc, this is return after a timeout or double Esc
YAS_K_C_40x1cCtrl-4
YAS_K_C_50x1dCtrl-5
YAS_K_C_60x1eCtrl-6
YAS_K_C_70x1fCtrl-7
YAS_K_SPACE0x20Space
YAS_K_EXCL0x21!
YAS_K_DQUOT0x22"
YAS_K_HASH0x23#
YAS_K_POUND0x24$
YAS_K_PERC0x25%
YAS_K_AND0x26Ampersand
YAS_K_QUOT0x27'
YAS_K_OBRA0x28(
YAS_K_CBRA0x29)
YAS_K_STAR0x2a*
YAS_K_PLUS0x2b+
YAS_K_COMMA0x2c,
YAS_K_MINUS0x2d-
YAS_K_DOT0x2e.
YAS_K_SLASH0x2f/
YAS_K_00x300
YAS_K_10x311
YAS_K_20x322
YAS_K_30x333
YAS_K_40x344
YAS_K_50x355
YAS_K_60x366
YAS_K_70x377
YAS_K_80x388
YAS_K_90x399
YAS_K_COLON0x3a:
YAS_K_SEMI0x3b;
YAS_K_LT0x3c<
YAS_K_EQ0x3d=
YAS_K_GT0x3e>
YAS_K_QUEST0x3f?
YAS_K_AT0x40@
YAS_K_A0x41A
YAS_K_B0x42B
YAS_K_C0x43C
YAS_K_D0x44D
YAS_K_E0x45E
YAS_K_F0x46F
YAS_K_G0x47G
YAS_K_H0x48H
YAS_K_I0x49I
YAS_K_J0x4aJ
YAS_K_K0x4bK
YAS_K_L0x4cL
YAS_K_M0x4dM
YAS_K_N0x4eN
YAS_K_O0x4fO
YAS_K_P0x50P
YAS_K_Q0x51Q
YAS_K_R0x52R
YAS_K_S0x53S
YAS_K_T0x54T
YAS_K_U0x55U
YAS_K_V0x56V
YAS_K_W0x57W
YAS_K_X0x58X
YAS_K_Y0x59Y
YAS_K_Z0x5aZ
YAS_K_OSQ0x5b[
YAS_K_BSLASH0x5c\
YAS_K_CSQ0x5d]
YAS_K_CARRET0x5e^
YAS_K_USCORE0x5f_
YAS_K_BTICK0x60`
YAS_K_a0x61a
YAS_K_b0x62b
YAS_K_c0x63c
YAS_K_d0x64d
YAS_K_e0x65e
YAS_K_f0x66f
YAS_K_g0x67g
YAS_K_h0x68h
YAS_K_i0x69i
YAS_K_j0x6aj
YAS_K_k0x6bk
YAS_K_l0x6cl
YAS_K_m0x6dm
YAS_K_n0x6en
YAS_K_o0x6fo
YAS_K_p0x70p
YAS_K_q0x71q
YAS_K_r0x72r
YAS_K_s0x73s
YAS_K_t0x74t
YAS_K_u0x75u
YAS_K_v0x76v
YAS_K_w0x77w
YAS_K_x0x78x
YAS_K_y0x79y
YAS_K_z0x7az
YAS_K_OCUR0x7b{
YAS_K_PIPE0x7c|
YAS_K_CCUR0x7d}
YAS_K_TLD0x7eTilde
YAS_K_C_80x7fBackspace; see below; depends on terminal see YAS_K_C_H
YAS_K_BSP0x7fBackspace; see below; depends on terminal see YAS_K_C_H
NameValueDescription
YAS_K_F10x100F1
YAS_K_F20x101F2
YAS_K_F30x102F3
YAS_K_F40x103F4
YAS_K_F50x104F5
YAS_K_F60x105F6
YAS_K_F70x106F7
YAS_K_F80x107F8
YAS_K_F90x108F9
YAS_K_F100x109F10
YAS_K_F110x10aF11
YAS_K_F120x10bF12
YAS_K_S_F10x10cShift-F1
YAS_K_S_F20x10dShift-F2
YAS_K_S_F30x10eShift-F3
YAS_K_S_F40x10fShift-F4
YAS_K_S_F50x110Shift-F5
YAS_K_S_F60x111Shift-F6
YAS_K_S_F70x112Shift-F7
YAS_K_S_F80x113Shift-F8
YAS_K_S_F90x114Shift-F9
YAS_K_S_F100x115Shift-F10
YAS_K_S_F110x116Shift-F11
YAS_K_S_F120x117Shift-F12
YAS_K_C_F10x118Ctrl-F1
YAS_K_C_F20x119Ctrl-F2
YAS_K_C_F30x11aCtrl-F3
YAS_K_C_F40x11bCtrl-F4
YAS_K_C_F50x11cCtrl-F5
YAS_K_C_F60x11dCtrl-F6
YAS_K_C_F70x11eCtrl-F7
YAS_K_C_F80x11fCtrl-F8
YAS_K_C_F90x120Ctrl-F9
YAS_K_C_F100x121Ctrl-F10
YAS_K_C_F110x122Ctrl-F11
YAS_K_C_F120x123Ctrl-F12
YAS_K_A_F10x124Alt-F1
YAS_K_A_F20x125Alt-F2
YAS_K_A_F30x126Alt-F3
YAS_K_A_F40x127Alt-F4
YAS_K_A_F50x128Alt-F5
YAS_K_A_F60x129Alt-F6
YAS_K_A_F70x12aAlt-F7
YAS_K_A_F80x12bAlt-F8
YAS_K_A_F90x12cAlt-F9
YAS_K_A_F100x12dAlt-F10
YAS_K_A_F110x12eAlt-F11
YAS_K_A_F120x12fAlt-F12
YAS_K_LEFT0x130Left
YAS_K_UP0x131Up
YAS_K_DOWN0x132Down
YAS_K_RIGHT0x133Right
YAS_K_HOME0x134Home
YAS_K_END0x135End
YAS_K_PGUP0x136PageUp
YAS_K_PGDN0x137PageDown
YAS_K_INS0x138Insert
YAS_K_DEL0x139Delete
YAS_K_C_LEFT0x13aCtrl-Left
YAS_K_C_UP0x13bCtrl-Up
YAS_K_C_DOWN0x13cCtrl-Down
YAS_K_C_RIGHT0x13dCtrl-Right

These codes are generated by a helper macro - YAS_K_ALT(keycode).

NameDescription
YAS_K_A_BTAlt-Backtick
YAS_K_A_1Alt-1
YAS_K_A_2Alt-2
YAS_K_A_3Alt-3
YAS_K_A_4Alt-4
YAS_K_A_5Alt-5
YAS_K_A_6Alt-6
YAS_K_A_7Alt-7
YAS_K_A_8Alt-8
YAS_K_A_9Alt-9
YAS_K_A_0Alt-0
YAS_K_A_MINUSAlt-Minus
YAS_K_A_EQAlt-=
YAS_K_A_BSPAlt-Backspace
YAS_K_A_TLDAlt-Tilde
YAS_K_A_EXCLAlt-!
YAS_K_A_ATAlt-@
YAS_K_A_HASHAlt-#
YAS_K_A_POUNDAlt-$
YAS_K_A_PERCAlt-%
YAS_K_A_CARRETAlt-^
YAS_K_A_ANDAlt-Ampersand
YAS_K_A_STARAlt-*
YAS_K_A_OBRAAlt-(
YAS_K_A_CBRAAlt-)
YAS_K_A_UNDAlt-_
YAS_K_A_PLUSAlt-+
YAS_K_A_aAlt-a
YAS_K_A_bAlt-b
YAS_K_A_cAlt-c
YAS_K_A_dAlt-d
YAS_K_A_eAlt-e
YAS_K_A_fAlt-f
YAS_K_A_gAlt-g
YAS_K_A_hAlt-h
YAS_K_A_iAlt-i
YAS_K_A_jAlt-j
YAS_K_A_kAlt-k
YAS_K_A_lAlt-l
YAS_K_A_mAlt-m
YAS_K_A_nAlt-n
YAS_K_A_oAlt-o
YAS_K_A_pAlt-p
YAS_K_A_qAlt-q
YAS_K_A_rAlt-r
YAS_K_A_sAlt-s
YAS_K_A_tAlt-t
YAS_K_A_uAlt-u
YAS_K_A_vAlt-v
YAS_K_A_wAlt-w
YAS_K_A_xAlt-x
YAS_K_A_yAlt-y
YAS_K_A_zAlt-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 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_telnet

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

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

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

NameValueDescription
YAS_NOBUFF1turn off canonical mode (disable ICANON and IEXTEN)
YAS_NOSIGN2disable ISIG
YAS_NOECHO4disable local echo (ECHO)
YAS_ONLCR8ONLCR|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_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 -1

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);

Info

September 30, 2020 User-Manual