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_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
29       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
33       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
40       It  supports  UTF-8  if enabled; either by detection of a UTF-8 locale,
41       explicitly by calling tickit_term_set_utf8(3).
42
43       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

OUTPUT

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

INPUT

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

EVENTS

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

CONTROLS

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
173       The  options are given in an enumeration called TickitTermCtl. The fol‐
174       lowing control values are recognised:
175
176       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
183       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
187              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
192       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
199       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
204              TICKIT_CURSORSHAPE_BLOCK
205                     A solid block filling the entire cell.
206
207              TICKIT_CURSORSHAPE_UNDER
208                     An underline below the character.
209
210              TICKIT_CURSORSHAPE_LEFT_BAR
211                     A vertical bar to the left of the character.
212
213              Note that not all terminals support setting this option, nor  to
214              all of the possible values.
215
216       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
224       TICKIT_TERMCTL_ICON_TEXT (str)
225              The value is a string for the terminal to use as  its  minimised
226              icon text.
227
228       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
232       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
239       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
243              BTICKIT_TERM_MOUSEMODE_CLICK
244                     Report button press and release events.
245
246              TICKIT_TERM_MOUSEMODE_DRAG
247                     Report  button  press  and  release  events, and movement
248                     while a button is held.
249
250              TICKIT_TERM_MOUSEMODE_MOVE
251                     Report all button press, release and motion  events  even
252                     with no buttons held.
253
254              TICKIT_TERM_MOUSEMODE_OFF
255                     Report nothing.
256
257       TICKIT_TERMCTL_TITLE_TEXT (str)
258              The value is a string for the terminal to use as its main window
259              title.
260

SEE ALSO

262       tickit(7), tickit_renderbuffer(7)
263
264
265
266                                                                TICKIT_TERM(7)
Impressum