2016-11-07 00:07:53 +00:00
|
|
|
# tui-rs
|
|
|
|
|
2019-11-05 07:24:14 +00:00
|
|
|
[![Build Status](https://github.com/fdehau/tui-rs/workflows/CI/badge.svg)](https://github.com/fdehau/tui-rs/actions?query=workflow%3ACI+)
|
2017-05-21 12:21:29 +00:00
|
|
|
[![Crate Status](https://img.shields.io/crates/v/tui.svg)](https://crates.io/crates/tui)
|
|
|
|
[![Docs Status](https://docs.rs/tui/badge.svg)](https://docs.rs/crate/tui/)
|
|
|
|
|
2018-09-09 06:55:51 +00:00
|
|
|
<img src="./assets/demo.gif" alt="Demo cast under Linux Termite with Inconsolata font 12pt">
|
2016-11-07 00:07:53 +00:00
|
|
|
|
|
|
|
`tui-rs` is a [Rust](https://www.rust-lang.org) library to build rich terminal
|
|
|
|
user interfaces and dashboards. It is heavily inspired by the `Javascript`
|
|
|
|
library [blessed-contrib](https://github.com/yaronn/blessed-contrib) and the
|
|
|
|
`Go` library [termui](https://github.com/gizak/termui).
|
|
|
|
|
2019-01-24 18:45:59 +00:00
|
|
|
The library itself supports four different backends to draw to the terminal. You
|
2016-11-07 00:07:53 +00:00
|
|
|
can either choose from:
|
|
|
|
|
|
|
|
- [termion](https://github.com/ticki/termion)
|
|
|
|
- [rustbox](https://github.com/gchp/rustbox)
|
2020-01-09 23:11:58 +00:00
|
|
|
- [crossterm](https://github.com/crossterm-rs/crossterm)
|
2019-01-24 18:45:59 +00:00
|
|
|
- [pancurses](https://github.com/ihalila/pancurses)
|
2016-11-07 00:07:53 +00:00
|
|
|
|
2019-03-11 02:26:30 +00:00
|
|
|
However, some features may only be available in one of the four.
|
2016-11-07 23:35:46 +00:00
|
|
|
|
|
|
|
The library is based on the principle of immediate rendering with intermediate
|
2016-11-08 10:20:59 +00:00
|
|
|
buffers. This means that at each new frame you should build all widgets that are
|
|
|
|
supposed to be part of the UI. While providing a great flexibility for rich and
|
|
|
|
interactive UI, this may introduce overhead for highly dynamic content. So, the
|
|
|
|
implementation try to minimize the number of ansi escapes sequences generated to
|
|
|
|
draw the updated UI. In practice, given the speed of `Rust` the overhead rather
|
2016-11-07 23:35:46 +00:00
|
|
|
comes from the terminal emulator than the library itself.
|
|
|
|
|
|
|
|
Moreover, the library does not provide any input handling nor any event system and
|
|
|
|
you may rely on the previously cited libraries to achieve such features.
|
2016-11-07 00:07:53 +00:00
|
|
|
|
2017-12-26 11:03:25 +00:00
|
|
|
### [Documentation](https://docs.rs/tui)
|
2016-11-07 23:35:46 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
### Demo
|
|
|
|
|
2019-02-10 21:35:44 +00:00
|
|
|
The demo shown in the gif can be run with all available backends
|
|
|
|
(`exmples/*_demo.rs` files). For example to see the `termion` version one could
|
|
|
|
run:
|
|
|
|
|
|
|
|
```
|
2019-02-15 15:53:20 +00:00
|
|
|
cargo run --example termion_demo --release -- --tick-rate 200
|
2019-02-10 21:35:44 +00:00
|
|
|
```
|
|
|
|
|
2019-12-13 19:19:59 +00:00
|
|
|
where `tick-rate` is the UI refresh rate in ms.
|
|
|
|
|
2019-02-10 21:35:44 +00:00
|
|
|
The UI code is in [examples/demo/ui.rs](examples/demo/ui.rs) while the
|
|
|
|
application state is in [examples/demo/app.rs](examples/demo/app.rs).
|
2018-06-09 09:31:02 +00:00
|
|
|
|
2019-12-13 19:19:59 +00:00
|
|
|
Beware that the `termion_demo` only works on Unix platforms. If you are a Windows user,
|
|
|
|
you can see the same demo using the `crossterm` backend with the following command:
|
|
|
|
|
|
|
|
```
|
|
|
|
cargo run --example crossterm_demo --no-default-features --features="crossterm" --release -- --tick-rate 200
|
|
|
|
```
|
|
|
|
|
2020-04-13 23:10:01 +00:00
|
|
|
If the user interface contains glyphs that are not displayed correctly by your terminal, you may want to run
|
|
|
|
the demo without those symbols:
|
|
|
|
|
|
|
|
```
|
|
|
|
cargo run --example crossterm_demo --no-default-features --features="crossterm" --release -- --tick-rate 200 --enhanced-graphics false
|
|
|
|
```
|
|
|
|
|
2016-11-07 23:35:46 +00:00
|
|
|
### Widgets
|
|
|
|
|
|
|
|
The library comes with the following list of widgets:
|
|
|
|
|
|
|
|
* [Block](examples/block.rs)
|
|
|
|
* [Gauge](examples/gauge.rs)
|
|
|
|
* [Sparkline](examples/sparkline.rs)
|
|
|
|
* [Chart](examples/chart.rs)
|
2019-03-27 12:22:32 +00:00
|
|
|
* [BarChart](examples/barchart.rs)
|
2016-11-07 23:35:46 +00:00
|
|
|
* [List](examples/list.rs)
|
|
|
|
* [Table](examples/table.rs)
|
|
|
|
* [Paragraph](examples/paragraph.rs)
|
|
|
|
* [Canvas (with line, point cloud, map)](examples/canvas.rs)
|
|
|
|
* [Tabs](examples/tabs.rs)
|
|
|
|
|
2017-10-28 23:44:09 +00:00
|
|
|
Click on each item to see the source of the example. Run the examples with with
|
|
|
|
cargo (e.g. to run the demo `cargo run --example demo`), and quit by pressing `q`.
|
2016-11-07 23:35:46 +00:00
|
|
|
|
2019-02-10 21:35:44 +00:00
|
|
|
You can run all examples by running `make run-examples`.
|
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
### Third-party widgets
|
2016-11-07 23:35:46 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
* [tui-logger](https://github.com/gin66/tui-logger)
|
2016-11-07 23:35:46 +00:00
|
|
|
|
2019-12-13 20:19:34 +00:00
|
|
|
### Apps using tui
|
|
|
|
|
|
|
|
* [spotify-tui](https://github.com/Rigellute/spotify-tui)
|
2020-01-03 17:02:55 +00:00
|
|
|
* [bandwhich](https://github.com/imsnif/bandwhich)
|
2020-04-03 13:57:54 +00:00
|
|
|
* [kmon](https://github.com/orhun/kmon)
|
2020-02-13 23:48:37 +00:00
|
|
|
* [ytop](https://github.com/cjbassi/ytop)
|
2020-03-02 03:01:49 +00:00
|
|
|
* [zenith](https://github.com/bvaisvil/zenith)
|
2020-03-04 22:53:42 +00:00
|
|
|
* [bottom](https://github.com/ClementTsang/bottom)
|
2020-03-11 03:29:29 +00:00
|
|
|
* [oha](https://github.com/hatoo/oha)
|
2020-04-09 22:04:53 +00:00
|
|
|
* [gitui](https://github.com/extrawurst/gitui)
|
2020-05-10 10:25:23 +00:00
|
|
|
* [rust-sadari-cli](https://github.com/24seconds/rust-sadari-cli)
|
2020-04-22 00:52:35 +00:00
|
|
|
* [desed](https://github.com/SoptikHa2/desed)
|
2020-06-17 17:07:00 +00:00
|
|
|
* [diskonaut](https://github.com/imsnif/diskonaut)
|
2019-12-13 20:19:34 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
### Alternatives
|
2016-11-07 00:07:53 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
You might want to checkout [Cursive](https://github.com/gyscos/Cursive) for an
|
|
|
|
alternative solution to build text user interfaces in Rust.
|
2016-11-07 00:07:53 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
## License
|
2016-11-07 00:07:53 +00:00
|
|
|
|
2018-06-09 09:31:02 +00:00
|
|
|
[MIT](LICENSE)
|