fatui is an immediate-mode terminal ui library
that aims to be flexible and cell-perfect.
less vaguely:
- "terminal ui": terminal (sometimes "textmode") uis are
based on grids of formatted characters, rather than individual pixels as in a graphical ui,
most commonly seen in your terminal
- "flexible": it operates on a small number of consistent principles,
and beyond that, it doesn't have any strong opinions.
- "cell-perfect": the textmode equivalent of pixel-perfect --
you can control exactly, down to the individul character, where elements will be drawn.
- "immediate-mode": your ui is defined "immediately" in imperative code,
rather than a declarative dsl or persistent object tree.
# what's it look like?
mostly, it looks like your terminal --
fatui's favorite rendering backend is just stdout.
here's what it looks like captured with [asciinema]:
the cool thing about fatui is that it's
`#![no_std]`-friendly, meaning it can be used on the web!
the uncool thing about fatui is i haven't built that backend yet.
haven't even actually made it `#![no_std]` --
there's just nothing that would absolutely require it in the main code.
# why should i use fatui?
if you're building a full-terminal app --
something like `htop` or `vim`, which draws a ui to a terminal,
**not** a command-line app like `grep`, which is run as a command in your shell --
and you like immediate-mode guis,
then fatui is a great option.
but it's not the only option!
- [`ratatui`] is a similar full-terminal immediate-mode tui crate,
but it doesn't handle any inputs -- *just* output.
fatui handles both input and output.
- [`crossterm`] and [`termion`] are great for just raw terminal control and coloring,
but they're much lower-level.
fatui presents a much higher-level api.
- if you want a docker- or kubernetes-style rich cli output just shy of a full-terminal system,
let me know what you find, because i got nothin' --
even cargo just [rolled their own][cargo-progress]
[`ratatui`]: https://crates.io/crates/ratatui
[`crossterm`]: https://crates.io/crates/crossterm
[`termion`]: https://crates.io/crates/termion
[cargo-progress]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/progress.rs
# how do i use it?
it's a simple, three-step process:
1. add fatui as a dependency to your project:
```sh
cargo add fatui
```
2. get a [`Backend`] to render to:
```rs
let mut backend = fatui::open();
// (or you can instantiate any implementation of `fatui::Backend` you like)
```
3. render the rest of the owl to it.
right now that's pretty verbose and fiddly,
but by the 1.0 release it'll look like:
```rs
let mut clicks = 0;
loop {
let frame = backend.step();
let (top, bottom) = frame.split(rows!(*, red "-", 1));
if top.render(Button.or_key(Key::Space)).clicked {
clicks += 1;
}
bottom.render(tfmt!(
"whoah! you've clicked {@red}{clicks}{@/} times!",
));
}
```
(for the current state of affairs, see [the docs][docs-rs])
there's no layers and layers of framework you need to integrate your code into,
there's no separate files with custom dsls,
it's all just rust code with a loop and a handful of lightly arcane macros.
[`Backend`]: https://docs.rs/fatui/latest/fatui/trait.Backend.html
[docs-rs]: https://docs.rs/fatui
# why the name?
"fatui" is the plural for "silly" in italian.
it could also be parsed as "make a tui", depending on how generous you are,
and "fat ui" puns off "thin terminals".
# compatibility
fatui uses semantic versioning, but there are a couple of important things to note:
- backwards compatibility is measured against the *documented, public* api.
so `#[doc(hidden)]` items, implementation details, etc.
are 100% liable to change in breaking ways in patch versions.
- fatui is built for the latest stable rust and latest edition.
this means that increasing its msrv or required edition
is not considered a breaking change, either!
if those are inconvenient for you, i'm sorry,
but it's a hobby project.
i want to *enjoy* my time working on it,
and that means letting myself play with the latest toys.