#tui #terminal

tuirealm

A tui-rs framework to build interfaces, inspired by React and Elm

3 unstable releases

new 0.2.2 May 3, 2021
0.2.1 May 2, 2021
0.2.0 May 2, 2021
0.1.0 Apr 20, 2021

#396 in Command line utilities

Download history 13/week @ 2021-04-16 83/week @ 2021-04-23 235/week @ 2021-04-30

78 downloads per month

MIT license

230KB
4.5K SLoC

tui-realm

License: MIT Stars Downloads Crates.io Docs

Build Build Build codecov

Developed by Christian Visintin
Current version: 0.2.2 (02/05/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 🦀

tuirealm = "0.2.2"

or if you want to include the standard component library...

tuirealm = { "version" = "0.2.2", features = [ "with-components" ] }

Since this library requires crossterm too, you'll also need to add it to your Cargo.toml

crossterm = "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

    cargo run --features="with-components" --example demo
    
  • 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 🦄

cargo run --features="with-components" --example gallery

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:

  1. 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.
  2. 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 🥳

Buy-me-a-coffee


License 📃

tui-realm is licensed under the MIT license.

You can read the entire license HERE

Dependencies

~2MB
~41K SLoC