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

otherwise you can specify the features you want to add:

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

Supported features are:

• derive (default): add the #[derive(MockComponent)] proc macro to automatically implement MockComponent for Component. .
• async-ports: add support for async ports
• 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::AndMany 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::OrMany 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.

Attribute Macros

async_traitasync-ports