focal (7) tickit_term.7.gz

Provided by: libtickit-dev_0.3.4-1_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.

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_term_ctlname(3) and searched by name using tickit_term_lookup_ctl(3). The  type  of  a  control
       option can be queried using tickit_term_ctltype(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.

SEE ALSO

       tickit(7), tickit_renderbuffer(7)

                                                                                                  TICKIT_TERM(7)