NAME

SYNOPSIS

#include <tickit.h>

typedef struct TickitTerm;

DESCRIPTION

FUNCTIONS

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

OUTPUT

INPUT

EVENTS

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.

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.

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.

CONTROLS

The options are given in an enumeration called TickitTermCtl. The following control values are recognised:

TICKIT_TERMCTL_ALTSCREEN (bool)

The value is a boolean indicating whether the terminal alternate buffer mode should be enabled. When enabled, a temporary buffer is used for drawing, preserving the original contents of the screen. This mode is usually used by full-screen applications to preserve the shell's scrollback state.

TICKIT_TERMCTL_COLORS (int, read-only)

The value indicates how many colors are available. This value is read-only; it can be requested but not set.

On terminfo-driven terminals this will likely be 8, 16, or 256. On xterm-like terminals this will be 16,777,216 (i.e. 1 << 24) if the driver detects that the terminal supports 24-bit RGB8 ("true-color") palettes, or 256 if not.

TICKIT_TERMCTL_CURSORBLINK (bool)

The value is a boolean indicating whether the terminal text cursor should blink. When disabled, the cursor will appear in a steady state, if visible. When enabled, the cursor will appear blinking, if visible. If the cursor is invisible, this should not have any effect.

TICKIT_TERMCTL_CURSORSHAPE (int)

The value is an integer from the TickitCursorShape enumeration indicating what shape the terminal's text cursor should be. Values are:

Note that not all terminals support setting this option, nor to all of the possible values.

TICKIT_TERMCTL_CURSORVIS (bool)

The value is a boolean indicating whether the terminal text cursor should be visible. When disabled the cursor position is not visible. Typically applications will hide the cursor while performing redrawing operations so as not to show a flickering effect as the cursor moves, and show it again when drawing is complete.

TICKIT_TERMCTL_ICON_TEXT (str)

The value is a string for the terminal to use as its minimised icon text.

TICKIT_TERMCTL_ICONTITLE_TEXT (str)

The value is a string for the terminal to use as its minimised icon text and main window title.

TICKIT_TERMCTL_KEYPAD_APP (bool)

The value is a boolean controlling the terminal's keypad mode. When enabled, the terminal is in keypad application mode; in this mode the numerical keypad will send different sequences that can be detected as distinct from regular ASCII text. When disabled, the keypad will send normal text.

TICKIT_TERMCTL_MOUSE (int)

The value is an integer from the TickitTermMouseMode enumeration indicating what mouse events should be sent. Values are:

TICKIT_TERMCTL_TITLE_TEXT (str)

The value is a string for the terminal to use as its main window title.

SEE ALSO