1TICKIT_TERM(7) Miscellaneous Information Manual TICKIT_TERM(7)
2
6 TickitTerm - abstraction of an interactive terminal
7
9 #include <tickit.h>
10 typedef struct TickitTerm;
12
15 A TickitTerm instance represents an interactive user terminal. It pro‐
16 vides functions to draw content to the terminal, and to accept input
17 and other events from it. It supports a variety of modes of operation;
18 allowing both synchronous and asynchronous filehandle IO, and working
19 abstractly via byte buffers.
20
22 A new TickitTerm instance is created using the tickit_term_build(3). A
23 terminal instance stores a reference count to make it easier for appli‐
24 cations to manage the lifetime of terminals. A new terminal starts with
25 reference count of one, and it can be adjusted using tickit_term_ref(3)
26 and tickit_term_unref(3). When the count reaches zero the instance is
27 destroyed.
28 The tickit_term_open_stdio(3) function offers a convenient shortcut to
30 creating a new instance set up to represent the standard input and out‐
31 put streams of the process.
32 Once built the terminal startup actions are performed, and the
34 tickit_term_await_started_msec(3) function can be used to wait until
35 this is complete. A running instance can be paused using
36 tickit_term_pause(3) and resumed using tickit_term_resume(3). It can be
37 stopped entirely ahead of application termination by tickit_term_tear‐
38 down(3).
39 It supports UTF-8 if enabled; either by detection of a UTF-8 locale,
41 explicitly by calling tickit_term_set_utf8(3).
42 The size of the terminal can be queried using tickit_term_get_size(3),
44 or forced to a given size by tickit_term_set_size(3). If the applica‐
45 tion is aware that the size of a terminal represented by a tty(7) file‐
46 handle has changed (for example due to receipt of a SIGWINCH signal),
47 it can call tickit_term_refresh_size(3) to update it. The type of the
48 terminal is set at construction time but can be queried later using
49 tickit_term_get_termtype(3).
50
52 A terminal instance can be used for outputting drawing and other com‐
53 mands. For drawing, the functions tickit_term_print(3),
54 tickit_term_goto(3), tickit_term_move(3), tickit_term_scrollrect(3),
55 tickit_term_chpen(3), tickit_term_setpen(3), tickit_term_clear(3) and
56 tickit_term_erasech(3) can be used. Additionally for setting modes, the
57 function tickit_term_setctl_int(3) can be used. If an output buffer is
58 defined it will need to be flushed when drawing is complete by calling
59 tickit_term_flush(3).
60
62 Input via a filehandle can be received either synchronously by calling
63 tickit_term_input_wait_msec(3), or asynchronously by calling
64 tickit_term_input_readable(3) and tickit_term_input_check_time‐
65 out_msec(3). Any of these functions may cause one or more events to be
66 raised by invoking event handler functions.
67
69 A terminal instance stores a list of event handlers. Each event handler
70 is associated with one event type and stores a function pointer, and an
71 arbitrary pointer containing user data. Event handlers may be installed
72 using tickit_term_bind_event(3) and removed using tickit_term_un‐
73 bind_event_id(3).
74 Fake events can be artificially injected into the event handler chain,
76 as if they had been received from the controlling terminal, by
77 tickit_term_emit_key(3) and tickit_term_emit_mouse(3). These may be
78 useful for testing, event capture-and-replay, or other specialised
79 cases.
80 The event types recognised are:
82 TICKIT_TERM_ON_DESTROY
84 The terminal instance is being destroyed.
85 TICKIT_TERM_ON_RESIZE
87 The terminal has been resized. info will point to a structure
88 defined as:
89 typedef struct {
91 int lines;
92 int cols;
93 } TickitResizeEventInfo;
94 TICKIT_TERM_ON_KEY
96 A key has been pressed on the keyboard. info will point to a
97 structure defined as:
98 typedef struct {
100 TickitKeyEventType type;
101 int mod;
102 const char *str;
103 } TickitKeyEventInfo;
104 type is an enumeration that gives the specific type of key
106 event.
107 TICKIT_KEYEV_KEY
109 a cursor control, arrow key, or function key. i.e. any of
110 the keys that don't directly produce text.
111 TICKIT_KEYEV_TEXT
113 regular Unicode characters.
114 str will contain the name of the special key, including any applied
116 modifiers, or a UTF-8 string of the Unicode character.
117 mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and
119 TICKIT_MOD_CTRL.
120 This event only runs until a bound function returns a true value; this
122 prevents later handler functions from observing it.
123 TICKIT_TERM_ON_MOUSE
125 A mouse button has been pressed or released, the mouse cursor
126 moved while dragging a button, or the wheel has been scrolled.
127 info will point to a structure defined as:
128 typedef struct {
130 TickitMouseEventType type;
131 int button;
132 int mod;
133 int line;
134 int col;
135 } TickitMouseEventInfo;
136 type is an enumeration that gives the specific type of mouse
138 event.
139 TICKIT_MOUSEEV_PRESS
141 A mouse button has been pressed.
142 TICKIT_MOUSEEV_DRAG
144 The mouse has been moved while a button is being held
145 down.
146 TICKIT_MOUSEEV_RELEASE
148 A mouse button has been released.
149 TICKIT_MOUSEEV_WHEEL
151 The wheel has been rolled.
152 button gives the button index for button events, or one of
154 TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.
155 line and col give the position of the mouse cursor for this event.
157 mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and
159 TICKIT_MOD_CTRL.
160 This event only runs until a bound function returns a true value; this
162 prevents later handler functions from observing it.
163
165 A terminal instance has a number of runtime-configuration control op‐
166 tions that affect its behaviour. These can be set using
167 tickit_term_setctl_int(3) and tickit_term_setctl_str(3), and queried
168 using tickit_term_getctl_int(3). The individual controls have human-
169 readable string names that can be obtained by tickit_term_ctlname(3)
170 and searched by name using tickit_term_lookup_ctl(3). The type of a
171 control option can be queried using tickit_term_ctltype(3).
172 The options are given in an enumeration called TickitTermCtl. The fol‐
174 lowing control values are recognised:
175 TICKIT_TERMCTL_ALTSCREEN (bool)
177 The value is a boolean indicating whether the terminal alternate
178 buffer mode should be enabled. When enabled, a temporary buffer
179 is used for drawing, preserving the original contents of the
180 screen. This mode is usually used by full-screen applications to
181 preserve the shell's scrollback state.
182 TICKIT_TERMCTL_COLORS (int, read-only)
184 The value indicates how many colors are available. This value is
185 read-only; it can be requested but not set.
186 On terminfo-driven terminals this will likely be 8, 16, or 256.
188 On xterm-like terminals this will be 16,777,216 (i.e. 1 << 24)
189 if the driver detects that the terminal supports 24-bit RGB8
190 ("true-color") palettes, or 256 if not.
191 TICKIT_TERMCTL_CURSORBLINK (bool)
193 The value is a boolean indicating whether the terminal text cur‐
194 sor should blink. When disabled, the cursor will appear in a
195 steady state, if visible. When enabled, the cursor will appear
196 blinking, if visible. If the cursor is invisible, this should
197 not have any effect.
198 TICKIT_TERMCTL_CURSORSHAPE (int)
200 The value is an integer from the TickitCursorShape enumeration
201 indicating what shape the terminal's text cursor should be. Val‐
202 ues are:
203 TICKIT_CURSORSHAPE_BLOCK
205 A solid block filling the entire cell.
206 TICKIT_CURSORSHAPE_UNDER
208 An underline below the character.
209 TICKIT_CURSORSHAPE_LEFT_BAR
211 A vertical bar to the left of the character.
212 Note that not all terminals support setting this option, nor to
214 all of the possible values.
215 TICKIT_TERMCTL_CURSORVIS (bool)
217 The value is a boolean indicating whether the terminal text cur‐
218 sor should be visible. When disabled the cursor position is not
219 visible. Typically applications will hide the cursor while per‐
220 forming redrawing operations so as not to show a flickering ef‐
221 fect as the cursor moves, and show it again when drawing is com‐
222 plete.
223 TICKIT_TERMCTL_ICON_TEXT (str)
225 The value is a string for the terminal to use as its minimised
226 icon text.
227 TICKIT_TERMCTL_ICONTITLE_TEXT (str)
229 The value is a string for the terminal to use as its minimised
230 icon text and main window title.
231 TICKIT_TERMCTL_KEYPAD_APP (bool)
233 The value is a boolean controlling the terminal's keypad mode.
234 When enabled, the terminal is in keypad application mode; in
235 this mode the numerical keypad will send different sequences
236 that can be detected as distinct from regular ASCII text. When
237 disabled, the keypad will send normal text.
238 TICKIT_TERMCTL_MOUSE (int)
240 The value is an integer from the TickitTermMouseMode enumeration
241 indicating what mouse events should be sent. Values are:
242 BTICKIT_TERM_MOUSEMODE_CLICK
244 Report button press and release events.
245 TICKIT_TERM_MOUSEMODE_DRAG
247 Report button press and release events, and movement
248 while a button is held.
249 TICKIT_TERM_MOUSEMODE_MOVE
251 Report all button press, release and motion events even
252 with no buttons held.
253 TICKIT_TERM_MOUSEMODE_OFF
255 Report nothing.
256 TICKIT_TERMCTL_TITLE_TEXT (str)
258 The value is a string for the terminal to use as its main window
259 title.
260
262 tickit(7), tickit_renderbuffer(7)
263 TICKIT_TERM(7)