.TH YASCREEN 3 "September 30, 2020" yascreen "User\-Manual"

.SH NAME
.PP
yascreen \- Yet Another Screen Library (curses replacement for daemons and embedded apps)


.SH SYNOPSIS
.PP
\fB\fC#include <yascreen.h>\fR


.SH DESCRIPTION
.SH Main features
.RS
.IP \(bu 2
small footprint
.IP \(bu 2
does not have external dependencies
.IP \(bu 2
allows both internal and external event loop
.IP \(bu 2
allows stdin/stdout or external input/output (can work over socket)
.IP \(bu 2
supports basic set of telnet sequences, making it suitable for built\-in terminal interfaces for daemons
.IP \(bu 2
supports a limited set of input keystroke sequences
.IP \(bu 2
fully unicode compatible (parts of this depend on wcwidth in libc)
.IP \(bu 2
supports utf8 verification of input
.IP \(bu 2
relies only on a limited subset of ansi/xterm ESC sequences, making it compatible with mostly all modern terminals (inspired by linenoise
\[la]https://github.com/antirez/linenoise\[ra])
.IP \(bu 2
there is no curses API and ancient terminal compatibility, hence less bloat
.IP \(bu 2
there is no autoconf \- there is no need to have one
.IP \(bu 2
clean API with opaque private data, usable from C/C++
.IP \(bu 2
easy cross compilation setup (by setting CC, AR, STRIP and RANLIB)

.RE

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

.PP
On *BSD a \fB\fCgmake\fR is required to build.

.SH Architecture
.PP
yascreen uses an opaque data structure, allocated by the library and dynamically resized when needed \- \fB\fCyascreen\_init(int sx, int sy)\fR / \fB\fCyascreen\_resize(yascreen *s, int sx, int sy)\fR\&. An application may specify (0,0) for both calls to let yascreen detect the size or use a fixed size.

.PP
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.

.PP
Modes of operation can be modified at runtime.

.PP
For terminal use signal handling (\fB\fCSIGWINCH\fR) should always be handled by the application.

.SH Example initialization for terminal and handling of SIGWINCH
.PP
.RS

.nf
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
	}
}

.fi
.RE

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

.PP
In multiprocess mode daemons where \fB\fCstdin\fR/\fB\fCstdout\fR 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.

.SH Example initialization for socket with external event loop and telnet sequences processing
.PP
.RS

.nf
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
	}
}


.fi
.RE


.SH API Reference
.SH Predefined constants and Helper macros
.PP
Internally style is kept into bitfields in a single integer variable \- that includes foreground/background colors, style modifiers (bold, italic, underline, inverse and blink.

.PP
\fBStyle codes\fP

.TS
allbox;
l l 
l l .
\fB\fCName\fR	\fB\fCFunction\fR
\fB\fCYAS\_ITALIC\fR	italic
\fB\fCYAS\_UNDERL\fR	underline
\fB\fCYAS\_STRIKE\fR	stikeout
\fB\fCYAS\_INVERSE\fR	inverse
\fB\fCYAS\_BOLD\fR	bold
\fB\fCYAS\_BLINK\fR	blink
.TE

.PP
\fBColor codes\fP

.TS
allbox;
l l 
l l .
\fB\fCName\fR	\fB\fCColor\fR
\fB\fCYAS\_BLACK\fR	black
\fB\fCYAS\_RED\fR	red
\fB\fCYAS\_GREEN\fR	green
\fB\fCYAS\_YELLOW\fR	yellow
\fB\fCYAS\_BLUE\fR	blue
\fB\fCYAS\_MAGENTA\fR	magenta
\fB\fCYAS\_CYAN\fR	cyan
\fB\fCYAS\_WHITE\fR	white
\fB\fCYAS\_FGCOLORDEF\fR	default terminal foreground
\fB\fCYAS\_BGCOLORDEF\fR	default terminal background
.TE

.PP
\fBHelper macros\fP

.TS
allbox;
l l 
l l .
\fB\fCName\fR	\fB\fCDescription\fR
\fB\fCYAS\_FG(attribute)\fR	extract foreground color
\fB\fCYAS\_BG(attribute)\fR	extract background color
\fB\fCYAS\_FGCOLOR(color)\fR	T{
shift simple color value into foreground color
T}
\fB\fCYAS\_BGCOLOR(color)\fR	T{
shift simple color value into background color
T}
\fB\fCYAS\_FGXCOLOR(color)\fR	T{
shift 256 palette color value into foreground color
T}
\fB\fCYAS\_BGXCOLOR(color)\fR	T{
shift 256 palette color value into background color
T}
.TE

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

.PP
\fBKey codes\fP

.RS
.IP \(bu 2
Special, generated internally

.RE

.TS
allbox;
l l l 
l l l .
\fB\fCName\fR	\fB\fCValue\fR	\fB\fCDescription\fR
\fB\fCYAS\_K\_NONE\fR	\-1	T{
no key is available; in time limited mode means that the time limit expired
T}
\fB\fCYAS\_SCREEN\_SIZE\fR	0x800	T{
notification for screen size change (may come because of telnet or ANSI sequence)
T}
\fB\fCYAS\_TELNET\_SIZE\fR	0x801	T{
notification for screen size change; duplicates the above, may be used to differentiate how screen size change event was generated
T}
.TE

.RS
.IP \(bu 2
Normal keys

.RE

.TS
allbox;
l l l 
l l l .
\fB\fCName\fR	\fB\fCValue\fR	\fB\fCDescription\fR
\fB\fCYAS\_K\_NUL\fR	0x00	Nul; on some terminals Ctrl\-2
\fB\fCYAS\_K\_C\_A\fR	0x01	Ctrl\-A
\fB\fCYAS\_K\_C\_B\fR	0x02	Ctrl\-B
\fB\fCYAS\_K\_C\_C\fR	0x03	Ctrl\-C
\fB\fCYAS\_K\_C\_D\fR	0x04	Ctrl\-D
\fB\fCYAS\_K\_C\_E\fR	0x05	Ctrl\-E
\fB\fCYAS\_K\_C\_F\fR	0x06	Ctrl\-F
\fB\fCYAS\_K\_C\_G\fR	0x07	Ctrl\-G
\fB\fCYAS\_K\_C\_H\fR	0x08	T{
Ctrl\-H; depends on terminal see \fB\fCYAS\_K\_BSP\fR, \fB\fCYAS\_K\_C\_8\fR
T}
\fB\fCYAS\_K\_C\_I\fR	0x09	Ctrl\-I
\fB\fCYAS\_K\_TAB\fR	0x09	Tab
\fB\fCYAS\_K\_C\_J\fR	0x0a	Ctrl\-J
\fB\fCYAS\_K\_C\_K\fR	0x0b	Ctrl\-K
\fB\fCYAS\_K\_C\_L\fR	0x0c	Ctrl\-L
\fB\fCYAS\_K\_C\_M\fR	0x0d	T{
Enter, Return, Ctrl\-M; see below
T}
\fB\fCYAS\_K\_RET\fR	0x0d	T{
Enter, Return, Ctrl\-M; see above
T}
\fB\fCYAS\_K\_C\_N\fR	0x0e	Ctrl\-N
\fB\fCYAS\_K\_C\_O\fR	0x0f	Ctrl\-O
\fB\fCYAS\_K\_C\_P\fR	0x10	Ctrl\-O
\fB\fCYAS\_K\_C\_Q\fR	0x11	Ctrl\-Q
\fB\fCYAS\_K\_C\_R\fR	0x12	Ctrl\-R
\fB\fCYAS\_K\_C\_S\fR	0x13	Ctrl\-S
\fB\fCYAS\_K\_C\_T\fR	0x14	Ctrl\-T
\fB\fCYAS\_K\_C\_U\fR	0x15	Ctrl\-U
\fB\fCYAS\_K\_C\_V\fR	0x16	Ctrl\-V
\fB\fCYAS\_K\_C\_W\fR	0x17	Ctrl\-W
\fB\fCYAS\_K\_C\_X\fR	0x18	Ctrl\-X
\fB\fCYAS\_K\_C\_Y\fR	0x19	Ctrl\-Y
\fB\fCYAS\_K\_C\_Z\fR	0x1a	Ctrl\-Z
\fB\fCYAS\_K\_ESC\fR	0x1b	T{
Esc, Ctrl\-3; see below; All ANSI sequences start with Esc, this is return after a timeout or double Esc
T}
\fB\fCYAS\_K\_C\_3\fR	0x1b	T{
Esc, Ctrl\-3; see above; All ANSI sequences start with Esc, this is return after a timeout or double Esc
T}
\fB\fCYAS\_K\_C\_4\fR	0x1c	Ctrl\-4
\fB\fCYAS\_K\_C\_5\fR	0x1d	Ctrl\-5
\fB\fCYAS\_K\_C\_6\fR	0x1e	Ctrl\-6
\fB\fCYAS\_K\_C\_7\fR	0x1f	Ctrl\-7
\fB\fCYAS\_K\_SPACE\fR	0x20	Space
\fB\fCYAS\_K\_EXCL\fR	0x21	!
\fB\fCYAS\_K\_DQUOT\fR	0x22	"
\fB\fCYAS\_K\_HASH\fR	0x23	#
\fB\fCYAS\_K\_POUND\fR	0x24	$
\fB\fCYAS\_K\_PERC\fR	0x25	%
\fB\fCYAS\_K\_AND\fR	0x26	Ampersand
\fB\fCYAS\_K\_QUOT\fR	0x27	\&'
\fB\fCYAS\_K\_OBRA\fR	0x28	(
\fB\fCYAS\_K\_CBRA\fR	0x29	)
\fB\fCYAS\_K\_STAR\fR	0x2a	*
\fB\fCYAS\_K\_PLUS\fR	0x2b	+
\fB\fCYAS\_K\_COMMA\fR	0x2c	,
\fB\fCYAS\_K\_MINUS\fR	0x2d	\-
\fB\fCYAS\_K\_DOT\fR	0x2e	\&.
\fB\fCYAS\_K\_SLASH\fR	0x2f	/
\fB\fCYAS\_K\_0\fR	0x30	0
\fB\fCYAS\_K\_1\fR	0x31	1
\fB\fCYAS\_K\_2\fR	0x32	2
\fB\fCYAS\_K\_3\fR	0x33	3
\fB\fCYAS\_K\_4\fR	0x34	4
\fB\fCYAS\_K\_5\fR	0x35	5
\fB\fCYAS\_K\_6\fR	0x36	6
\fB\fCYAS\_K\_7\fR	0x37	7
\fB\fCYAS\_K\_8\fR	0x38	8
\fB\fCYAS\_K\_9\fR	0x39	9
\fB\fCYAS\_K\_COLON\fR	0x3a	:
\fB\fCYAS\_K\_SEMI\fR	0x3b	;
\fB\fCYAS\_K\_LT\fR	0x3c	<
\fB\fCYAS\_K\_EQ\fR	0x3d	\fB\fC=\fR
\fB\fCYAS\_K\_GT\fR	0x3e	>
\fB\fCYAS\_K\_QUEST\fR	0x3f	?
\fB\fCYAS\_K\_AT\fR	0x40	@
\fB\fCYAS\_K\_A\fR	0x41	A
\fB\fCYAS\_K\_B\fR	0x42	B
\fB\fCYAS\_K\_C\fR	0x43	C
\fB\fCYAS\_K\_D\fR	0x44	D
\fB\fCYAS\_K\_E\fR	0x45	E
\fB\fCYAS\_K\_F\fR	0x46	F
\fB\fCYAS\_K\_G\fR	0x47	G
\fB\fCYAS\_K\_H\fR	0x48	H
\fB\fCYAS\_K\_I\fR	0x49	I
\fB\fCYAS\_K\_J\fR	0x4a	J
\fB\fCYAS\_K\_K\fR	0x4b	K
\fB\fCYAS\_K\_L\fR	0x4c	L
\fB\fCYAS\_K\_M\fR	0x4d	M
\fB\fCYAS\_K\_N\fR	0x4e	N
\fB\fCYAS\_K\_O\fR	0x4f	O
\fB\fCYAS\_K\_P\fR	0x50	P
\fB\fCYAS\_K\_Q\fR	0x51	Q
\fB\fCYAS\_K\_R\fR	0x52	R
\fB\fCYAS\_K\_S\fR	0x53	S
\fB\fCYAS\_K\_T\fR	0x54	T
\fB\fCYAS\_K\_U\fR	0x55	U
\fB\fCYAS\_K\_V\fR	0x56	V
\fB\fCYAS\_K\_W\fR	0x57	W
\fB\fCYAS\_K\_X\fR	0x58	X
\fB\fCYAS\_K\_Y\fR	0x59	Y
\fB\fCYAS\_K\_Z\fR	0x5a	Z
\fB\fCYAS\_K\_OSQ\fR	0x5b	[
\fB\fCYAS\_K\_BSLASH\fR	0x5c	\fB\fC\\\fR
\fB\fCYAS\_K\_CSQ\fR	0x5d	]
\fB\fCYAS\_K\_CARRET\fR	0x5e	^
\fB\fCYAS\_K\_USCORE\fR	0x5f	\fB\fC\_\fR
\fB\fCYAS\_K\_BTICK\fR	0x60	`
\fB\fCYAS\_K\_a\fR	0x61	a
\fB\fCYAS\_K\_b\fR	0x62	b
\fB\fCYAS\_K\_c\fR	0x63	c
\fB\fCYAS\_K\_d\fR	0x64	d
\fB\fCYAS\_K\_e\fR	0x65	e
\fB\fCYAS\_K\_f\fR	0x66	f
\fB\fCYAS\_K\_g\fR	0x67	g
\fB\fCYAS\_K\_h\fR	0x68	h
\fB\fCYAS\_K\_i\fR	0x69	i
\fB\fCYAS\_K\_j\fR	0x6a	j
\fB\fCYAS\_K\_k\fR	0x6b	k
\fB\fCYAS\_K\_l\fR	0x6c	l
\fB\fCYAS\_K\_m\fR	0x6d	m
\fB\fCYAS\_K\_n\fR	0x6e	n
\fB\fCYAS\_K\_o\fR	0x6f	o
\fB\fCYAS\_K\_p\fR	0x70	p
\fB\fCYAS\_K\_q\fR	0x71	q
\fB\fCYAS\_K\_r\fR	0x72	r
\fB\fCYAS\_K\_s\fR	0x73	s
\fB\fCYAS\_K\_t\fR	0x74	t
\fB\fCYAS\_K\_u\fR	0x75	u
\fB\fCYAS\_K\_v\fR	0x76	v
\fB\fCYAS\_K\_w\fR	0x77	w
\fB\fCYAS\_K\_x\fR	0x78	x
\fB\fCYAS\_K\_y\fR	0x79	y
\fB\fCYAS\_K\_z\fR	0x7a	z
\fB\fCYAS\_K\_OCUR\fR	0x7b	{
\fB\fCYAS\_K\_PIPE\fR	0x7c	|
\fB\fCYAS\_K\_CCUR\fR	0x7d	}
\fB\fCYAS\_K\_TLD\fR	0x7e	Tilde
\fB\fCYAS\_K\_C\_8\fR	0x7f	T{
Backspace; see below; depends on terminal see \fB\fCYAS\_K\_C\_H\fR
T}
\fB\fCYAS\_K\_BSP\fR	0x7f	T{
Backspace; see below; depends on terminal see \fB\fCYAS\_K\_C\_H\fR
T}
.TE

.RS
.IP \(bu 2
Extended keys, parsed from ANSI sequences

.RE

.TS
allbox;
l l l 
l l l .
\fB\fCName\fR	\fB\fCValue\fR	\fB\fCDescription\fR
\fB\fCYAS\_K\_F1\fR	0x100	F1
\fB\fCYAS\_K\_F2\fR	0x101	F2
\fB\fCYAS\_K\_F3\fR	0x102	F3
\fB\fCYAS\_K\_F4\fR	0x103	F4
\fB\fCYAS\_K\_F5\fR	0x104	F5
\fB\fCYAS\_K\_F6\fR	0x105	F6
\fB\fCYAS\_K\_F7\fR	0x106	F7
\fB\fCYAS\_K\_F8\fR	0x107	F8
\fB\fCYAS\_K\_F9\fR	0x108	F9
\fB\fCYAS\_K\_F10\fR	0x109	F10
\fB\fCYAS\_K\_F11\fR	0x10a	F11
\fB\fCYAS\_K\_F12\fR	0x10b	F12
\fB\fCYAS\_K\_S\_F1\fR	0x10c	Shift\-F1
\fB\fCYAS\_K\_S\_F2\fR	0x10d	Shift\-F2
\fB\fCYAS\_K\_S\_F3\fR	0x10e	Shift\-F3
\fB\fCYAS\_K\_S\_F4\fR	0x10f	Shift\-F4
\fB\fCYAS\_K\_S\_F5\fR	0x110	Shift\-F5
\fB\fCYAS\_K\_S\_F6\fR	0x111	Shift\-F6
\fB\fCYAS\_K\_S\_F7\fR	0x112	Shift\-F7
\fB\fCYAS\_K\_S\_F8\fR	0x113	Shift\-F8
\fB\fCYAS\_K\_S\_F9\fR	0x114	Shift\-F9
\fB\fCYAS\_K\_S\_F10\fR	0x115	Shift\-F10
\fB\fCYAS\_K\_S\_F11\fR	0x116	Shift\-F11
\fB\fCYAS\_K\_S\_F12\fR	0x117	Shift\-F12
\fB\fCYAS\_K\_C\_F1\fR	0x118	Ctrl\-F1
\fB\fCYAS\_K\_C\_F2\fR	0x119	Ctrl\-F2
\fB\fCYAS\_K\_C\_F3\fR	0x11a	Ctrl\-F3
\fB\fCYAS\_K\_C\_F4\fR	0x11b	Ctrl\-F4
\fB\fCYAS\_K\_C\_F5\fR	0x11c	Ctrl\-F5
\fB\fCYAS\_K\_C\_F6\fR	0x11d	Ctrl\-F6
\fB\fCYAS\_K\_C\_F7\fR	0x11e	Ctrl\-F7
\fB\fCYAS\_K\_C\_F8\fR	0x11f	Ctrl\-F8
\fB\fCYAS\_K\_C\_F9\fR	0x120	Ctrl\-F9
\fB\fCYAS\_K\_C\_F10\fR	0x121	Ctrl\-F10
\fB\fCYAS\_K\_C\_F11\fR	0x122	Ctrl\-F11
\fB\fCYAS\_K\_C\_F12\fR	0x123	Ctrl\-F12
\fB\fCYAS\_K\_A\_F1\fR	0x124	Alt\-F1
\fB\fCYAS\_K\_A\_F2\fR	0x125	Alt\-F2
\fB\fCYAS\_K\_A\_F3\fR	0x126	Alt\-F3
\fB\fCYAS\_K\_A\_F4\fR	0x127	Alt\-F4
\fB\fCYAS\_K\_A\_F5\fR	0x128	Alt\-F5
\fB\fCYAS\_K\_A\_F6\fR	0x129	Alt\-F6
\fB\fCYAS\_K\_A\_F7\fR	0x12a	Alt\-F7
\fB\fCYAS\_K\_A\_F8\fR	0x12b	Alt\-F8
\fB\fCYAS\_K\_A\_F9\fR	0x12c	Alt\-F9
\fB\fCYAS\_K\_A\_F10\fR	0x12d	Alt\-F10
\fB\fCYAS\_K\_A\_F11\fR	0x12e	Alt\-F11
\fB\fCYAS\_K\_A\_F12\fR	0x12f	Alt\-F12
\fB\fCYAS\_K\_LEFT\fR	0x130	Left
\fB\fCYAS\_K\_UP\fR	0x131	Up
\fB\fCYAS\_K\_DOWN\fR	0x132	Down
\fB\fCYAS\_K\_RIGHT\fR	0x133	Right
\fB\fCYAS\_K\_HOME\fR	0x134	Home
\fB\fCYAS\_K\_END\fR	0x135	End
\fB\fCYAS\_K\_PGUP\fR	0x136	PageUp
\fB\fCYAS\_K\_PGDN\fR	0x137	PageDown
\fB\fCYAS\_K\_INS\fR	0x138	Insert
\fB\fCYAS\_K\_DEL\fR	0x139	Delete
\fB\fCYAS\_K\_C\_LEFT\fR	0x13a	Ctrl\-Left
\fB\fCYAS\_K\_C\_UP\fR	0x13b	Ctrl\-Up
\fB\fCYAS\_K\_C\_DOWN\fR	0x13c	Ctrl\-Down
\fB\fCYAS\_K\_C\_RIGHT\fR	0x13d	Ctrl\-Right
.TE

.RS
.IP \(bu 2
Alt\-<letter>

.RE

.PP
These codes are generated by a helper macro \- \fB\fCYAS\_K\_ALT(keycode)\fR\&.

.TS
allbox;
l l 
l l .
\fB\fCName\fR	\fB\fCDescription\fR
\fB\fCYAS\_K\_A\_BT\fR	Alt\-Backtick
\fB\fCYAS\_K\_A\_1\fR	Alt\-1
\fB\fCYAS\_K\_A\_2\fR	Alt\-2
\fB\fCYAS\_K\_A\_3\fR	Alt\-3
\fB\fCYAS\_K\_A\_4\fR	Alt\-4
\fB\fCYAS\_K\_A\_5\fR	Alt\-5
\fB\fCYAS\_K\_A\_6\fR	Alt\-6
\fB\fCYAS\_K\_A\_7\fR	Alt\-7
\fB\fCYAS\_K\_A\_8\fR	Alt\-8
\fB\fCYAS\_K\_A\_9\fR	Alt\-9
\fB\fCYAS\_K\_A\_0\fR	Alt\-0
\fB\fCYAS\_K\_A\_MINUS\fR	Alt\-Minus
\fB\fCYAS\_K\_A\_EQ\fR	Alt\-=
\fB\fCYAS\_K\_A\_BSP\fR	Alt\-Backspace
\fB\fCYAS\_K\_A\_TLD\fR	Alt\-Tilde
\fB\fCYAS\_K\_A\_EXCL\fR	Alt\-!
\fB\fCYAS\_K\_A\_AT\fR	Alt\-@
\fB\fCYAS\_K\_A\_HASH\fR	Alt\-#
\fB\fCYAS\_K\_A\_POUND\fR	Alt\-$
\fB\fCYAS\_K\_A\_PERC\fR	Alt\-%
\fB\fCYAS\_K\_A\_CARRET\fR	Alt\-^
\fB\fCYAS\_K\_A\_AND\fR	Alt\-Ampersand
\fB\fCYAS\_K\_A\_STAR\fR	Alt\-*
\fB\fCYAS\_K\_A\_OBRA\fR	Alt\-(
\fB\fCYAS\_K\_A\_CBRA\fR	Alt\-)
\fB\fCYAS\_K\_A\_UND\fR	Alt\-\_
\fB\fCYAS\_K\_A\_PLUS\fR	Alt\-+
\fB\fCYAS\_K\_A\_a\fR	Alt\-a
\fB\fCYAS\_K\_A\_b\fR	Alt\-b
\fB\fCYAS\_K\_A\_c\fR	Alt\-c
\fB\fCYAS\_K\_A\_d\fR	Alt\-d
\fB\fCYAS\_K\_A\_e\fR	Alt\-e
\fB\fCYAS\_K\_A\_f\fR	Alt\-f
\fB\fCYAS\_K\_A\_g\fR	Alt\-g
\fB\fCYAS\_K\_A\_h\fR	Alt\-h
\fB\fCYAS\_K\_A\_i\fR	Alt\-i
\fB\fCYAS\_K\_A\_j\fR	Alt\-j
\fB\fCYAS\_K\_A\_k\fR	Alt\-k
\fB\fCYAS\_K\_A\_l\fR	Alt\-l
\fB\fCYAS\_K\_A\_m\fR	Alt\-m
\fB\fCYAS\_K\_A\_n\fR	Alt\-n
\fB\fCYAS\_K\_A\_o\fR	Alt\-o
\fB\fCYAS\_K\_A\_p\fR	Alt\-p
\fB\fCYAS\_K\_A\_q\fR	Alt\-q
\fB\fCYAS\_K\_A\_r\fR	Alt\-r
\fB\fCYAS\_K\_A\_s\fR	Alt\-s
\fB\fCYAS\_K\_A\_t\fR	Alt\-t
\fB\fCYAS\_K\_A\_u\fR	Alt\-u
\fB\fCYAS\_K\_A\_v\fR	Alt\-v
\fB\fCYAS\_K\_A\_w\fR	Alt\-w
\fB\fCYAS\_K\_A\_x\fR	Alt\-x
\fB\fCYAS\_K\_A\_y\fR	Alt\-y
\fB\fCYAS\_K\_A\_z\fR	Alt\-z
.TE

.SH Functions
.PP
All functions in the API work with a pointer to an opaque \fB\fCyascreen\fR structure.

.PP
The structure is allocated internally in the library by \fB\fCyascreen\_init\fR and it is the job of the user program to keep track of it.

.PP
The library is thread safe, as long as each \fB\fCstruct yascreen\fR object is accessed by a single thread.

.SS yascreen\_init
.PP
.RS

.nf
inline yascreen *yascreen\_init(int sx,int sy);

.fi
.RE

.PP
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

.PP
in case of error, returns \fB\fCNULL\fR

.SS yascreen\_ver
.PP
.RS

.nf
inline const char *yascreen\_ver(void);

.fi
.RE

.PP
returns a string with the library version

.SS yascreen\_setout
.PP
.RS

.nf
inline int yascreen\_setout(yascreen *s,ssize\_t (*out)(yascreen *s,const void *data,size\_t len));

.fi
.RE

.PP
set callback that handles output
if out=NULL, the output goes to \fB\fCstdout\fR

.PP
the callback may implement internal buffering, a flush is signalled by calling \fB\fCout\fR with len=0

.SS yascreen\_set\_telnet
.PP
.RS

.nf
inline void yascreen\_set\_telnet(yascreen *s,int on);

.fi
.RE

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

.SS yascreen\_init\_telnet
.PP
.RS

.nf
inline void yascreen\_init\_telnet(yascreen *s);

.fi
.RE

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

.SS yascreen\_resize
.PP
.RS

.nf
inline int yascreen\_resize(yascreen *s,int sx,int sy);

.fi
.RE

.PP
resize screen
should redraw afterwards
since allocation is involved, this may fail and return \-1

.SS yascreen\_free
.PP
.RS

.nf
inline void yascreen\_free(yascreen *s);

.fi
.RE

.PP
finish the lifecycle of \fB\fCstruct yascreen\fR \- all internally allocated memory is freed

.SS yascreen\_term\_save
.PP
.RS

.nf
inline void yascreen\_term\_save(yascreen *s);

.fi
.RE

.PP
save current terminal state on top of state stack

.SS yascreen\_term\_restore
.PP
.RS

.nf
inline void yascreen\_term\_restore(yascreen *s);

.fi
.RE

.PP
restore previously saved terminal state from top of state stack

.SS yascreen\_term\_push
.PP
.RS

.nf
inline void yascreen\_term\_push(yascreen *s);

.fi
.RE

.PP
push current terminal state to state stack

.SS yascreen\_term\_pop
.PP
.RS

.nf
inline void yascreen\_term\_pop(yascreen *s);

.fi
.RE

.PP
pop and restore previously saved terminal state from state stack

.SS yascreen\_term\_set
.PP
.RS

.nf
inline void yascreen\_term\_set(yascreen *s,int mode);

.fi
.RE

.PP
set terminal for proper screen operation

.SS \fB\fCmode\fR is a bitmask, containing one of
.TS
allbox;
l l l 
l l l .
\fB\fCName\fR	\fB\fCValue\fR	\fB\fCDescription\fR
\fB\fCYAS\_NOBUFF\fR	1	T{
turn off canonical mode (disable \fB\fCICANON\fR and \fB\fCIEXTEN\fR)
T}
\fB\fCYAS\_NOSIGN\fR	2	disable \fB\fCISIG\fR
\fB\fCYAS\_NOECHO\fR	4	T{
disable local echo (\fB\fCECHO\fR)
T}
\fB\fCYAS\_ONLCR\fR	8	\fB\fCONLCR\fR|\fB\fCOPOST\fR
.TE

.SS yascreen\_printxy
.PP
.RS

.nf
inline int yascreen\_printxy(yascreen *s,int x,int y,uint32\_t attr,const char *format,...) \_\_attribute\_\_((format(printf,5,6)));

.fi
.RE

.SS yascreen\_putsxy
.PP
.RS

.nf
inline int yascreen\_putsxy(yascreen *s,int x,int y,uint32\_t attr,const char *str);

.fi
.RE

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

.SS yascreen\_printxyu
.PP
.RS

.nf
inline int yascreen\_printxyu(yascreen *s,int x,int y,uint32\_t attr,const char *format,...) \_\_attribute\_\_((format(printf,5,6)));

.fi
.RE

.SS yascreen\_putsxyu
.PP
.RS

.nf
inline int yascreen\_putsxyu(yascreen *s,int x,int y,uint32\_t attr,const char *str);

.fi
.RE

.PP
print at position, if data exceeds buffer, then it gets truncated
screen is immediately updated

.SS yascreen\_update
.PP
.RS

.nf
inline int yascreen\_update(yascreen *s);

.fi
.RE

.PP
sync memory state to screen
since allocation is involved, this may fail and return \-1

.SS yascreen\_redraw
.PP
.RS

.nf
inline void yascreen\_redraw(yascreen *s);

.fi
.RE

.PP
set next update to be a full redraw

.SS yascreen\_clear\_mem
.PP
.RS

.nf
inline void yascreen\_clear\_mem(yascreen *s,uint32\_t attr);

.fi
.RE

.PP
clear memory buffer
all cells in the screen are set to \fB\fCSpace\fR, using \fB\fCattr\fR for colors and style

.SS yascreen\_cursor
.PP
.RS

.nf
inline void yascreen\_cursor(yascreen *s,int on);

.fi
.RE

.PP
hide (\fB\fCon\fR=0) or show (\fB\fCon\fR is non\-zero) cusror
screen is updated immediately

.SS yascreen\_cursor\_xy
.PP
.RS

.nf
inline void yascreen\_cursor\_xy(yascreen *s,int x,int y);

.fi
.RE

.PP
set cursor position
screen is updated immediately

.SS yascreen\_altbuf
.PP
.RS

.nf
inline void yascreen\_altbuf(yascreen *s,int on);

.fi
.RE

.PP
switch between regular and alternative buffer
screen is updated immediately

.SS yascreen\_clear
.PP
.RS

.nf
inline void yascreen\_clear(yascreen *s);

.fi
.RE

.PP
clear real screen, no change to memory buffers

.SS yascreen\_clearln
.PP
.RS

.nf
inline void yascreen\_clearln(yascreen *s);

.fi
.RE

.PP
clear current line, no change to memory buffers

.SS yascreen\_update\_attr
.PP
.RS

.nf
inline void yascreen\_update\_attr(yascreen *s,uint32\_t oattr,uint32\_t nattr);

.fi
.RE

.PP
apply difference between two attrs and output the optimized ANSI sequence to switch from \fB\fCoattr\fR to \fB\fCnattr\fR
if \fB\fCoattr\fR=0xffffffff, the full ANSI sequence will be generated
no change to memory buffers

.SS yascreen\_set\_attr
.PP
.RS

.nf
yascreen\_set\_attr(s,attr)

.fi
.RE

.PP
reset all attrs and set specific one (\fB\fCattr\fR)

.SS yascreen\_print
.PP
.RS

.nf
inline int yascreen\_print(yascreen *s,const char *format,...) \_\_attribute\_\_((format(printf,2,3)));

.fi
.RE

.SS yascreen\_write
.PP
.RS

.nf
inline int yascreen\_write(yascreen *s,const char *str,int len);

.fi
.RE

.SS yascreen\_puts
.PP
.RS

.nf
inline int yascreen\_puts(yascreen *s,const char *str);

.fi
.RE

.SS yascreen\_clearln\_s
.PP
.RS

.nf
inline const char *yascreen\_clearln\_s(yascreen *s);

.fi
.RE

.PP
print in line mode

.SS yascreen\_sx
.PP
.RS

.nf
inline int yascreen\_sx(yascreen *s);

.fi
.RE

.PP
get current x size

.SS yascreen\_sy
.PP
.RS

.nf
inline int yascreen\_sy(yascreen *s);

.fi
.RE

.PP
get current y size

.SS yascreen\_x
.PP
.RS

.nf
inline int yascreen\_x(yascreen *s);

.fi
.RE

.PP
get current x

.SS yascreen\_y
.PP
.RS

.nf
inline int yascreen\_y(yascreen *s);

.fi
.RE

.PP
get current y

.SS yascreen\_esc\_to
.PP
.RS

.nf
inline void yascreen\_esc\_to(yascreen *s,int timeout);

.fi
.RE

.PP
set timeout for single ESC key press

.SS yascreen\_ckto
.PP
.RS

.nf
inline void yascreen\_ckto(yascreen *s);

.fi
.RE

.PP
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

.SS yascreen\_getch\_to
.PP
.RS

.nf
inline int yascreen\_getch\_to(yascreen *s,int timeout);

.fi
.RE

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

.SS yascreen\_getch
.PP
.RS

.nf
yascreen\_getch(s)

.fi
.RE

.PP
get a key without timeout
this macro expands to \fB\fCyascreen\_getch\_to(s,0)\fR
zero timeout=wait forever

.SS yascreen\_getch\_nowait
.PP
.RS

.nf
yascreen\_getch\_nowait(s)

.fi
.RE

.PP
get a key, if available, return immediately
this macro expands to \fB\fCyascreen\_getch\_to(s,\-1)\fR
negative timeout=do not wait

.SS yascreen\_ungetch
.PP
.RS

.nf
inline void yascreen\_ungetch(yascreen *s,int key);

.fi
.RE

.PP
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

.SS yascreen\_pushch
.PP
.RS

.nf
inline void yascreen\_pushch(yascreen *s,int key);

.fi
.RE

.PP
push key value at end of key buffer
similar to \fB\fCyascreen\_ungetch\fR but the \fB\fCkey\fR 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

.SS yascreen\_feed
.PP
.RS

.nf
inline void yascreen\_feed(yascreen *s,unsigned char c);

.fi
.RE

.PP
feed key sequence state machine with byte stream
this is useful to implement external event loop and read key codes by \fB\fCyascreen\_getch\_nowait\fR until it returns \-1

.SS yascreen\_peekch
.PP
.RS

.nf
inline int yascreen\_peekch(yascreen *s);

.fi
.RE

.PP
peek for key without removing it from input queue

.SS yascreen\_getsize
.PP
.RS

.nf
inline void yascreen\_getsize(yascreen *s,int *sx,int *sy);

.fi
.RE

.PP
get last reported screen size
set both to 0 if there is none
this will yield valid result after \fB\fCYAS\_SCREEN\_SIZE\fR is returned as keypress

.SS yascreen\_reqsize
.PP
.RS

.nf
inline void yascreen\_reqsize(yascreen *s);

.fi
.RE

.PP
request terminal to report its size via ANSI sequence

.SS yascreen\_set\_hint\_i
.PP
.RS

.nf
inline void yascreen\_set\_hint\_i(yascreen *s,int hint);

.fi
.RE

.SS yascreen\_get\_hint\_i
.PP
.RS

.nf
inline int yascreen\_get\_hint\_i(yascreen *s);

.fi
.RE

.SS yascreen\_set\_hint\_p
.PP
.RS

.nf
inline void yascreen\_set\_hint\_p(yascreen *s,void *hint);

.fi
.RE

.SS yascreen\_get\_hint\_p
.PP
.RS

.nf
inline void *yascreen\_get\_hint\_p(yascreen *s);

.fi
.RE

.PP
get/set opaque hint values
integer and pointer hints are stored separately and both can be used at the same time

.PP
these are useful to link the \fB\fCyascreen\fR instance to user program data

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

.SS yascreen\_line\_flush
.PP
.RS

.nf
inline void yascreen\_line\_flush(yascreen *s,int on);

.fi
.RE

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

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

.PP
disabling internal flush can help an application optimize the number of \fB\fCwrite\fR calls at the cost of performing explicit flush after each group of operations

.PP
explicit flush example:

.PP
.RS

.nf
yascreen\_write(s,"",0);

.fi
.RE