Skip to main content

Crate rustom

Crate rustom 

Source
Expand description

§rustom

A library for building rich, stateful terminal user interfaces and dashboards, modeled after the immediate mode widget architecture that has become the standard approach for Rust TUIs: an in-memory Buffer that widgets render into, a diff based Terminal that only repaints what changed, and a pluggable Backend trait so the rendering core does not care whether it is talking to crossterm, a test harness, or anything else.

§Quick start

use std::io;
use rustom::layout::{Constraint, Direction, Layout};
use rustom::style::{Color, Style};
use rustom::widgets::{Block, Borders, Paragraph};

fn run() -> io::Result<()> {
    let mut terminal = rustom::init()?;
    terminal.draw(|frame| {
        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([Constraint::Length(3), Constraint::Fill(1)])
            .split(frame.area());

        let title = Block::bordered().title("rustom");
        frame.render_widget(title, chunks[0]);

        let body = Paragraph::new("Hello from rustom.")
            .style(Style::new().fg(Color::Cyan))
            .block(Block::bordered());
        frame.render_widget(body, chunks[1]);
    })?;
    rustom::restore()?;
    Ok(())
}

Re-exports§

pub use backend::Backend;
pub use buffer::Buffer;
pub use buffer::Cell;
pub use layout::Constraint;
pub use layout::Direction;
pub use layout::Layout;
pub use layout::Rect;
pub use style::Color;
pub use style::Modifier;
pub use style::Style;
pub use terminal::Frame;
pub use terminal::Terminal;
pub use text::Alignment;
pub use text::Line;
pub use text::Span;
pub use text::Text;
pub use widgets::StatefulWidget;
pub use widgets::Widget;

Modules§

backend
The Backend trait abstracts over the terminal driver used to actually paint cells to the screen, so Terminal can stay backend agnostic.
buffer
The Buffer is an in-memory grid of Cells representing everything that should be drawn on screen for a single frame. Widgets never touch the terminal directly, they only ever write into a Buffer.
layout
Layout primitives for splitting a screen area into smaller regions.
style
Styling primitives: colors, text modifiers, and the Style type used throughout the buffer and widget rendering pipeline.
terminal
Terminal owns a Backend plus two buffers (the currently displayed frame and the one being built), and diffs them on every draw call so only cells that actually changed get written to the real terminal.
text
Styled text primitives. A Span is a run of text with one style, a Line is a sequence of spans laid out on a single row, and Text is a sequence of lines making up a paragraph.
widgets
Built in widgets. Every widget implements Widget, which consumes self and draws into a region of a Buffer.

Functions§

init
Puts the terminal into raw mode and the alternate screen, and returns a ready to use Terminal. Pair this with restore before the process exits so the user’s shell is left in a sane state.
restore
Reverses the effect of init: leaves the alternate screen and disables raw mode. Call this before returning from main or on any error path, otherwise the terminal will be left unusable.

Type Aliases§

DefaultTerminal
The default terminal type most applications will use: a crossterm backed Terminal writing to stdout.