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_new(3) or
23 tickit_term_new_for_termtype(3) functions. A terminal instance stores a
24 reference count to make it easier for applications to manage the life‐
25 time of terminals. A new terminal starts with reference count of one,
26 and it can be adjusted using tickit_term_ref(3) and
27 tickit_term_unref(3). When the count reaches zero the instance is
28 destroyed.
29 The tickit_term_open_stdio(3) function offers a convenient shortcut to
31 creating a new instance set up to represent the standard input and out‐
32 put streams of the process.
33 A terminal instance will need either an output function or an output
35 filehandle set before it can send output. This can be performed by
36 either tickit_term_set_output_func(3) or tickit_term_set_output_fd(3).
37 An output buffer can be defined by tickit_term_set_output_buffer(3). If
38 output is via a filehandle, then the size of that will be queried if it
39 is a TTY. If output is via an output function only then the size must
40 be set using tickit_term_set_size(3). An input filehandle can be set
41 using tickit_term_set_input_fd(3), or input can be sent from a byte
42 buffer using tickit_term_input_push_bytes(3). Once input and output
43 methods are set the terminal startup actions are performed, and the
44 tickit_term_await_started_msec(3) function can be used to wait until
45 this is complete. A running instance can be paused using
46 tickit_term_pause(3) and resumed using tickit_term_resume(3).
47 It supports UTF-8 if enabled; either by detection of a UTF-8 locale,
49 explicitly by calling tickit_term_set_utf8(3).
50 The size of the terminal can be queried using tickit_term_get_size(3),
52 or forced to a given size by tickit_term_set_size(3). If the applica‐
53 tion is aware that the size of a terminal represented by a tty(7) file‐
54 handle has changed (for example due to receipt of a SIGWINCH signal),
55 it can call tickit_term_refresh_size(3) to update it. The type of the
56 terminal is set at construction time but can be queried later using
57 tickit_term_get_termtype(3).
58
60 Once an output method is defined, a terminal instance can be used for
61 outputting drawing and other commands. For drawing, the functions
62 tickit_term_print(3), tickit_term_goto(3), tickit_term_move(3),
63 tickit_term_scrollrect(3), tickit_term_chpen(3), tickit_term_setpen(3),
64 tickit_term_clear(3) and tickit_term_erasech(3) can be used. Addition‐
65 ally for setting modes, the function tickit_term_setctl_int(3) can be
66 used. If an output buffer is defined it will need to be flushed when
67 drawing is complete by calling tickit_term_flush(3).
68
70 Input via a filehandle can be received either synchronously by calling
71 tickit_term_input_wait_msec(3), or asynchronously by calling
72 tickit_term_input_readable(3) and tickit_term_input_check_time‐
73 out_msec(3). Any of these functions may cause one or more events to be
74 raised by invoking event handler functions.
75
77 A terminal instance stores a list of event handlers. Each event handler
78 is associated with one event type and stores a function pointer, and an
79 arbitrary pointer containing user data. Event handlers may be installed
80 using tickit_term_bind_event(3) and removed using
81 tickit_term_unbind_event_id(3).
82 Fake events can be artificially injected into the event handler chain,
84 as if they had been received from the controlling terminal, by
85 tickit_term_emit_key(3) and tickit_term_emit_mouse(3). These may be
86 useful for testing, event capture-and-replay, or other specialised
87 cases.
88 The event types recognised are:
90 TICKIT_TERM_ON_DESTROY
92 The terminal instance is being destroyed.
93 TICKIT_TERM_ON_RESIZE
95 The terminal has been resized. info will point to a structure
96 defined as:
97 typedef struct {
99 int lines;
100 int cols;
101 } TickitResizeEventInfo;
102 TICKIT_TERM_ON_KEY
104 A key has been pressed on the keyboard. info will point to a
105 structure defined as:
106 typedef struct {
108 TickitKeyEventType type;
109 int mod;
110 const char *str;
111 } TickitKeyEventInfo;
112 type is an enumeration that gives the specific type of key
114 event.
115 TICKIT_KEYEV_KEY
117 a cursor control, arrow key, or function key. i.e. any of
118 the keys that don't directly produce text.
119 TICKIT_KEYEV_TEXT
121 regular Unicode characters.
122 str will contain the name of the special key, including any applied
124 modifiers, or a UTF-8 string of the Unicode character.
125 mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and
127 TICKIT_MOD_CTRL.
128 This event only runs until a bound function returns a true value; this
130 prevents later handler functions from observing it.
131 TICKIT_TERM_ON_MOUSE
133 A mouse button has been pressed or released, the mouse cursor
134 moved while dragging a button, or the wheel has been scrolled.
135 info will point to a structure defined as:
136 typedef struct {
138 TickitMouseEventType type;
139 int button;
140 int mod;
141 int line;
142 int col;
143 } TickitMouseEventInfo;
144 type is an enumeration that gives the specific type of mouse
146 event.
147 TICKIT_MOUSEEV_PRESS
149 A mouse button has been pressed.
150 TICKIT_MOUSEEV_DRAG
152 The mouse has been moved while a button is being held
153 down.
154 TICKIT_MOUSEEV_RELEASE
156 A mouse button has been released.
157 TICKIT_MOUSEEV_WHEEL
159 The wheel has been rolled.
160 button gives the button index for button events, or one of
162 TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.
163 line and col give the position of the mouse cursor for this event.
165 mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and
167 TICKIT_MOD_CTRL.
168 This event only runs until a bound function returns a true value; this
170 prevents later handler functions from observing it.
171
173 A terminal instance has a number of runtime-configuration control
174 options that affect its behaviour. These can be set using
175 tickit_term_setctl_int(3) and tickit_term_setctl_str(3), and queried
176 using tickit_term_getctl_int(3). The individual controls have human-
177 readable string names that can be obtained by tickit_term_ctlname(3)
178 and searched by name using tickit_term_lookup_ctl(3). The type of a
179 control option can be queried using tickit_term_ctltype(3).
180 The options are given in an enumeration called TickitTermCtl. The fol‐
182 lowing control values are recognised:
183 TICKIT_TERMCTL_ALTSCREEN (bool)
185 The value is a boolean indicating whether the terminal alternate
186 buffer mode should be enabled. When enabled, a temporary buffer
187 is used for drawing, preserving the original contents of the
188 screen. This mode is usually used by full-screen applications to
189 preserve the shell's scrollback state.
190 TICKIT_TERMCTL_COLORS (int, read-only)
192 The value indicates how many colors are available. This value is
193 read-only; it can be requested but not set.
194 On terminfo-driven terminals this will likely be 8, 16, or 256.
196 On xterm-like terminals this will be 16,777,216 (i.e. 1 << 24)
197 if the driver detects that the terminal supports 24-bit RGB8
198 ("true-color") palettes, or 256 if not.
199 TICKIT_TERMCTL_CURSORBLINK (bool)
201 The value is a boolean indicating whether the terminal text cur‐
202 sor should blink. When disabled, the cursor will appear in a
203 steady state, if visible. When enabled, the cursor will appear
204 blinking, if visible. If the cursor is invisible, this should
205 not have any effect.
206 TICKIT_TERMCTL_CURSORSHAPE (int)
208 The value is an integer from the TickitCursorShape enumeration
209 indicating what shape the terminal's text cursor should be. Val‐
210 ues are:
211 TICKIT_CURSORSHAPE_BLOCK
213 A solid block filling the entire cell.
214 TICKIT_CURSORSHAPE_UNDER
216 An underline below the character.
217 TICKIT_CURSORSHAPE_LEFT_BAR
219 A vertical bar to the left of the character.
220 Note that not all terminals support setting this option, nor to
222 all of the possible values.
223 TICKIT_TERMCTL_CURSORVIS (bool)
225 The value is a boolean indicating whether the terminal text cur‐
226 sor should be visible. When disabled the cursor position is not
227 visible. Typically applications will hide the cursor while per‐
228 forming redrawing operations so as not to show a flickering
229 effect as the cursor moves, and show it again when drawing is
230 complete.
231 TICKIT_TERMCTL_ICON_TEXT (str)
233 The value is a string for the terminal to use as its minimised
234 icon text.
235 TICKIT_TERMCTL_ICONTITLE_TEXT (str)
237 The value is a string for the terminal to use as its minimised
238 icon text and main window title.
239 TICKIT_TERMCTL_KEYPAD_APP (bool)
241 The value is a boolean controlling the terminal's keypad mode.
242 When enabled, the terminal is in keypad application mode; in
243 this mode the numerical keypad will send different sequences
244 that can be detected as distinct from regular ASCII text. When
245 disabled, the keypad will send normal text.
246 TICKIT_TERMCTL_MOUSE (int)
248 The value is an integer from the TickitTermMouseMode enumeration
249 indicating what mouse events should be sent. Values are:
250 BTICKIT_TERM_MOUSEMODE_CLICK
252 Report button press and release events.
253 TICKIT_TERM_MOUSEMODE_DRAG
255 Report button press and release events, and movement
256 while a button is held.
257 TICKIT_TERM_MOUSEMODE_MOVE
259 Report all button press, release and motion events even
260 with no buttons held.
261 TICKIT_TERM_MOUSEMODE_OFF
263 Report nothing.
264 TICKIT_TERMCTL_TITLE_TEXT (str)
266 The value is a string for the terminal to use as its main window
267 title.
268
270 tickit(7), tickit_renderbuffer(7)
271 TICKIT_TERM(7)