source: mainline/uspace/lib/termui/include/termui.h

Last change on this file was 899bdfd, checked in by Jiří Zárevúcky <zarevucky.jiri@…>, 10 months ago

Terminal scrolling and resizing support

  • Property mode set to 100644
File size: 5.6 KB
Line 
1/*
2 * Copyright (c) 2024 Jiří Zárevúcky
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29#ifndef USPACE_LIB_TERMUI_TERMUI_H_
30#define USPACE_LIB_TERMUI_TERMUI_H_
31
32#include <errno.h>
33#include <stdbool.h>
34#include <stddef.h>
35#include <stdint.h>
36
37#define GLYPH_IDX_
38#define GLYPH_IDX_ENDL 0xffffffu
39
40struct termui;
41typedef struct termui termui_t;
42
43/* RGB555 color representation. See termui_color_from/to_rgb() */
44typedef uint16_t termui_color_t;
45#define TERMUI_COLOR_DEFAULT 0
46
47typedef struct {
48 unsigned italic : 1;
49 unsigned bold : 1;
50 unsigned underline : 1;
51 unsigned blink : 1;
52 unsigned strike : 1;
53 unsigned inverted : 1;
54 unsigned cursor : 1;
55 /*
56 * Padding cells for wide characters.
57 * Placed at the end of rows where a wide character should have gone
58 * but didn't fit, and after wide characters to mark out the full space
59 * taken.
60 */
61 unsigned padding : 1;
62 // This is enough range for full Unicode coverage several times over.
63 // The library is almost completely oblivious to the meaning of glyph index,
64 // with the sole exception that zero is assumed to mean no glyph/empty cell.
65 // User application can utilize the extended range to, for example:
66 // - support multiple fonts / fallback fonts
67 // - support select combining character sequences that don't
68 // have equivalent precomposed characters in Unicode
69 // - support additional graphical features that aren't included in
70 // this structure
71 // Empty cells are initialized to all zeros.
72 unsigned glyph_idx : 24;
73 termui_color_t fgcolor;
74 termui_color_t bgcolor;
75} termui_cell_t;
76
77/** Update callback for viewport contents. The updated region is always limited
78 * to a single row. One row can be updated by multiple invocations.
79 * @param userdata
80 * @param col First column of the updated region.
81 * @param row Viewport row of the updated region.
82 * @param cell Updated cell data array.
83 * @param len Length of the updated region.
84 */
85typedef void (*termui_update_cb_t)(void *userdata, int col, int row, const termui_cell_t *cell, int len);
86
87/** Scrolling callback.
88 * The entire viewport was shifted by the given number of rows.
89 * For example, when a new line is added at the bottom of a full screen,
90 * this is called with delta = +1.
91 * The recipient must call termui_force_viewport_update() for previously
92 * off-screen rows manually (allowing this callback to be implemented
93 * the same as refresh).
94 *
95 * @param userdata
96 * @param delta Number of rows. Positive when viewport content moved up.
97 */
98typedef void (*termui_scroll_cb_t)(void *userdata, int delta);
99
100/** Refresh callback. Instructs user to re-render the entire screen.
101 *
102 * @param userdata
103 */
104typedef void (*termui_refresh_cb_t)(void *userdata);
105
106termui_t *termui_create(int cols, int rows, size_t history_lines);
107void termui_destroy(termui_t *termui);
108
109errno_t termui_resize(termui_t *termui, int cols, int rows, size_t history_lines);
110
111void termui_set_scroll_cb(termui_t *termui, termui_scroll_cb_t cb, void *userdata);
112void termui_set_update_cb(termui_t *termui, termui_update_cb_t cb, void *userdata);
113void termui_set_refresh_cb(termui_t *termui, termui_refresh_cb_t cb, void *userdata);
114
115void termui_put_lf(termui_t *termui);
116void termui_put_cr(termui_t *termui);
117void termui_put_crlf(termui_t *termui);
118void termui_put_tab(termui_t *termui);
119void termui_put_backspace(termui_t *termui);
120void termui_put_glyph(termui_t *termui, uint32_t glyph, int width);
121void termui_clear_screen(termui_t *termui);
122void termui_wipe_screen(termui_t *termui, int first_row);
123
124void termui_set_style(termui_t *termui, termui_cell_t style);
125void termui_set_pos(termui_t *termui, int col, int row);
126void termui_get_pos(const termui_t *termui, int *col, int *row);
127int termui_get_cols(const termui_t *termui);
128int termui_get_rows(const termui_t *termui);
129
130bool termui_get_cursor_visibility(const termui_t *termui);
131void termui_set_cursor_visibility(termui_t *termui, bool visible);
132termui_cell_t *termui_get_active_row(termui_t *termui, int row);
133void termui_history_scroll(termui_t *termui, int delta);
134void termui_force_viewport_update(const termui_t *termui, int first_row, int rows);
135bool termui_scrollback_is_active(const termui_t *termui);
136
137termui_color_t termui_color_from_rgb(uint8_t r, uint8_t g, uint8_t b);
138void termui_color_to_rgb(termui_color_t c, uint8_t *r, uint8_t *g, uint8_t *b);
139
140#endif /* USPACE_LIB_TERMUI_TERMUI_H_ */
Note: See TracBrowser for help on using the repository browser.