LeoNerd.org.uk

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.

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 set of event handlers. Each event handler consists of a bitmask of one or more event types it is interested in, 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_EV_RESIZE
The terminal has been resized. info will point to a structure defined as:
typedef struct {
    int lines;
    int cols;
} TickitResizeEventInfo;
TICKIT_EV_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;
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-8string 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 preventslater handler functions from observing it.
TICKIT_EV_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;
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. 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 preventslater handler functions from observing it.

SEE ALSO

tickit(7), tickit_renderbuffer(7)