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_build(3). A ter- minal 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 de- stroyed. The tickit_term_open_stdio(3) function offers a convenient shortcut to cre- ating 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, ex- plicitly 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 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 invok- ing 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 arbi- trary 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 de- fined 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 struc- ture 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 modi- fiers, 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 pre- vents 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_MOUSE- WHEEL_UP, TICKIT_MOUSEWHEEL_DOWN, TICKIT_MOUSEWHEEL_LEFT or TICKIT_MOUSE- WHEEL_RIGHT 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 pre- vents later handler functions from observing it. CONTROLS 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 ob- tained by tickit_termctl_name(3) and searched by name using tickit_term- ctl_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: 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 ef- fect. TICKIT_TERMCTL_CURSORSHAPE (int) The value is an integer from the TickitCursorShape enumeration indi- cating what shape the terminal's text cursor should be. Values are: TICKIT_CURSORSHAPE_BLOCK A solid block filling the entire cell. TICKIT_CURSORSHAPE_UNDER An underline below the character. TICKIT_CURSORSHAPE_LEFT_BAR A vertical bar to the left of the character. 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 redraw- ing 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 de- tected as distinct from regular ASCII text. When disabled, the key- pad will send normal text. TICKIT_TERMCTL_MOUSE (int) The value is an integer from the TickitTermMouseMode enumeration in- dicating what mouse events should be sent. Values are: BTICKIT_TERM_MOUSEMODE_CLICK Report button press and release events. TICKIT_TERM_MOUSEMODE_DRAG Report button press and release events, and movement while a button is held. TICKIT_TERM_MOUSEMODE_MOVE Report all button press, release and motion events even with no buttons held. TICKIT_TERM_MOUSEMODE_OFF Report nothing. TICKIT_TERMCTL_TITLE_TEXT (str) The value is a string for the terminal to use as its main window ti- tle. SEE ALSO tickit(7), tickit_renderbuffer(7) TICKIT_TERM(7)
NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | OUTPUT | INPUT | EVENTS | CONTROLS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=tickit_term&sektion=7&manpath=FreeBSD+Ports+15.1.quarterly>