FreeBSD Manual Pages
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 pro- vides 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 terminal instance stores a reference count to make it easier for appli- cations 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 out- put 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_tear- down(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 applica- tion is aware that the size of a terminal represented by a tty(7) file- handle 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 com- mands. 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_time- out_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_un- bind_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, TICKIT_MOUSEWHEEL_DOWN, TICKIT_MOUSEWHEEL_LEFT or TICKIT_MOUSEWHEEL_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 prevents later handler functions from observing it. CONTROLS A terminal instance has a number of runtime-configuration control op- tions 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 obtained by tickit_termctl_name(3) and searched by name using tickit_termctl_lookup(3). The type of a con- trol option can be queried using tickit_termctl_type(3). The options are given in an enumeration called TickitTermCtl. The fol- lowing 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 cur- sor 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. Val- ues 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 cur- sor should be visible. When disabled the cursor position is not visible. Typically applications will hide the cursor while per- forming redrawing operations so as not to show a flickering ef- fect as the cursor moves, and show it again when drawing is com- plete. 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: 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 title. 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.0>