Crate tuirealm

tui-realm

tui-realm is a framework for ratatui 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 routines as happens in Elm.

In addition, the components are organized inside the View, which manages mounting/umounting, focus and event forwarding for you.

tui-realm also comes with a standard library of components, which can be added to your dependencies, that you may find very useful.

Get started 🏁

⚠️ Warning: currently tui-realm supports these backends: crossterm, termion

Add tui-realm to your Cargo.toml 🦀

If you want the default features, just add tuirealm 1.x version:

tuirealm = "2"

otherwise you can specify the features you want to add:

tuirealm = { version = "2", default-features = false, features = [ "derive", "serialize", "termion" ] }

Supported features are:

• derive (default): add the #[derive(MockComponent)] proc macro to automatically implement MockComponent for Component. .
• serialize: add the serialize/deserialize trait implementation for KeyEvent and Key.
• crossterm: use the crossterm terminal backend
• termion: use the termion terminal backend

Create a tui-realm application 🪂

You can read the guide to get started with tui-realm on Github

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 --example demo

Re-exports

• pub use listener::EventListenerCfg;
• pub use listener::ListenerError;

Modules

• application
  Application
• command
  Command
• event
  events
• listener
  Listener
• macros
• props
  props
• ratatui
  ratatui
• terminal
  terminal
• utils
  Utils

Macros

• subclause_and
  A macro to generate a chain of crate::SubClause::And from a list of Ids with the case crate::SubClause::IsMounted for every id.
• subclause_and_not
  A macro to generate a chain of crate::SubClause::And from a list of Ids with the case crate::SubClause::Not containing crate::SubClause::IsMounted for every id.
• subclause_or
  A macro to generate a chain of crate::SubClause::Or from a list of Ids with the case crate::SubClause::IsMounted for every id.

Structs

• Application
  The application defines a tui-realm application. It will handle events, subscriptions and the view too. It provides functions to interact with the view (mount, umount, query, etc), but also the main function: Application::tick.
• Frame
  A consistent view into the terminal state for rendering a single frame.
• Props
  The props struct holds all the attributes associated to the component. Properties have been designed to be versatile for all kind of components, but without introducing too many attributes at the same time.
• Sub
  Public type to define a subscription.

Enums

• ApplicationError
  Error variants returned by Application
• AttrValue
  Describes a single attribute in the component properties.
• Attribute
  Describes a “selector” to query an attribute on props. The selector must identify uniquely an attribute in the properties. Check each attribute documentation to see how they’re supposed to be used, but remember that when implementing a component, you’re free to use each attribute as you prefer!
• Event
  An event raised by a user interaction
• NoUserEvent
  When using event you can use this as type parameter if you don’t want to use user events
• PollStrategy
  Poll strategy defines how to call Application::poll on the event listener.
• State
  State describes a component state
• StateValue
  StateValue describes the value contained in a State
• SubClause
  A subclause indicates the condition that must be satisfied in order to forward ev to target. Usually clauses are single conditions, but there are also some special condition, to create “ligatures”, which are:
• SubEventClause
  An event clause indicates on which kind of event the event must be forwarded to the target component.
• ViewError
  An error returned by the view

Traits

• Component
  The component describes the application level component, which is a wrapper around the MockComponent, which, in addition to all the methods exposed by the mock, it will handle the event coming from the View. The Event are passed to the on method, which will eventually return a Msg, which is defined in your application as an enum. (Don’t forget to derive PartialEq for your enum). In your application you should have a Component for each element on your UI, but the logic to implement is very tiny, since the most of the work should already be done into the MockComponent and many of them are available in the standard library at https://github.com/veeso/tui-realm-stdlib.
• Injector
  An injector is a trait object which can provide properties to inject to a certain component. The injector is called each time a component is mounted, providing the id of the mounted component and may return a list of (Attribute, AttrValue) to inject.
• MockComponent
  A Mock Component represents a component which defines all the properties and states it can handle and represent and the way it should be rendered. It must also define how to behave in case of a Cmd (command). Despite that, it won’t define how to behave after an Event and it won’t send any Msg. The MockComponent is intended to be used as a reusable component to implement your application component.
• Update
  The update trait defines the prototype of the function to be used to handle the events coming from the View.