1TICKIT(7) Miscellaneous Information Manual TICKIT(7)
2
6 tickit - Terminal Interface Construction KIT
7
9 #include <tickit.h>
10 typedef struct Tickit;
12
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 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
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 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 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 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 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
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
69 The flags argument to the various tickit_..._bind_event() functions
70 should be zero, or a bitmask of the following constants.
71 typedef enum {
73 TICKIT_BIND_FIRST,
74 TICKIT_BIND_UNBIND,
75 TICKIT_BIND_DESTROY,
76 TICKIT_BIND_ONESHOT,
77 } TickitBindFlags;
78 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 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 TICKIT_BIND_DESTROY indicates that this handler should also be invoked
89 at the time that the bound object is being destroyed.
90 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 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 typedef enum {
102 TICKIT_YES = 1,
103 TICKIT_NO = 0,
104 TICKIT_MAYBE = -1,
105 } TickitMaybeBool;
106 The various tickit_*ctl_type() 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 typedef enum {
112 TICKIT_TYPE_NONE,
113 TICKIT_TYPE_BOOL,
114 TICKIT_TYPE_INT,
115 TICKIT_TYPE_COLOUR,
116 } TickitType;
117
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 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
130 When an event handler function is invoked, it is passed a bitmask of
131 flags to indicate the reason for its invocation.
132 typedef enum {
134 TICKIT_EV_FIRE,
135 TICKIT_EV_UNBIND,
136 TICKIT_EV_DESTROY,
137 } TickitEventFlags;
138 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 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 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 Any event handlers for this event will be invoked in reverse or‐
156 der; the newest is run first and the oldest last.
157
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_ctl_name(3) and searched by name using tickit_ctl_lookup(3).
164 The type of a control option can be queried using tickit_ctl_type(3).
165 The options are given in an enumeration called TickitCtl. The following
167 control values are recognised:
168 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
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 TICKIT(7)