Provided by: libtickit-dev_0.3.4-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_new_stdio(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_timer_after_msec(3), tickit_watch_timer_after_tv(3), or
tickit_watch_later(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_stdio(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 intial 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,
} 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.
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.
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)