NAME

       libtty - a library for handling vt100-like pseudo-terminals

SYNOPSIS

       #include <tty.h>

       Link with -ltty.

DESCRIPTION

   Functions:
       tty    tty_init(int sx, int sy, int resizable);
           Creates a new vt100 terminal, of size sxXsy.  If you want user input to be allowed to
           change that size, set resizable to non-zero.

       int    tty_resize(tty vt, int nsx, int nsy);
           Resizes the vt to nsxXnsy.  This works even on terminals marked as non-resizable since
           that prevents only user input from resizing, not you.

       void   tty_reset(tty vt);
           Clears the screen and attributes.

       void   tty_free(tty vt);
           Deallocates the vt and all its internal structures.

       void   tty_write(tty vt, const char *buf, int len);
           Writes len bytes into the terminal, parsing them as vt100 codes.

       void   tty_printf(tty vt, const char *fmt, ...);
           Does a printf into the terminal.

       tty    tty_copy(tty vt);
           Allocates a new vt100 terminal, making it an exact copy of an existing one, including
           its internal state.  Attached event callbacks are not copied.

       uint32_t tty_color_convert(uint32_t c, uint32_t to);
           Converts color values between modes: VT100_COLOR_OFF, VT100_COLOR_16, VT100_COLOR_256,
           VT100_COLOR_RGB.

   Inside the terminal
       You'll most likely be interested in the following fields of the structure:

       tty {
       int sx,sy;             // screen size
       int cx,cy;             // cursor position
       attrchar *scr;         // screen buffer
       int attr;              // current attribute
       char *title;           // window title

       scr is an array of character/attribute pairs, more exactly, each element is a struct "{
       ucs ch; int attr; }".  The array is a flat one of vt->sx*vt->sy elements, arranged row by
       row.  A screen coordinate x,y is stored at x+y*vt->sy.

       For other fields, please RTFS the header itself: tty.h

   TTY event callbacks
       Well, you have written some data to the terminal.  Now you probably want to put it
       somewhere.  What now?  The tty structure has a number of event hooks that you can attach
       your functions to.

       These hooks are callbacks inside the tty structure that you can set.  The callback fields
       are:

       void *l_data;
           it's a place to put your private data in

       void (*l_char)(tty vt, int x, int y, ucs ch, int attr, int width);
           after a character has been written to the screen; the cursor advances by width which
           might be 1 (regular) or 2 (CJK "fullwidth")

       void (*l_cursor)(tty vt, int x, int y);
           after the cursor has moved

       void (*l_clear)(tty vt, int x, int y, int len);
           after a chunk of screen has been cleared

           If an endpoint spills outside of the current line, it will go all the way to an end of
           screen.

           If the cursor moves, you'll get a separate l_cursor, although it is already in place
           during the l_clear call.

       void (*l_scroll)(tty vt, int nl);
           after the region s1<=y<s2 is scrolled nl lines (nl<0 -> backwards, nl>0 -> forward).

           There's no separare l_cursor event, cx and cy are already updated.

       void (*l_flag)(tty vt, int f, int v);
           when a flag changes to v.  Flags that are likely to be of interest to you are:

           •   VT100_FLAG_CURSOR

               cursor visibility

           •   VT100_FLAG_KPAD

               application keypad mode (more detailed codes for keypad arrow keys)

       void (*l_osc)(tty vt, int cmd, const char *str);
           when a string command has been issued; most commands alter a color palette, but the
           most interesting one is 0: "set window title"

       void (*l_resize)(tty vt, int sx, int sy);
           after the terminal has been resized

       void (*l_flush)(tty vt);
           when a write chunk ends

       void (*l_bell)(tty vt);
           upon a beep

       void (*l_free)(tty vt);
           before the terminal is destroyed

   Vt-on-vt redirection
       For the case when you want the output go to a real terminal, there are:

       void   vtvt_attach(tty vt, FILE *f, int dump);
           Attaches the FILE stream f to terminal vt.  Usually, f will be stdout.  Whenever the
           contents of vt changes, appropriate data will be written to the stream as well.  If
           dump is non-zero, the current state will be drawn, otherwise, only subsequent changes
           will be shown.

           The redirection will last until the terminal is destroyed by tty_free().

       void   vtvt_resize(tty vt, int sx, int sy);
           Tells libtty that the real terminal has been resized (for resizing the virtual one,
           please use tty_resize()).

       void   vtvt_dump(tty vt);
           Forces a full-screen redraw of the current contents of vt.

SEE ALSO

       libttyrec(3)