tui-realm
Developed by Christian Visintin
Current version: 0.1.0 (20/04/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.
Why tui-realm 🤔
Personally I didn't start this project from scratch. I've just decided to make a library out of the already existing code in termscp, which I had just finished at the time I started this project. I thought this library could have come handy for somebody.
You might be wondering now how much is this project influenced by the development of termscp. Well, a lot actually, I won't deny this, so don't expect this library to always try to fit the community needs, I'm just providing you with a tool I've made for myself, but that I wanted to share with the community.
Get started 🏁
⚠ Warning: tui-realm works only with crossterm as backend ⚠
Add tui-realm to your Cargo.toml 🦀
= "0.1.0"
or if you want to include the standard component library...
= { = "0.1.0", = [ "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
-
termscp: real production implemenetation of tui-realm; just browse the
src/ui/folder.
Standard components library 🎨
Tui-realm comes with an optional standard library of components I thought may be 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.
Guides 🎓
Documentation 📚
The developer documentation can be found on Rust Docs at https://docs.rs/tui-realm
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 advantage in using termion or other backends. Crossterm is cross platform and works perfectly fine.
- Implementing the support for the other backends would 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