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

NAME

6       TickitTerm - abstraction of an interactive terminal
7

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONS

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
30       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
34       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
48       It  supports  UTF-8  if enabled; either by detection of a UTF-8 locale,
49       explicitly by calling tickit_term_set_utf8(3).
50
51       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

OUTPUT

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

INPUT

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

EVENTS

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
83       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
89       The event types recognised are:
90
91       TICKIT_TERM_ON_DESTROY
92              The terminal instance is being destroyed.
93
94       TICKIT_TERM_ON_RESIZE
95              The  terminal  has  been resized. info will point to a structure
96              defined as:
97
98              typedef struct {
99                  int lines;
100                  int cols;
101              } TickitResizeEventInfo;
102
103       TICKIT_TERM_ON_KEY
104              A key has been pressed on the keyboard. info  will  point  to  a
105              structure defined as:
106
107              typedef struct {
108                  TickitKeyEventType type;
109                  int mod;
110                  const char *str;
111              } TickitKeyEventInfo;
112
113              type  is  an  enumeration  that  gives  the specific type of key
114              event.
115
116              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
120              TICKIT_KEYEV_TEXT
121                     regular Unicode characters.
122
123       str  will  contain  the  name of the special key, including any applied
124       modifiers, or a UTF-8 string of the Unicode character.
125
126       mod will contain a  bitmask  of  TICKIT_MOD_SHIFT,  TICKIT_MOD_ALT  and
127       TICKIT_MOD_CTRL.
128
129       This  event only runs until a bound function returns a true value; this
130       prevents later handler functions from observing it.
131
132       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
137              typedef struct {
138                  TickitMouseEventType type;
139                  int button;
140                  int mod;
141                  int line;
142                  int col;
143              } TickitMouseEventInfo;
144
145              type is an enumeration that gives the  specific  type  of  mouse
146              event.
147
148              TICKIT_MOUSEEV_PRESS
149                     A mouse button has been pressed.
150
151              TICKIT_MOUSEEV_DRAG
152                     The  mouse  has  been  moved while a button is being held
153                     down.
154
155              TICKIT_MOUSEEV_RELEASE
156                     A mouse button has been released.
157
158              TICKIT_MOUSEEV_WHEEL
159                     The wheel has been rolled.
160
161       button  gives  the  button  index  for  button  events,   or   one   of
162       TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.
163
164       line and col give the position of the mouse cursor for this event.
165
166       mod  will  contain  a  bitmask  of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and
167       TICKIT_MOD_CTRL.
168
169       This event only runs until a bound function returns a true value;  this
170       prevents later handler functions from observing it.
171

CONTROLS

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
181       The  options are given in an enumeration called TickitTermCtl. The fol‐
182       lowing control values are recognised:
183
184       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
191       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
195              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
200       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
207       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
212              TICKIT_CURSORSHAPE_BLOCK
213                     A solid block filling the entire cell.
214
215              TICKIT_CURSORSHAPE_UNDER
216                     An underline below the character.
217
218              TICKIT_CURSORSHAPE_LEFT_BAR
219                     A vertical bar to the left of the character.
220
221              Note that not all terminals support setting this option, nor  to
222              all of the possible values.
223
224       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
232       TICKIT_TERMCTL_ICON_TEXT (str)
233              The value is a string for the terminal to use as  its  minimised
234              icon text.
235
236       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
240       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
247       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
251              BTICKIT_TERM_MOUSEMODE_CLICK
252                     Report button press and release events.
253
254              TICKIT_TERM_MOUSEMODE_DRAG
255                     Report  button  press  and  release  events, and movement
256                     while a button is held.
257
258              TICKIT_TERM_MOUSEMODE_MOVE
259                     Report all button press, release and motion  events  even
260                     with no buttons held.
261
262              TICKIT_TERM_MOUSEMODE_OFF
263                     Report nothing.
264
265       TICKIT_TERMCTL_TITLE_TEXT (str)
266              The value is a string for the terminal to use as its main window
267              title.
268

SEE ALSO

270       tickit(7), tickit_renderbuffer(7)
271
272
273
274                                                                TICKIT_TERM(7)
Impressum