Crate tuirealm

Expand description

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 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 = "^1.8.0"

otherwise you can specify the features you want to add:

tuirealm = { version = "^1.8.0", default-features = false, features = [ "derive", "with-termion" ] }

Supported features are:

derive (default): add the #[derive(MockComponent)] proc macro to automatically implement MockComponent for Component. Read more.
with-crossterm (default): use crossterm as backend for tui.
with-termion (default): use termion as backend for tui.

⚠️ You can enable only one backend at the time and at least one must be enabled in order to build. ❗ You don’t need tui as a dependency, since you can access to tui types via use tuirealm::tui::

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 adapter::Frame;

pub use adapter::Terminal;

pub use listener::ListenerError;

Modules

adapters

Application

Command

events

Listener

Utils

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: tick(). See tick

EventListenerCfg

The event listener configurator is used to setup an event listener. Once you’re done with configuration just call start() and the event listener will start and the listener will be returned.

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 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.