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
20 regions that can be managed by different parts of the program struc‐
21 ture. Each window can react to input events such as keyboard or mouse
22 interaction.
23 As well as creating the initial root window, the toplevel Tickit
25 instance 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_new_stdio(3). A
32 toplevel instance stores a reference count to make it easier for appli‐
33 cations to manage its lifetime. A new toplevel instance starts with a
34 count of one, and it can be adjusted using tickit_ref(3) and
35 tickit_unref(3). When the count reaches zero the instance is destroyed.
36 The toplevel instance manages a tree of TickitWindow instances. The
38 root of this tree is obtained by tickit_get_rootwin(3) and thereafter
39 can be divided further by other functions on the window, described more
40 in tickit_window(7).
41 The TickitTerm instance behind the toplevel instance can be obtained by
43 tickit_get_term(3), and is described more in tickit_term(7).
44 Event handling callback functions can be installed to be called at a
46 later time, by using tickit_watch_timer_after_msec(3),
47 tickit_watch_timer_after_tv(3), or tickit_watch_later(3). The main IO
48 event loop is controlled using tickit_run(3) and tickit_stop(3).
49
51 A typical program using this library would start by creating the
52 toplevel instance, by calling tickit_new_stdio(3), then obtain its root
53 window on it by calling tickit_get_rootwin(3). This root window can
54 then be sub-divided into regions of interest by calling tickit_win‐
55 dow_new(3) to build a tree of windows. Window can then have some event
56 handlers attached by calling tickit_window_bind_event(3) - each window
57 will need to handle the TICKIT_WINDOW_ON_EXPOSE event, but might also
58 wish to handle other kinds like geometry change for dynamic resizing,
59 or keyboard or mouse to react to user input. Finally, once the intial
60 window tree is created, the program would enter the main event loop by
61 invoking tickit_run(3).
62
64 The flags argument to the various tickit_..._bind_event() functions
65 should be zero, or a bitmask of the following constants.
66 typedef enum {
68 TICKIT_BIND_FIRST,
69 TICKIT_BIND_UNBIND,
70 TICKIT_BIND_DESTROY,
71 } TickitBindFlags;
72 TICKIT_BIND_FIRST indicates that this handler should be inserted at the
75 start of the list, rather than the default position at the end.
76 TICKIT_BIND_UNBIND indicates that this handler should also be invoked
78 at the time it is unbound, either due to a specific call to the
79 tickit_..._unbind_event() function, or because the bound object is
80 being destroyed.
81 TICKIT_BIND_DESTROY indicates that this handler should also be invoked
83 at the time that the bound object is being destroyed.
84 Some API functions take or return the following enum type, to represent
86 a tri-state extended boolean concept of true, false, or some third con‐
87 dition typically indicating a "don't care" or "unknown" state; the
88 exact semantics will vary between specific uses and should be docu‐
89 mented specifically.
90 typedef enum {
92 TICKIT_YES = 1,
93 TICKIT_NO = 0,
94 TICKIT_MAYBE = -1,
95 } TickitMaybeBool;
96 The various tickit_*_ctltype() and tickit_pen_attrtype(3) functions
98 return the following enum type, to indicate what type of value each
99 individual control or attribute takes.
100 typedef enum {
102 TICKIT_TYPE_NONE,
103 TICKIT_TYPE_BOOL,
104 TICKIT_TYPE_INT,
105 TICKIT_TYPE_COLOUR,
106 } TickitType;
107
109 Every object instance that supports events supports the following type
110 of event, in addition to the specific ones listed for that kind of
111 object:
112 TICKIT_..._ON_DESTROY
114 Invoked when the object instance is being destroyed. This will
115 be the last time the application can use the stored data argu‐
116 ment; it may perform any resource reclaiming operations that are
117 required at this time.
118
120 When an event handler function is invoked, it is passed a bitmask of
121 flags to indicate the reason for its invocation.
122 typedef enum {
124 TICKIT_EV_FIRE,
125 TICKIT_EV_UNBIND,
126 TICKIT_EV_DESTROY,
127 } TickitEventFlags;
128 TICKIT_EV_FIRE
130 This handler is being invoked because its associated event has
131 occurred. The info pointer will point to a structure containing
132 the relevant information.
133 TICKIT_EV_UNBIND
135 This handler is being invoked because it is being removed from
136 the object. This will only be observed if it was bound with the
137 TICKIT_BIND_UNBIND flag. The info pointer will be NULL.
138 TICKIT_EV_DESTROY
140 This handler is being invoked because the object instance itself
141 is being destroyed. This will be observed if it was bound with
142 the TICKIT_BIND_DESTROY flag, or because it is bound to the
143 TICKIT_..._ON_DESTROY event. The info pointer will be NULL.
144 Any event handlers for this event will be invoked in reverse
146 order; the newest is run first and the oldest last.
147
149 A toplevel instance has a number of runtime-configuration control
150 options that affect its behaviour. These can be set using
151 tickit_setctl_int(3), and queried using tickit_getctl_int(3). The indi‐
152 vidual controls have human-readable string names that can be obtained
153 by tickit_ctlname(3) and searched by name using tickit_lookup_ctl(3).
154 The type of a control option can be queried using tickit_ctltype(3).
155 The options are given in an enumeration called TickitCtl. The following
157 control values are recognised:
158 TICKIT_CTL_USE_ALTSCREEN (bool)
160 The value is a boolean indicating whether the instance will
161 activate the terminal alternate screen buffer mode when started.
162
164 tickit_window(7), tickit_term(7), tickit_pen(7), tickit_rect(7),
165 tickit_rectset(7), tickit_renderbuffer(7), tickit_string(7),
166 tickit_utf8_count(3)
167 TICKIT(7)