1TICKIT(7)              Miscellaneous Information Manual              TICKIT(7)
2
3
4

NAME

6       tickit - Terminal Interface Construction KIT
7

SYNOPSIS

9       #include <tickit.h>
10
11       typedef struct Tickit;
12
13

DESCRIPTION

15       tickit  is a library for building full-screen interactive programs that
16       use a terminal interface. A program using this library would  start  by
17       creating  a  toplevel Tickit instance, from which one or more divisions
18       of the terminal area,  called  "windows"  are  created.  These  form  a
19       heirarchial  tree that subdivides the content area into independent re‐
20       gions that can be managed by different parts of the program  structure.
21       Each  window can react to input events such as keyboard or mouse inter‐
22       action.
23
24       As well as creating the initial root window, the  toplevel  Tickit  in‐
25       stance  also  performs  a few other jobs for the containing program. It
26       can act as a containing event loop for the program, performing IO  mul‐
27       tiplexing  tasks  both for tickit's own needs and the needs of the pro‐
28       gram as a whole.
29

FUNCTIONS

31       A  new  toplevel  instance  is  created   by   using   tickit_build(3),
32       tickit_new_stdio(3) or tickit_new_stdtty(3). A toplevel instance stores
33       a reference count to make it easier  for  applications  to  manage  its
34       lifetime.  A  new  toplevel instance starts with a count of one, and it
35       can be adjusted using tickit_ref(3) and tickit_unref(3). When the count
36       reaches zero the instance is destroyed.
37
38       The  toplevel  instance  manages  a tree of TickitWindow instances. The
39       root of this tree is obtained by tickit_get_rootwin(3)  and  thereafter
40       can be divided further by other functions on the window, described more
41       in tickit_window(7).
42
43       The TickitTerm instance behind the toplevel instance can be obtained by
44       tickit_get_term(3), and is described more in tickit_term(7).
45
46       Event  handling  callback  functions can be installed to be called at a
47       later  time,  by   using   tickit_watch_io(3),   tickit_watch_timer_af‐
48       ter_msec(3),   tickit_watch_timer_after_tv(3),   tickit_watch_later(3),
49       tickit_watch_signal(3) or tickit_watch_process(3). The  main  IO  event
50       loop is controlled using tickit_run(3) and tickit_stop(3).
51
52       The  compile-time  and run-time version of the library can be inspected
53       using the macros and functions described in tickit_version(7).
54

TYPICAL STRUCTURE

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

COMMON TYPES

69       The flags argument to  the  various  tickit_..._bind_event()  functions
70       should be zero, or a bitmask of the following constants.
71
72       typedef enum {
73         TICKIT_BIND_FIRST,
74         TICKIT_BIND_UNBIND,
75         TICKIT_BIND_DESTROY,
76         TICKIT_BIND_ONESHOT,
77       } TickitBindFlags;
78
79
80       TICKIT_BIND_FIRST indicates that this handler should be inserted at the
81       start of the list, rather than the default position at the end.
82
83       TICKIT_BIND_UNBIND indicates that this handler should also  be  invoked
84       at  the  time  it  is  unbound,  either  due  to a specific call to the
85       tickit_..._unbind_event() function, or because the bound object is  be‐
86       ing destroyed.
87
88       TICKIT_BIND_DESTROY  indicates that this handler should also be invoked
89       at the time that the bound object is being destroyed.
90
91       TICKIT_BIND_ONESHOT indicates that the handler should be invoke at-most
92       once,  and  unbound  the first time it is invoked. When invoked it will
93       receive both the TICKIT_EV_FIRE and TICKIT_EV_UNBIND flags at once.
94
95       Some API functions take or return the following enum type, to represent
96       a tri-state extended boolean concept of true, false, or some third con‐
97       dition typically indicating a "don't care" or "unknown" state; the  ex‐
98       act  semantics will vary between specific uses and should be documented
99       specifically.
100
101       typedef enum {
102         TICKIT_YES = 1,
103         TICKIT_NO = 0,
104         TICKIT_MAYBE = -1,
105       } TickitMaybeBool;
106
107       The various tickit_*_ctltype() and tickit_pen_attrtype(3) functions re‐
108       turn the following enum type, to indicate what type of value each indi‐
109       vidual control or attribute takes.
110
111       typedef enum {
112         TICKIT_TYPE_NONE,
113         TICKIT_TYPE_BOOL,
114         TICKIT_TYPE_INT,
115         TICKIT_TYPE_COLOUR,
116       } TickitType;
117

COMMON EVENTS

119       Every object instance that supports events supports the following  type
120       of  event, in addition to the specific ones listed for that kind of ob‐
121       ject:
122
123       TICKIT_..._ON_DESTROY
124              Invoked when the object instance is being destroyed.  This  will
125              be  the  last time the application can use the stored data argu‐
126              ment; it may perform any resource reclaiming operations that are
127              required at this time.
128

EVENT FLAGS

130       When  an  event  handler function is invoked, it is passed a bitmask of
131       flags to indicate the reason for its invocation.
132
133       typedef enum {
134         TICKIT_EV_FIRE,
135         TICKIT_EV_UNBIND,
136         TICKIT_EV_DESTROY,
137       } TickitEventFlags;
138
139       TICKIT_EV_FIRE
140              This handler is being invoked because its associated  event  has
141              occurred.  The info pointer will point to a structure containing
142              the relevant information.
143
144       TICKIT_EV_UNBIND
145              This handler is being invoked because it is being  removed  from
146              the  object. This will only be observed if it was bound with the
147              TICKIT_BIND_UNBIND flag. The info pointer will be NULL.
148
149       TICKIT_EV_DESTROY
150              This handler is being invoked because the object instance itself
151              is  being  destroyed. This will be observed if it was bound with
152              the TICKIT_BIND_DESTROY flag, or because  it  is  bound  to  the
153              TICKIT_..._ON_DESTROY event. The info pointer will be NULL.
154
155              Any event handlers for this event will be invoked in reverse or‐
156              der; the newest is run first and the oldest last.
157

CONTROLS

159       A toplevel instance has a number of runtime-configuration  control  op‐
160       tions   that   affect   its   behaviour.   These   can   be  set  using
161       tickit_setctl_int(3), and queried using tickit_getctl_int(3). The indi‐
162       vidual  controls  have human-readable string names that can be obtained
163       by tickit_ctlname(3) and searched by name  using  tickit_lookup_ctl(3).
164       The type of a control option can be queried using tickit_ctltype(3).
165
166       The options are given in an enumeration called TickitCtl. The following
167       control values are recognised:
168
169       TICKIT_CTL_USE_ALTSCREEN (bool)
170              The value is a boolean indicating whether the instance will  ac‐
171              tivate the terminal alternate screen buffer mode when started.
172

SEE ALSO

174       tickit_window(7),    tickit_term(7),   tickit_pen(7),   tickit_rect(7),
175       tickit_rectset(7),      tickit_renderbuffer(7),       tickit_string(7),
176       tickit_utf8_count(3), tickit_version(7)
177
178
179
180                                                                     TICKIT(7)
Impressum