| TICKIT_TERM(7) | Miscellaneous Information Manual | TICKIT_TERM(7) |
TickitTerm - abstraction of an interactive terminal
#include <tickit.h> typedef struct TickitTerm;
A TickitTerm instance represents an interactive user terminal. It provides functions to draw content to the terminal, and to accept input and other events from it. It supports a variety of modes of operation; allowing both synchronous and asynchronous filehandle IO, and working abstractly via byte buffers.
A new TickitTerm instance is created using the tickit_term_build(3). A terminal instance stores a reference count to make it easier for applications to manage the lifetime of terminals. A new terminal starts with reference count of one, and it can be adjusted using tickit_term_ref(3) and tickit_term_unref(3). When the count reaches zero the instance is destroyed.
The tickit_term_open_stdio(3) function offers a convenient shortcut to creating a new instance set up to represent the standard input and output streams of the process.
Once built the terminal startup actions are performed, and the tickit_term_await_started_msec(3) function can be used to wait until this is complete. A running instance can be paused using tickit_term_pause(3) and resumed using tickit_term_resume(3). It can be stopped entirely ahead of application termination by tickit_term_teardown(3).
It supports UTF-8 if enabled; either by detection of a UTF-8 locale, explicitly by calling tickit_term_set_utf8(3).
The size of the terminal can be queried using tickit_term_get_size(3), or forced to a given size by tickit_term_set_size(3). If the application is aware that the size of a terminal represented by a tty(7) filehandle has changed (for example due to receipt of a SIGWINCH signal), it can call tickit_term_refresh_size(3) to update it. The type of the terminal is set at construction time but can be queried later using tickit_term_get_termtype(3).
A terminal instance can be used for outputting drawing and other commands. For drawing, the functions tickit_term_print(3), tickit_term_goto(3), tickit_term_move(3), tickit_term_scrollrect(3), tickit_term_chpen(3), tickit_term_setpen(3), tickit_term_clear(3) and tickit_term_erasech(3) can be used. Additionally for setting modes, the function tickit_term_setctl_int(3) can be used. If an output buffer is defined it will need to be flushed when drawing is complete by calling tickit_term_flush(3).
Input via a filehandle can be received either synchronously by calling tickit_term_input_wait_msec(3), or asynchronously by calling tickit_term_input_readable(3) and tickit_term_input_check_timeout_msec(3). Any of these functions may cause one or more events to be raised by invoking event handler functions.
A terminal instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_term_bind_event(3) and removed using tickit_term_unbind_event_id(3).
Fake events can be artificially injected into the event handler chain, as if they had been received from the controlling terminal, by tickit_term_emit_key(3) and tickit_term_emit_mouse(3). These may be useful for testing, event capture-and-replay, or other specialised cases.
The event types recognised are:
typedef struct {
int lines;
int cols;
} TickitResizeEventInfo;
typedef struct {
TickitKeyEventType type;
int mod;
const char *str;
} TickitKeyEventInfo;
str will contain the name of the special key, including any applied modifiers, or a UTF-8 string of the Unicode character.
mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.
This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.
typedef struct {
TickitMouseEventType type;
int button;
int mod;
int line;
int col;
} TickitMouseEventInfo;
button gives the button index for button events, or one of TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.
line and col give the position of the mouse cursor for this event.
mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.
This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.
A terminal instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_term_setctl_int(3) and tickit_term_setctl_str(3), and queried using tickit_term_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_termctl_name(3) and searched by name using tickit_termctl_lookup(3). The type of a control option can be queried using tickit_termctl_type(3).
The options are given in an enumeration called
TickitTermCtl. The following control values are recognised: