rustom 0.1.0

A library for building rich, stateful terminal user interfaces and dashboards.
Documentation
//! # 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
//!
//! ```no_run
//! 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(())
//! }
//! ```

pub mod backend;
pub mod buffer;
pub mod layout;
pub mod style;
pub mod terminal;
pub mod text;
pub mod widgets;

use std::io::{self, stdout, Stdout};

use crossterm::execute;
use crossterm::terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen};

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

/// The default terminal type most applications will use: a crossterm
/// backed `Terminal` writing to stdout.
pub type DefaultTerminal = Terminal<backend::CrosstermBackend<Stdout>>;

/// 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.
pub fn init() -> io::Result<DefaultTerminal> {
    enable_raw_mode()?;
    execute!(stdout(), EnterAlternateScreen)?;
    let backend = backend::CrosstermBackend::new(stdout());
    let mut terminal = Terminal::new(backend)?;
    terminal.clear()?;
    Ok(terminal)
}

/// 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.
pub fn restore() -> io::Result<()> {
    execute!(stdout(), LeaveAlternateScreen)?;
    disable_raw_mode()?;
    Ok(())
}