DOKK / manpages / debian 10 / libtickit-dev / tickit_term.7.en
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_new(3) or tickit_term_new_for_termtype(3) functions. 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.

A terminal instance will need either an output function or an output filehandle set before it can send output. This can be performed by either tickit_term_set_output_func(3) or tickit_term_set_output_fd(3). An output buffer can be defined by tickit_term_set_output_buffer(3). If output is via a filehandle, then the size of that will be queried if it is a TTY. If output is via an output function only then the size must be set using tickit_term_set_size(3). An input filehandle can be set using tickit_term_set_input_fd(3), or input can be sent from a byte buffer using tickit_term_input_push_bytes(3). Once input and output methods are set 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 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).

Once an output method is defined, 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:

The terminal instance is being destroyed.
The terminal has been resized. info will point to a structure defined as:

typedef struct {
    int lines;
    int cols;
} TickitResizeEventInfo;
    
A key has been pressed on the keyboard. info will point to a structure defined as:

typedef struct {
    TickitKeyEventType type;
    int mod;
    const char *str;
} TickitKeyEventInfo;
    
type is an enumeration that gives the specific type of key event.
a cursor control, arrow key, or function key. i.e. any of the keys that don't directly produce text.
regular Unicode characters.

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.

A mouse button has been pressed or released, the mouse cursor moved while dragging a button, or the wheel has been scrolled. info will point to a structure defined as:

typedef struct {
    TickitMouseEventType type;
    int button;
    int mod;
    int line;
    int col;
} TickitMouseEventInfo;
    
type is an enumeration that gives the specific type of mouse event.
A mouse button has been pressed.
The mouse has been moved while a button is being held down.
A mouse button has been released.
The wheel has been rolled.

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.

tickit(7), tickit_renderbuffer(7)