Provided by: libtickit-dev_0.2-5_amd64 bug

NAME

       TickitTerm - abstraction of an interactive terminal

SYNOPSIS

       #include <tickit.h>

       typedef struct TickitTerm;

DESCRIPTION

       A  TickitTerm  instance  represents an interactive user terminal. It provides functions to
       draw content to the terminal, and to accept input and other events from it. It supports  a
       variety  of  modes of operation; allowing both synchronous and asynchronous filehandle IO,
       and working abstractly via byte buffers.

FUNCTIONS

       A   new   TickitTerm   instance   is   created    using    the    tickit_term_new(3)    or
       tickit_term_new_for_termtype(3) functions. A terminal instance stores a reference count to
       make it easier for applications to manage the lifetime of terminals. A new terminal starts
       with  reference  count  of  one,  and  it  can  be  adjusted  using tickit_term_ref(3) and
       tickit_term_unref(3). When the count reaches zero the instance is destroyed.

       The tickit_term_open_stdio(3) function offers a convenient  shortcut  to  creating  a  new
       instance set up to represent the standard input and output streams of the process.

       A terminal instance will need either an output function or an output filehandle set before
       it can send output. This can be  performed  by  either  tickit_term_set_output_func(3)  or
       tickit_term_set_output_fd(3).     An     output     buffer     can     be    defined    by
       tickit_term_set_output_buffer(3). If output is via a filehandle, then  the  size  of  that
       will  be  queried  if it is a TTY.  If output is via an output function only then the size
       must  be  set  using  tickit_term_set_size(3).  An  input  filehandle  can  be  set  using
       tickit_term_set_input_fd(3),   or   input   can   be   sent   from  a  byte  buffer  using
       tickit_term_input_push_bytes(3). Once input  and  output  methods  are  set  the  terminal
       startup  actions  are performed, and the tickit_term_await_started_msec(3) function can be
       used  to  wait  until  this  is  complete.  A  running  instance  can  be   paused   using
       tickit_term_pause(3) and resumed using tickit_term_resume(3).

       It supports UTF-8 if enabled; either by detection of a UTF-8 locale, explicitly by calling
       tickit_term_set_utf8(3).

       The size of the terminal can be queried using  tickit_term_get_size(3),  or  forced  to  a
       given  size  by  tickit_term_set_size(3).  If  the application is aware that the size of a
       terminal represented by a tty(7) filehandle has changed (for example due to receipt  of  a
       SIGWINCH  signal),  it  can call tickit_term_refresh_size(3) to update it. The type of the
       terminal   is   set   at   construction   time   but   can   be   queried   later    using
       tickit_term_get_termtype(3).

OUTPUT

       Once  an  output method is defined, a terminal instance can be used for outputting drawing
       and other commands. For drawing, the functions tickit_term_print(3),  tickit_term_goto(3),
       tickit_term_move(3),            tickit_term_scrollrect(3),           tickit_term_chpen(3),
       tickit_term_setpen(3),  tickit_term_clear(3)  and  tickit_term_erasech(3)  can  be   used.
       Additionally  for setting modes, the function tickit_term_setctl_int(3) can be used. If an
       output buffer is defined it will need to be flushed when drawing is  complete  by  calling
       tickit_term_flush(3).

INPUT

       Input   via   a   filehandle   can   be   received   either   synchronously   by   calling
       tickit_term_input_wait_msec(3), or asynchronously by calling tickit_term_input_readable(3)
       and  tickit_term_input_check_timeout_msec(3). Any of these functions may cause one or more
       events to be raised by invoking event handler functions.

EVENTS

       A terminal instance stores a list of event handlers. Each event handler is associated with
       one  event  type  and  stores a function pointer, and an arbitrary pointer containing user
       data. Event handlers may be installed using tickit_term_bind_event(3)  and  removed  using
       tickit_term_unbind_event_id(3).

       Fake events can be artificially injected into the event handler chain, as if they had been
       received   from    the    controlling    terminal,    by    tickit_term_emit_key(3)    and
       tickit_term_emit_mouse(3).  These  may be useful for testing, event capture-and-replay, or
       other specialised cases.

       The event types recognised are:

       TICKIT_TERM_ON_DESTROY
              The terminal instance is being destroyed.

       TICKIT_TERM_ON_RESIZE
              The terminal has been resized. info will point to a structure defined as:

              typedef struct {
                  int lines;
                  int cols;
              } TickitResizeEventInfo;

       TICKIT_TERM_ON_KEY
              A key has been pressed on the keyboard. info will point to a structure defined as:

              typedef struct {
                  TickitKeyEventType type;
                  int mod;
                  const char *str;
              } TickitKeyEventInfo;

              type is an enumeration that gives the specific type of key event.

              TICKIT_KEYEV_KEY
                     a cursor control, arrow key, or function key. i.e.  any  of  the  keys  that
                     don't directly produce text.

              TICKIT_KEYEV_TEXT
                     regular Unicode characters.

       str  will contain the name of the special key, including any applied modifiers, or a UTF-8
       string of the Unicode character.

       mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

       This event only runs until a bound function returns a  true  value;  this  prevents  later
       handler functions from observing it.

       TICKIT_TERM_ON_MOUSE
              A  mouse button has been pressed or released, the mouse cursor moved while dragging
              a button, or the wheel has been scrolled. info will point to  a  structure  defined
              as:

              typedef struct {
                  TickitMouseEventType type;
                  int button;
                  int mod;
                  int line;
                  int col;
              } TickitMouseEventInfo;

              type is an enumeration that gives the specific type of mouse event.

              TICKIT_MOUSEEV_PRESS
                     A mouse button has been pressed.

              TICKIT_MOUSEEV_DRAG
                     The mouse has been moved while a button is being held down.

              TICKIT_MOUSEEV_RELEASE
                     A mouse button has been released.

              TICKIT_MOUSEEV_WHEEL
                     The wheel has been rolled.

       button  gives  the  button  index  for  button  events,  or one of TICKIT_MOUSEWHEEL_UP or
       TICKIT_MOUSEWHEEL_DOWN for wheel events.

       line and col give the position of the mouse cursor for this event.

       mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

       This event only runs until a bound function returns a  true  value;  this  prevents  later
       handler functions from observing it.

SEE ALSO

       tickit(7), tickit_renderbuffer(7)

                                                                                   TICKIT_TERM(7)