Ubuntu Manpage: tickit - Terminal Interface Construction KIT

Provided by: libtickit-dev_0.4.2a-1_amd64

NAME

       tickit - Terminal Interface Construction KIT

SYNOPSIS

       #include <tickit.h>

       typedef struct Tickit;

DESCRIPTION

       tickit  is  a  library  for  building full-screen interactive programs that use a terminal
       interface. A program using  this  library  would  start  by  creating  a  toplevel  Tickit
       instance,  from  which  one  or  more divisions of the terminal area, called "windows" are
       created. These form a heirarchial tree that subdivides the content area  into  independent
       regions  that  can be managed by different parts of the program structure. Each window can
       react to input events such as keyboard or mouse interaction.

       As well as creating the initial root window, the toplevel Tickit instance also performs  a
       few  other  jobs for the containing program. It can act as a containing event loop for the
       program, performing IO multiplexing tasks both for tickit's own needs and the needs of the
       program as a whole.

FUNCTIONS

       A  new  toplevel  instance  is  created  by  using tickit_build(3), tickit_new_stdio(3) or
       tickit_new_stdtty(3). A toplevel instance stores a reference count to make it  easier  for
       applications  to  manage its lifetime. A new toplevel instance starts with a count of one,
       and it can be adjusted using tickit_ref(3) and tickit_unref(3).  When  the  count  reaches
       zero the instance is destroyed.

       The  toplevel  instance manages a tree of TickitWindow instances. The root of this tree is
       obtained by tickit_get_rootwin(3) and thereafter can be divided further by other functions
       on the window, described more in tickit_window(7).

       The   TickitTerm   instance   behind   the   toplevel   instance   can   be   obtained  by
       tickit_get_term(3), and is described more in tickit_term(7).

       Event handling callback functions can be installed to be called at a later time, by  using
       tickit_watch_io(3),    tickit_watch_timer_after_msec(3),   tickit_watch_timer_after_tv(3),
       tickit_watch_later(3), tickit_watch_signal(3)  or  tickit_watch_process(3).  The  main  IO
       event loop is controlled using tickit_run(3) and tickit_stop(3).

       The compile-time and run-time version of the library can be inspected using the macros and
       functions described in tickit_version(7).

TYPICAL STRUCTURE

       A typical program using this library would start by creating  the  toplevel  instance,  by
       calling   tickit_new_stdtty(3),   then   obtain   its   root   window  on  it  by  calling
       tickit_get_rootwin(3). This root window can then be sub-divided into regions  of  interest
       by  calling  tickit_window_new(3)  to  build  a tree of windows. Window can then have some
       event handlers attached by calling tickit_window_bind_event(3) - each window will need  to
       handle  the  TICKIT_WINDOW_ON_EXPOSE event, but might also wish to handle other kinds like
       geometry change for dynamic resizing, or  keyboard  or  mouse  to  react  to  user  input.
       Finally,  once  the initial window tree is created, the program would enter the main event
       loop by invoking tickit_run(3).

COMMON TYPES

       The flags argument to the various tickit_..._bind_event() functions should be zero,  or  a
       bitmask of the following constants.

       typedef enum {
         TICKIT_BIND_FIRST,
         TICKIT_BIND_UNBIND,
         TICKIT_BIND_DESTROY,
         TICKIT_BIND_ONESHOT,
       } TickitBindFlags;

       TICKIT_BIND_FIRST indicates that this handler should be inserted at the start of the list,
       rather than the default position at the end.

       TICKIT_BIND_UNBIND indicates that this handler should also be invoked at the  time  it  is
       unbound,  either  due  to  a  specific  call to the tickit_..._unbind_event() function, or
       because the bound object is being destroyed.

       TICKIT_BIND_DESTROY indicates that this handler should also be invoked at  the  time  that
       the bound object is being destroyed.

       TICKIT_BIND_ONESHOT  indicates that the handler should be invoke at-most once, and unbound
       the first time it is invoked. When invoked it will receive  both  the  TICKIT_EV_FIRE  and
       TICKIT_EV_UNBIND flags at once.

       Some  API  functions  take  or  return  the  following enum type, to represent a tri-state
       extended boolean concept of true, false, or some third condition  typically  indicating  a
       "don't  care"  or "unknown" state; the exact semantics will vary between specific uses and
       should be documented specifically.

       typedef enum {
         TICKIT_YES = 1,
         TICKIT_NO = 0,
         TICKIT_MAYBE = -1,
       } TickitMaybeBool;

       The various tickit_*_ctltype() and tickit_pen_attrtype(3) functions return  the  following
       enum type, to indicate what type of value each individual control or attribute takes.

       typedef enum {
         TICKIT_TYPE_NONE,
         TICKIT_TYPE_BOOL,
         TICKIT_TYPE_INT,
         TICKIT_TYPE_COLOUR,
       } TickitType;

COMMON EVENTS

       Every  object  instance  that  supports  events  supports  the following type of event, in
       addition to the specific ones listed for that kind of object:

       TICKIT_..._ON_DESTROY
              Invoked when the object instance is being destroyed. This will be the last time the
              application  can  use  the  stored  data  argument;  it  may  perform  any resource
              reclaiming operations that are required at this time.

EVENT FLAGS

       When an event handler function is invoked, it is passed a bitmask of flags to indicate the
       reason for its invocation.

       typedef enum {
         TICKIT_EV_FIRE,
         TICKIT_EV_UNBIND,
         TICKIT_EV_DESTROY,
       } TickitEventFlags;

       TICKIT_EV_FIRE
              This  handler  is being invoked because its associated event has occurred. The info
              pointer will point to a structure containing the relevant information.

       TICKIT_EV_UNBIND
              This handler is being invoked because it is being removed  from  the  object.  This
              will  only  be  observed if it was bound with the TICKIT_BIND_UNBIND flag. The info
              pointer will be NULL.

       TICKIT_EV_DESTROY
              This handler  is  being  invoked  because  the  object  instance  itself  is  being
              destroyed. This will be observed if it was bound with the TICKIT_BIND_DESTROY flag,
              or because it is bound to the TICKIT_..._ON_DESTROY event. The info pointer will be
              NULL.

              Any  event  handlers for this event will be invoked in reverse order; the newest is
              run first and the oldest last.

CONTROLS

       A toplevel instance has a number of runtime-configuration control options that affect  its
       behaviour.   These   can   be   set   using   tickit_setctl_int(3),   and   queried  using
       tickit_getctl_int(3). The individual controls have human-readable string names that can be
       obtained by tickit_ctlname(3) and searched by name using tickit_lookup_ctl(3). The type of
       a control option can be queried using tickit_ctltype(3).

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

       TICKIT_CTL_USE_ALTSCREEN (bool)
              The  value  is a boolean indicating whether the instance will activate the terminal
              alternate screen buffer mode when started.

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

TYPICAL STRUCTURE

COMMON TYPES

COMMON EVENTS

EVENT FLAGS

CONTROLS

SEE ALSO