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_*ctl_type() 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_ctl_name(3) and searched by name
       using tickit_ctl_lookup(3). The type of a control option can be queried using tickit_ctl_type(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.

SEE ALSO

       tickit_window(7),       tickit_term(7),       tickit_pen(7),      tickit_rect(7),      tickit_rectset(7),
       tickit_renderbuffer(7), tickit_string(7), tickit_utf8_count(3), tickit_version(7)

                                                                                                       TICKIT(7)