Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Cubified/tuibox
A single-header terminal UI (TUI) library, capable of creating mouse-driven, interactive applications on the command line.
https://github.com/Cubified/tuibox
Last synced: 3 months ago
JSON representation
A single-header terminal UI (TUI) library, capable of creating mouse-driven, interactive applications on the command line.
- Host: GitHub
- URL: https://github.com/Cubified/tuibox
- Owner: Cubified
- Created: 2021-12-19T20:03:04.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-01T13:21:15.000Z (about 1 year ago)
- Last Synced: 2024-06-04T16:57:11.753Z (8 months ago)
- Language: C
- Size: 3.9 MB
- Stars: 101
- Watchers: 7
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- trackawesomelist - tuibox (⭐128) - A single-header terminal UI (TUI) library, capable of creating mouse-driven, interactive applications on the command line. \[MIT] (Recently Updated / [Oct 28, 2024](/content/2024/10/28/README.md))
README
# tuibox
tuibox ("toybox") is a single-header terminal UI library, capable of creating mouse-driven, interactive applications on the command line.
It is completely dependency-free, using nothing other than ANSI escape sequences to handle parsing input and rendering the screen. Additionally, its individual parts work largely independently, meaning as much (or as little) of the library as is necessary can be used.
## Demos
[demo_basic.c](https://github.com/Cubified/tuibox/blob/main/demos/demo_basic.c): Basic button demo w/ truecolor background
- (Note: Ugly color banding is from GIF compression)
[demo_bounce.c](https://github.com/Cubified/tuibox/blob/main/demos/demo_bounce.c): Bouncing box using custom render loop
[demo_drag.c](https://github.com/Cubified/tuibox/blob/main/demos/demo_drag.c): Click and drag
[bdfedit](https://github.com/Cubified/bdfedit), a bitmap font editor built using `tuibox`:
[colorslide](https://github.com/Cubified/colorslide), an RGBA/HSL/CMYK color picker built using `tuibox`:
[vt100utils](https://github.com/Cubified/vt100utils), an ANSI graphics escape sequence encoder/decoder that can couple with `tuibox` for content-aware text processing:
## Features
tuibox currently contains the following:
- Event-driven terminal render loop
- Mouse click and hover events on individual UI elements
- Keyboard events (including escape sequence events, such as arrow keys)
- Render caching (controlled by a user-defined dirty bit)
- Completely dependency-free, using pure ANSI escape sequences (no ncurses)
- Incrementally-adoptable -- rendering, events, and loops can all be used independently
## Design Overview
The basic hierarchy of a UI looks like this:
- UI: A collection of screens
- Screen: A collection of boxes
- Box: Any UI element
- X/Y, width/height
- Render function
- Click event function (optional)
- Hover event function (optional)
- Arbitrary user data (see below example)
- Main loop: Infinite `read()` loop gathering user input
- Update: Parses user input and fires events (if applicable)
## Example Code
A complete example is as follows:
```c
/* Global UI struct */
ui_t u;
/* Function that runs on box click */
void click(ui_box_t *b, int x, int y){
b->data1 = "you clicked me!";
ui_draw(&u);
}
/* Function that runs on box hover */
void hover(ui_box_t *b, int x, int y, int down){
b->data1 = "you hovered me!";
ui_draw(&u);
}
void stop(){
ui_free(&u);
exit(0);
}
int main(){
/* Initialize UI data structures */
ui_new(0, &u);
/* Add a new text box to screen 0 */
ui_text(
UI_CENTER_X, UI_CENTER_Y,
"hello world!",
0,
click, hover,
&u
);
/* Register an event on the q key */
ui_key("q", stop, &u);
/* Render the screen */
ui_draw(&u);
ui_loop(&u){
/* Check for mouse/keyboard events */
ui_update(&u);
}
return 0;
}
```
## Compiling and Running Demos
To compile all demos in one go:
$ make
$ ./demo_basic
$ ./demo_bounce
$ ./demo_drag
## Libraries/See Also
- [vec](https://github.com/rxi/vec): Dynamic arrays used to store events and boxes
- [bdfedit](https://github.com/Cubified/bdfedit): Bitmap font editor written alongside `tuibox`