Crate tuirealm

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

otherwise you can specify the features you want to add:

tuirealm = { version = "^1.9.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. .
• 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::EventListenerCfg;
• pub use listener::ListenerError;

Modules

• adapter
  adapters
• application
  Application
• command
  Command
• event
  events
• listener
  Listener
• props
  props
• terminal
  terminal
• tui
  tui
• utils
  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
• 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.