TICKIT_TERM(7)

Miscellaneous Information Manual

TICKIT_TERM(7)

NAME¶

TickitTerm - abstraction of an interactive terminal

SYNOPSIS¶

#include <tickit.h>

typedef struct TickitTerm;

DESCRIPTION¶

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.

FUNCTIONS¶

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).

OUTPUT¶

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¶

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.

EVENTS¶

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:

TICKIT_TERM_ON_DESTROY

The terminal instance is being destroyed.

TICKIT_TERM_ON_RESIZE

The terminal has been resized. info will point to a structure defined as:

typedef struct {
    int lines;
    int cols;
} TickitResizeEventInfo;

TICKIT_TERM_ON_KEY

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.

TICKIT_KEYEV_KEY: a cursor control, arrow key, or function key. i.e. any of the keys that don't directly produce text.
TICKIT_KEYEV_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.

TICKIT_TERM_ON_MOUSE

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.

TICKIT_MOUSEEV_PRESS: A mouse button has been pressed.
TICKIT_MOUSEEV_DRAG: The mouse has been moved while a button is being held down.
TICKIT_MOUSEEV_RELEASE: A mouse button has been released.
TICKIT_MOUSEEV_WHEEL: 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.