Ubuntu Manpage: TickitTerm - abstraction of an interactive terminal

Provided by: libtickit-dev_0.4.3-2_amd64

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_build(3). 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.

       Once     built    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 can be stopped entirely  ahead  of  application  termination  by
       tickit_term_teardown(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

       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.

CONTROLS

A terminal instance has a number of runtime-configuration control options that affect its
behaviour. These can be set using tickit_term_setctl_int(3) and tickit_term_setctl_str(3),
and queried using tickit_term_getctl_int(3). The individual controls have human-readable
string names that can be obtained by tickit_termctl_name(3) and searched by name using
tickit_termctl_lookup(3). The type of a control option can be queried using
tickit_termctl_type(3).

The options are given in an enumeration called TickitTermCtl. The following control values
are recognised:

TICKIT_TERMCTL_ALTSCREEN (bool)
The value is a boolean indicating whether the terminal alternate buffer mode should
be enabled. When enabled, a temporary buffer is used for drawing, preserving the
original contents of the screen. This mode is usually used by full-screen
applications to preserve the shell's scrollback state.

TICKIT_TERMCTL_COLORS (int, read-only)
The value indicates how many colors are available. This value is read-only; it can
be requested but not set.

On terminfo-driven terminals this will likely be 8, 16, or 256. On xterm-like
terminals this will be 16,777,216 (i.e. 1 << 24) if the driver detects that the
terminal supports 24-bit RGB8 ("true-color") palettes, or 256 if not.

TICKIT_TERMCTL_CURSORBLINK (bool)
The value is a boolean indicating whether the terminal text cursor should blink.
When disabled, the cursor will appear in a steady state, if visible. When enabled,
the cursor will appear blinking, if visible. If the cursor is invisible, this
should not have any effect.

TICKIT_TERMCTL_CURSORSHAPE (int)
The value is an integer from the TickitCursorShape enumeration indicating what
shape the terminal's text cursor should be. Values are:

TICKIT_CURSORSHAPE_BLOCK
A solid block filling the entire cell.

TICKIT_CURSORSHAPE_UNDER
An underline below the character.

TICKIT_CURSORSHAPE_LEFT_BAR
A vertical bar to the left of the character.

Note that not all terminals support setting this option, nor to all of the possible
values.

TICKIT_TERMCTL_CURSORVIS (bool)
The value is a boolean indicating whether the terminal text cursor should be
visible. When disabled the cursor position is not visible. Typically applications
will hide the cursor while performing redrawing operations so as not to show a
flickering effect as the cursor moves, and show it again when drawing is complete.

TICKIT_TERMCTL_ICON_TEXT (str)
The value is a string for the terminal to use as its minimised icon text.

TICKIT_TERMCTL_ICONTITLE_TEXT (str)
The value is a string for the terminal to use as its minimised icon text and main
window title.

TICKIT_TERMCTL_KEYPAD_APP (bool)
The value is a boolean controlling the terminal's keypad mode. When enabled, the
terminal is in keypad application mode; in this mode the numerical keypad will send
different sequences that can be detected as distinct from regular ASCII text. When
disabled, the keypad will send normal text.

TICKIT_TERMCTL_MOUSE (int)
The value is an integer from the TickitTermMouseMode enumeration indicating what
mouse events should be sent. Values are:

BTICKIT_TERM_MOUSEMODE_CLICK
Report button press and release events.

TICKIT_TERM_MOUSEMODE_DRAG
Report button press and release events, and movement while a button is held.

TICKIT_TERM_MOUSEMODE_MOVE
Report all button press, release and motion events even with no buttons
held.

TICKIT_TERM_MOUSEMODE_OFF
Report nothing.

TICKIT_TERMCTL_TITLE_TEXT (str)
The value is a string for the terminal to use as its main window title.