tui-realm
Developed by Christian Visintin
Current version: 0.4.3 (23/06/2021)
About tui-realm 👑
tui-realm is a framework for tui to simplify the implementation of terminal user interfaces adding the possibility to work with re-usable components with properties and states, as you'd do in React But that's not all: the components communicate with the ui engine via a system based on Messages and events, providing you with the possibility to implement update functions as happens in Elm. In addition, the components are organized inside Views, which manages mounting/umounting and focus for you.
And that's also explains the reason of the name: Realm stands for React and Elm.
Tui-realm also comes with a built-in standard library of components you may find very useful. Don't worry, they are optional if you don't want to use them 😉, just follow the guide in get started.
Get started 🏁
⚠ Warning: tui-realm works only with crossterm as backend ⚠
Add tui-realm to your Cargo.toml 🦀
= "0.4.3"
or if you want to include the standard component library...
= { = "0.4.3", = [ "with-components" ] }
Since this library requires crossterm too, you'll also need to add it to your Cargo.toml
= "0.19.0"
You don't need tui as dependency, since you can access to tui via tuirealm::tui::*
Create a tui-realm application
View how to implement a tui-realm application in the related guide.
Run examples
Still confused about how tui-realm works? Don't worry, try with the examples:
-
demo: a simple application which shows how tui-realm works
Apps using tui-realm
Want to add yours? Open an issue using the New app/component template 😄
Standard components library 🎨
Tui-realm comes with an optional standard library of components I thought would have been useful for most of the applications.
If you want to use it, just enable the with-components feature in your Cargo.toml.
For each component, the standard library provides a PropsBuilder in the same module (e.g. input::Input => input::InputPropsBuilder), which provides methods to set only the properties actually used by the component.
To have an overview of the components just run the gallery example 🦄
If you want a super-detailed guide about components check out the components guide.
Community components 🏘️
These components are not included in tui-realm, but have been developed by other users. I like advertising other's contents, so here you can find a list of components you may find useful for your next tui-realm project 💜.
- tui-realm-treeview A treeview component developed by @veeso
Want to add yours? Open an issue using the New app/component template 😄
Guides 🎓
Documentation 📚
The developer documentation can be found on Rust Docs at https://docs.rs/tuirealm
About other backends
As you've probably already noticed, tuirealm only supports crossterm as backend for the terminal, even if tui supports termion and other libraries. Why this?
Well the reasons are these two:
- There's no reason to use the other backends: I use crossterm in termscp, and I don't find any advantage in using termion or other backends. Crossterm is cross platform and works perfectly fine.
- Implementing the support for the other backends would force me in creating a mapper for input events from the different backends into a common type. Is it possible? Yes it is, but I'm really not interested in implementing it.
Contributing and issues 🤝🏻
Contributions, bug reports, new features and questions are welcome! 😉 If you have any question or concern, or you want to suggest a new feature, or you want just want to improve tui-realm, feel free to open an issue or a PR.
Please follow our contributing guidelines
Changelog ⏳
View tui-realm's changelog HERE
Buy me a coffee ☕
If you like tui-realm and you're grateful for the work I've done, please consider a little donation 🥳
License 📃
tui-realm is licensed under the MIT license.
You can read the entire license HERE