pito-tui

cargo new hello
cd hello
cargo add pito-tui --git https://github.com/gmrdad82/pito-tui --tag v1.3.0

pito-tui = { git = "https://github.com/gmrdad82/pito-tui", tag = "v1.3.0" }

A first screen

Put this in src/main.rs, then cargo run: a titled screen with a key count, the hints and version in the footer, and Ctrl+C twice to quit.

use pito_tui::crossterm::event::KeyEvent;
use pito_tui::footer::Hint;
use pito_tui::header::Section;
use pito_tui::ratatui::{Frame, layout::Rect, style::Color, text::Line};
use pito_tui::{Cx, Palette, Screen, Tui, Words, message};

struct Hello {
    presses: usize,
}

impl Screen<()> for Hello {
    fn draw(&mut self, frame: &mut Frame, area: Rect, palette: &Palette) {
        let text = format!("{} keys pressed", self.presses);
        message(frame, area, Line::styled(text, palette.ink));
    }

    fn key(&mut self, _key: KeyEvent, _cx: &mut Cx<'_, ()>) {
        self.presses += 1;
    }

    fn hints(&self) -> Vec<Hint<'_>> {
        vec![Hint::new("any key", "count")]
    }
}

fn main() -> std::io::Result<()> {
    let words = Words::new()
        .help("? help")
        .again("ctrl+c again to quit")
        .yes("Yes")
        .no("No")
        .too_small("Make the window bigger");
    Tui::new("hello", env!("CARGO_PKG_VERSION"), Color::Rgb(0x5b, 0x8c, 0xff))
        .words(words)
        .hints([Hint::new("ctrl+c", "twice quit").pinned()])
        .screen(Section::new("Hello"), Hello { presses: 0 })
        .run()
}

Everything, live

git clone https://github.com/gmrdad82/pito-tui
cd pito-tui
cargo run --release --example demo
cargo run --release --example demo -- --stack
cargo run --release --example demo -- --dump 100x24 --keys "tab down enter"

Ctrl+K in the demo opens a "Go to" list that reaches every screen and every layer; --stack shows the header as a row stack with groups, and --mono the monochrome palette.

1. 01

   A header, a footer and screens

   Each screen is a type that implements Screen: it draws its area, takes its keys, and says what it shows in the header and the footer. The shell lays the screens out as numbered tabs in groups, keeps a breadcrumb when a screen drills in, and fits the footer's hints to the width.

   One Ctrl+C arms the quit guard, a second quits, and while work runs it asks first, in the app's words. Every key goes through one fixed order, so layers never fight over a key.

   More on app shell

2. 02

   Modals

   Cx::open(Modal) puts a centred, titled container over the live screen, built from text, lists and fields: filtered pick lists, search boxes, step menus with a reason field, and forms.

   A field narrows a list as it is typed, headings are skipped by the cursor, a risky row needs a second Enter, and modals stack, so an alert can sit over a form.

3. 03

   Bands, takeovers, toasts and gates

   A band under the header with a live countdown, a takeover that covers the app with the hourglass during a switch, toasts that outlive a screen change, and a gate in front of the app, such as a lock screen or a sign-in, that takes every key until the app opens it.

4. 04

   Activities and real commands

   The app hands the shell what it has running, and the shell draws it as a band on the footer and an activity screen that opens over any screen.

   Cx::run starts a real child command and follows its --progress json lines live; x stops it with a polite signal, then a kill, and no command outlives the app.

5. 05

   A log viewer for 20,000 lines

   Log holds the lines once, builds only the rows on screen, and scrolls, pages and jumps to either end. / finds every line holding each word, n and N step through the hits, and the scrollbar and range count show where you are.

   Drawing the Log screen at 200x60 took 0.314 ms on average.

6. 06

   Headless runs, and a terminal always given back

   Tui::shot draws the app at any size after a list of keys, dump::text and dump::ansi print it, Tui::bench times every screen, and capture::compare reports each cell that moved after a big change. Time comes from the run, never the wall clock, so the same app gives the same frames.

   Term turns on raw mode, the alternate screen and bracketed paste, remembers each one, and turns exactly those off again on quit, on an error, on a hangup or termination signal, and on a panic, before the panic message prints.

   More on headless

   $ cargo run --release --example demo -- --dump 72x14 --keys "tab"
    ──────────────────────────────── demo ──────────────── workspace one ─
                       1 Home  2 What to do next  3 Log
                                   5 steps
    ─ What to do next ────────────────────────────────────────────────────
       Step                        How
     ▌ Replace this screen         Home and Next are two Screen types; s…
       Set your accent             Tui::new takes one colour, or Palette…
       Add your first command      a key in Screen::key, its work in Cx:…
       Load real data              Screen::load returns the read; Screen…
       Wire the headless flags     --dump, --keys, --at, --bench, --capt…
   
    ──────────────────────────────────────────────────────────────────────
    ↑↓ move · enter open · / filter · ctrl+k go to · ctrl+c twice quit

7. 07

   Lists that fit the width

   Every list's columns make room as the terminal narrows: each carries a drop priority, so they go in that order while pinned ones stay and the message clips with an ellipsis, and as it widens they come back in order.

• Four widget crates

  One pin, the whole family

  pito-header draws the groups, tabs and breadcrumb at the top, pito-footer the hints, notice line, confirm and quit guard at the bottom, pito-hourglass the Braille hourglass while a screen loads, and pito-list the rows, scrollbar and range count of every list.

  pito-header's docs
• prec

  Recorded frame by frame

  Every clip on this page is a demo recorded by prec in a pseudo-terminal, from pito-tui's and pito-list's own tapes.

  See prec
• pito-compare

  Charted by pcmp

  The frame-time charts on this page are drawn by pcmp from the demo's own bench numbers.

  See pito-compare