Ratatui

https://ratatui.rs
Admin
Ratatui is a lightweight Rust library for building terminal user interfaces (TUIs) with widgets and...
Tokens:335,349
Snippets:2,053
Trust Score:8.4
Update:5 days ago
Show doc for...
Tokens:
Raw
### Main function pre-run setup

Source: https://ratatui.rs/tutorials/json-editor/main

Starts the main function with terminal setup: enables raw mode, creates a stderr handle, and executes EnterAlternateScreen and EnableMouseCapture. Uses stderr to allow piping output to stdout.

```rust
fn main() -> Result<(), Box<dyn Error>> {
    // setup terminal
    enable_raw_mode()?;
    let mut stderr = io::stderr(); // This is a special case. Normally using stdout is fine
    execute!(stderr, EnterAlternateScreen, EnableMouseCapture)?;
    // --snip--
```

--------------------------------

### Run the list example

Source: https://ratatui.rs/examples/widgets/list

Clone the ratatui repository at version v0.30.2 and run the list example using cargo. Requires git and cargo installed.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example list
```

--------------------------------

### Flex::Start layout example

Source: https://ratatui.rs/concepts/layout

Visual example showing two Length(20) elements aligned to the start of an 80-cell container, with a 40 px spacer at the end.

```svgbob
<--------------------------------------- 80 px ---------------------------------------->
┌────────────────────┐┌────────────────────┐┌╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ┐
│    Length(20)      ││    Length(20)      ││              40 px Spacer                │
└────────────────────┘└────────────────────┘└╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ┘
```

--------------------------------

### Run the tracing example

Source: https://ratatui.rs/examples/apps/tracing

Clone the Ratatui repository and run the tracing example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p tracing
```

--------------------------------

### Run the calendar example

Source: https://ratatui.rs/examples/widgets/calendar

Clone the ratatui repository and run the calendar example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example calendar
```

--------------------------------

### Run the flex example

Source: https://ratatui.rs/examples/layout/flex

Clone the Ratatui repository at version v0.30.2 and run the flex example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p flex
```

--------------------------------

### Run the Block example

Source: https://ratatui.rs/examples/widgets/block

Clone the Ratatui repository and run the block example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example block
```

--------------------------------

### Run the color-explorer example

Source: https://ratatui.rs/examples/style/colors

Clones the Ratatui repository at version v0.30.2 and runs the color-explorer example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p color-explorer
```

--------------------------------

### Run the volatility-surface example

Source: https://ratatui.rs/highlights/v0301

Clone the Ratatui repository and run the volatility-surface example with cargo.

```sh
git clone https://github.com/ratatui/ratatui && cd ratatui/

cargo run -p volatility-surface
```

--------------------------------

### Run the barchart example

Source: https://ratatui.rs/examples/widgets/barchart

Clone the Ratatui repository and run the barchart example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example barchart
```

--------------------------------

### Run the table example

Source: https://ratatui.rs/examples/widgets/table

Clone the Ratatui repository at version v0.30.2 and run the table example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example table
```

--------------------------------

### Run demo2 example

Source: https://ratatui.rs/highlights/v024

Command to run the new demo2 example with crossterm and widget-calendar features.

```sh
cargo run --example=demo2 --features="crossterm widget-calendar"
```

--------------------------------

### Run the canvas example

Source: https://ratatui.rs/examples/widgets/canvas

Commands to clone the Ratatui repository and run the canvas example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example canvas
```

--------------------------------

### Run the tabs example

Source: https://ratatui.rs/examples/widgets/tabs

Clone the Ratatui repository at version v0.30.2 and run the tabs example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example tabs
```

--------------------------------

### Run the hello-world example

Source: https://ratatui.rs/examples/apps/hello_world

Clone the Ratatui repository at version v0.30.2 and run the hello-world example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p hello-world
```

--------------------------------

### main.rs: Terminal setup and app loop

Source: https://ratatui.rs/tutorials/json-editor/closing-thoughts

Sets up the terminal with raw mode, alternate screen, and mouse capture, then runs the app loop. Handles key events for editing, exiting, and saving key-value pairs. Restores the terminal on exit.

```rust
use std::{error::Error, io};

use ratatui::{
    backend::{Backend, CrosstermBackend},
    crossterm::{
        event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyEventKind},
        execute,
        terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
    },
    Terminal,
};

mod app;
mod ui;
use crate::{
    app::{App, CurrentScreen, CurrentlyEditing},
    ui::ui,
};

fn main() -> Result<(), Box<dyn Error>> {
    // setup terminal
    enable_raw_mode()?;
    let mut stderr = io::stderr(); // This is a special case. Normally using stdout is fine
    execute!(stderr, EnterAlternateScreen, EnableMouseCapture)?;
    let backend = CrosstermBackend::new(stderr);
    let mut terminal = Terminal::new(backend)?;

    // create app and run it
    let mut app = App::new();
    let res = run_app(&mut terminal, &mut app);

    // restore terminal
    disable_raw_mode()?;
    execute!(
        terminal.backend_mut(),
        LeaveAlternateScreen,
        DisableMouseCapture
    )?;
    terminal.show_cursor()?;

    if let Ok(do_print) = res {
        if do_print {
            app.print_json()?;
        }
    } else if let Err(err) = res {
        println!("{err:?}");
    }

    Ok(())
}

fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<bool>
where
    io::Error: From<B::Error>,
{
    loop {
        terminal.draw(|f| ui(f, app))?;

        if let Event::Key(key) = event::read()? {
            if key.kind == event::KeyEventKind::Release {
                // Skip events that are not KeyEventKind::Press
                continue;
            }
            match app.current_screen {
                CurrentScreen::Main => match key.code {
                    KeyCode::Char('e') => {
                        app.current_screen = CurrentScreen::Editing;
                        app.currently_editing = Some(CurrentlyEditing::Key);
                    }
                    KeyCode::Char('q') => {
                        app.current_screen = CurrentScreen::Exiting;
                    }
                    _ => {}
                },
                CurrentScreen::Exiting => match key.code {
                    KeyCode::Char('y') => {
                        return Ok(true);
                    }
                    KeyCode::Char('n') | KeyCode::Char('q') => {
                        return Ok(false);
                    }
                    _ => {}
                },
                CurrentScreen::Editing if key.kind == KeyEventKind::Press => {
                    match key.code {
                        KeyCode::Enter => {
                            if let Some(editing) = &app.currently_editing {
                                match editing {
                                    CurrentlyEditing::Key => {
                                        app.currently_editing = Some(CurrentlyEditing::Value);
                                    }
                                    CurrentlyEditing::Value => {
                                        app.save_key_value();
                                        app.current_screen = CurrentScreen::Main;
                                    }
                                }
                            }
                        }
                        KeyCode::Backspace => {
                            if let Some(editing) = &app.currently_editing {
                                match editing {
                                    CurrentlyEditing::Key => {
                                        app.key_input.pop();
                                    }
                                    CurrentlyEditing::Value => {
                                        app.value_input.pop();
                                    }
                                }
                            }
                        }
                        KeyCode::Esc => {
                            app.current_screen = CurrentScreen::Main;
                            app.currently_editing = None;
                        }
                        KeyCode::Tab => {
                            app.toggle_editing();
                        }
                        KeyCode::Char(value) => {
                            if let Some(editing) = &app.currently_editing {
                                match editing {
                                    CurrentlyEditing::Key => {
                                        app.key_input.push(value);
                                    }
                                    CurrentlyEditing::Value => {
                                        app.value_input.push(value);
                                    }
                                }
                            }
                        }
                        _ => {}
                    }
                }
                _ => {}
            }
        }
    }
}
```

--------------------------------

### Run the todo-list example with cargo

Source: https://ratatui.rs/examples/apps/todo-list

Clones the Ratatui repository at the ratatui-v0.30.2 branch and runs the todo-list example with cargo. Requires git and cargo installed.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p todo-list
```

--------------------------------

### Run the Ratatui Logo example

Source: https://ratatui.rs/examples/apps/ratatui-logo

Clone the Ratatui repository at version v0.30.2 and run the logo example with cargo. This requires Rust and Cargo installed.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example logo
```

--------------------------------

### Run chart example with cargo

Source: https://ratatui.rs/examples/apps/chart

Clones the Ratatui repository at version ratatui-v0.30.2 and runs the chart example with cargo. Requires git and cargo installed.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p chart
```

--------------------------------

### Run the panic example with cargo

Source: https://ratatui.rs/examples/apps/panic

Clone the Ratatui repository at version 0.30.2 and run the panic example using cargo. This requires git and cargo installed.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p panic
```

--------------------------------

### demo/main.rs - Ratatui Original Demo example

Source: https://ratatui.rs/examples/apps/demo

Main entry point for the demo application. Parses CLI arguments for tick rate and unicode, then runs the appropriate backend based on enabled features.

```rust
//! # [Ratatui] Original Demo example
//!
//! The latest version of this example is available in the [examples] folder in the repository.
//!
//! Please note that the examples are designed to be run against the `main` branch of the Github
//! repository. This means that you may not be able to compile with the latest release version on
//! crates.io, or the one that you have installed locally.
//!
//! See the [examples readme] for more information on finding examples that match the version of the
//! library you are using.
//!
//! [Ratatui]: https://github.com/ratatui/ratatui
//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

use std::error::Error;
use std::time::Duration;

use clap::Parser;

mod app;
#[cfg(feature = "crossterm")]
mod crossterm;
#[cfg(feature = "termina")]
mod termina;
#[cfg(all(not(windows), feature = "termion"))]
mod termion;
#[cfg(feature = "termwiz")]
mod termwiz;

mod ui;

/// Demo
#[derive(Debug, Parser)]
struct Cli {
    /// time in ms between two ticks.
    #[arg(short, long, default_value_t = 250)]
    tick_rate: u64,

    /// whether unicode symbols are used to improve the overall look of the app
    #[arg(short, long, default_value_t = true)]
    unicode: bool,
}

fn main() -> Result<(), Box<dyn Error>> {
    let cli = Cli::parse();
    let tick_rate = Duration::from_millis(cli.tick_rate);
    #[cfg(feature = "crossterm")]
    crate::crossterm::run(tick_rate, cli.unicode)?;
    #[cfg(all(feature = "termina", not(feature = "crossterm")))]
    crate::termina::run(tick_rate, cli.unicode)?;
    #[cfg(all(
        not(windows),
        feature = "termion",
        not(feature = "crossterm"),
        not(feature = "termina")
    ))]
    crate::termion::run(tick_rate, cli.unicode)?;
    #[cfg(all(
        feature = "termwiz",
        not(feature = "crossterm"),
        not(feature = "termina"),
        not(feature = "termion")
    ))]
    crate::termwiz::run(tick_rate, cli.unicode)?;
    Ok(())
}
```

--------------------------------

### Flex::End layout example

Source: https://ratatui.rs/concepts/layout

Visual example showing two Length(20) elements aligned to the end of an 80-cell container, with a 40 px spacer at the start.

```svgbob
<--------------------------------------- 80 px ---------------------------------------->
┌╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ┐┌────────────────────┐┌────────────────────┐
│              40 px Spacer                ││    Length(20)      ││    Length(20)      │
└╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ╌ ┘└────────────────────┘└────────────────────┘
```

--------------------------------

### main.rs - Minimal Ratatui application

Source: https://ratatui.rs/examples/apps/minimal

The main.rs file for the minimal example. It uses ratatui::run to draw 'Hello World!' and exits on any key press.

```rust
//! A minimal example of a Ratatui application.
//!
//! This is a bare minimum example. There are many approaches to running an application loop,
//! so this is not meant to be prescriptive. See the [examples] folder for more complete
//! examples. In particular, the [hello-world] example is a good starting point.
//!
//! This example runs with the Ratatui library code in the branch that you are currently
//! reading. See the [`latest`] branch for the code which works with the most recent Ratatui
//! release.
//!
//! [`latest`]: https://github.com/ratatui/ratatui/tree/latest
//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
//! [hello-world]: https://github.com/ratatui/ratatui/blob/main/examples/apps/hello-world
fn main() -> Result<(), Box<dyn std::error::Error>> {
    ratatui::run(|terminal| {
        loop {
            terminal.draw(|frame| frame.render_widget("Hello World!", frame.area()))?;
            if crossterm::event::read()?.is_key_press() {
                break Ok(());
            }
        }
    })
}
```

--------------------------------

### svgbob diagram example

Source: https://ratatui.rs/developer-guide/website

Draw diagrams using svgbob syntax. The example shows a simple flow diagram with three steps: Get Key Event, Update State, and Render.

```svgbob
 ,-------------.
 |Get Key Event|
 `-----+-------'
       |
       |
 ,-----v------.
 |Update State|
 `-----+------'
       |
       |
   ,---v----.
   | Render |
   `--------'
```

--------------------------------

### Termion panic hook setup in main.rs

Source: https://ratatui.rs/recipes/apps/panic-hooks

This Rust example shows how to set up a panic hook for a Termion-based TUI. It creates a RawTerminal, suspends raw mode immediately, and installs a hook that suspends raw mode and restores the terminal before calling the original hook. It also includes init_tui and restore_tui functions that use ToAlternateScreen and ToMainScreen, and a main function that triggers a panic after drawing.

```rust
use std::{
    io::{self, stdout, Stdout, Write},
    panic::{set_hook, take_hook},
    thread::sleep,
    time::Duration,
};

use ratatui::{
    backend::TermionBackend,
    termion::{
        raw::{IntoRawMode, RawTerminal},
        screen::{ToAlternateScreen, ToMainScreen},
    },
    text::Span,
    Terminal,
};

pub fn main() -> io::Result<()> {
    init_panic_hook()?;
    let mut tui = init_tui()?;
    tui.draw(|frame| frame.render_widget(Span::from("Hello, world!"), frame.area()))?;
    sleep(Duration::from_secs(1));
    panic!("This is a panic!");
}

pub fn init_panic_hook() -> io::Result<()> {
    let raw_output = stdout().into_raw_mode()?;
    raw_output.suspend_raw_mode()?;

    let original_hook = take_hook();
    set_hook(Box::new(move |panic_info| {
        // intentionally ignore errors here since we're already in a panic
        let _ = raw_output.suspend_raw_mode();
        let _ = restore_tui();
        original_hook(panic_info);
    }));
    Ok(())
}

pub fn init_tui() -> io::Result<Terminal<TermionBackend<RawTerminal<Stdout>>>> {
    let mut stdout = stdout().into_raw_mode()?;
    write!(stdout, "{}", ToAlternateScreen)?;
    stdout.flush()?;
    Terminal::new(TermionBackend::new(stdout))
}

pub fn restore_tui() -> io::Result<()> {
    write!(stdout(), "{}", ToMainScreen)?;
    stdout().flush()?;
    Ok(())
}

```

--------------------------------

### Initialize color-eyre in main

Source: https://ratatui.rs/tutorials/counter-app/_multiple-files

Example of adding color_eyre::install()? at the start of the main function when using color-eyre.

```rust
use color_eyre::eyre::Result;

fn main() -> Result<()> {
    color_eyre::install()?;
    // ...
    Ok(())
}
```

--------------------------------

### demo2/main.rs - Entry point with fixed viewport

Source: https://ratatui.rs/examples/apps/demo2

Main entry point for the demo2 example. Sets up error handling, a fixed viewport of 81x18, enters alternate screen, runs the app, and restores terminal. Requires color_eyre and crossterm.

```rust
//! # [Ratatui] Demo2 example
//!
//! The latest version of this example is available in the [examples] folder in the repository.
//!
//! Please note that the examples are designed to be run against the `main` branch of the Github
//! repository. This means that you may not be able to compile with the latest release version on
//! crates.io, or the one that you have installed locally.
//!
//! See the [examples readme] for more information on finding examples that match the version of the
//! library you are using.
//!
//! [Ratatui]: https://github.com/ratatui/ratatui
//! [examples]: https://github.com/ratatui/ratatui/blob/main/examples
//! [examples readme]: https://github.com/ratatui/ratatui/blob/main/examples/README.md

#![allow(
    clippy::missing_errors_doc,
    clippy::module_name_repetitions,
    clippy::must_use_candidate
)]

mod app;
mod colors;
mod destroy;
mod tabs;
mod theme;

use std::io::stdout;

use app::App;
use color_eyre::Result;
use crossterm::execute;
use crossterm::terminal::{EnterAlternateScreen, LeaveAlternateScreen};
use ratatui::layout::Rect;
use ratatui::{TerminalOptions, Viewport};

pub use self::colors::{RgbSwatch, color_from_oklab};
pub use self::theme::THEME;

fn main() -> Result<()> {
    color_eyre::install()?;
    // this size is to match the size of the terminal when running the demo
    // using vhs in a 1280x640 sized window (github social preview size)
    let viewport = Viewport::Fixed(Rect::new(0, 0, 81, 18));
    let terminal = ratatui::init_with_options(TerminalOptions { viewport });
    execute!(stdout(), EnterAlternateScreen).expect("failed to enter alternate screen");
    let app_result = App::default().run(terminal);
    execute!(stdout(), LeaveAlternateScreen).expect("failed to leave alternate screen");
    ratatui::restore();
    app_result
}
```

--------------------------------

### Run the constraint-explorer example

Source: https://ratatui.rs/examples/layout/constraint-explorer

Clones the Ratatui repository at version v0.30.2 and runs the constraint-explorer example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p constraint-explorer
```

--------------------------------

### Import pre-run terminal setup modules

Source: https://ratatui.rs/tutorials/json-editor/main

Imports the necessary crossterm modules for enabling raw mode, entering the alternate screen, and enabling mouse capture. These are used at the start of the main function.

```rust
use ratatui::crossterm::event::EnableMouseCapture;
use ratatui::crossterm::execute;
use ratatui::crossterm::terminal::{enable_raw_mode, EnterAlternateScreen};
use std::io;
```

--------------------------------

### Run the minimal example

Source: https://ratatui.rs/examples/apps/minimal

Clones the Ratatui repository at version v0.30.2 and runs the minimal example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p minimal
```

--------------------------------

### Gauge example main.rs

Source: https://ratatui.rs/examples/apps/gauge

Full Rust source for the gauge demo. It defines an App with four progress values, handles keyboard input to start and quit, and renders four gauges with different colors and progress calculations.

```rust
/// A Ratatui example that demonstrates different types of gauges.
///
/// This example runs with the Ratatui library code in the branch that you are currently
/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
/// release.
///
/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
use std::time::Duration;

use color_eyre::Result;
use crossterm::event::{self, KeyCode};
use ratatui::DefaultTerminal;
use ratatui::buffer::Buffer;
use ratatui::layout::{Alignment, Constraint, Layout, Rect};
use ratatui::style::palette::tailwind;
use ratatui::style::{Color, Style, Stylize};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Gauge, Padding, Paragraph, Widget};

const GAUGE1_COLOR: Color = tailwind::RED.c800;
const GAUGE2_COLOR: Color = tailwind::GREEN.c800;
const GAUGE3_COLOR: Color = tailwind::BLUE.c800;
const GAUGE4_COLOR: Color = tailwind::ORANGE.c800;
const CUSTOM_LABEL_COLOR: Color = tailwind::SLATE.c200;

#[derive(Debug, Default, Clone, Copy)]
struct App {
    state: AppState,
    progress_columns: u16,
    progress1: u16,
    progress2: f64,
    progress3: f64,
    progress4: f64,
}

#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
enum AppState {
    #[default]
    Running,
    Started,
    Quitting,
}

fn main() -> Result<()> {
    color_eyre::install()?;
    ratatui::run(|terminal| App::default().run(terminal))
}

impl App {
    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
        while self.state != AppState::Quitting {
            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
            self.handle_events()?;
            self.update(terminal.size()?.width);
        }
        Ok(())
    }

    fn update(&mut self, terminal_width: u16) {
        if self.state != AppState::Started {
            return;
        }

        // progress1 and progress2 help show the difference between ratio and percentage measuring
        // the same thing, but converting to either a u16 or f64. Effectively, we're showing the
        // difference between how a continuous gauge acts for floor and rounded values.
        self.progress_columns = (self.progress_columns + 1).clamp(0, terminal_width);
        self.progress1 = self.progress_columns * 100 / terminal_width;
        self.progress2 = f64::from(self.progress_columns) * 100.0 / f64::from(terminal_width);

        // progress3 and progress4 similarly show the difference between unicode and non-unicode
        // gauges measuring the same thing.
        self.progress3 = (self.progress3 + 0.1).clamp(40.0, 100.0);
        self.progress4 = (self.progress4 + 0.1).clamp(40.0, 100.0);
    }

    fn handle_events(&mut self) -> Result<()> {
        let timeout = Duration::from_secs_f32(1.0 / 20.0);
        if !event::poll(timeout)? {
            return Ok(());
        }
        if let Some(key) = event::read()?.as_key_press_event() {
            match key.code {
                KeyCode::Char(' ') | KeyCode::Enter => self.start(),
                KeyCode::Char('q') | KeyCode::Esc => self.quit(),
                _ => {}
            }
        }
        Ok(())
    }

    const fn start(&mut self) {
        self.state = AppState::Started;
    }

    const fn quit(&mut self) {
        self.state = AppState::Quitting;
    }
}

impl Widget for &App {
    #[expect(clippy::similar_names)]
    fn render(self, area: Rect, buf: &mut Buffer) {
        use Constraint::{Length, Min, Ratio};
        let layout = Layout::vertical([Length(2), Min(0), Length(1)]);
        let [header_area, gauge_area, footer_area] = area.layout(&layout);

        let layout = Layout::vertical([Ratio(1, 4); 4]);
        let [gauge1_area, gauge2_area, gauge3_area, gauge4_area] = gauge_area.layout(&layout);

        render_header(header_area, buf);
        render_footer(footer_area, buf);

        self.render_gauge1(gauge1_area, buf);
        self.render_gauge2(gauge2_area, buf);
        self.render_gauge3(gauge3_area, buf);
        self.render_gauge4(gauge4_area, buf);
    }
}

fn render_header(area: Rect, buf: &mut Buffer) {
    Paragraph::new("Ratatui Gauge Example")
        .bold()
        .alignment(Alignment::Center)
        .fg(CUSTOM_LABEL_COLOR)
        .render(area, buf);
}

fn render_footer(area: Rect, buf: &mut Buffer) {
    Paragraph::new("Press ENTER to start")
        .alignment(Alignment::Center)
        .fg(CUSTOM_LABEL_COLOR)
        .bold()
        .render(area, buf);
}
```

--------------------------------

### Retrieve window size with CrosstermBackend::window_size

Source: https://ratatui.rs/highlights/v024

Use the new window_size method on a backend to get a WindowSize struct containing columns_rows and pixels. The example prints the result with debug formatting. The output shows a Size with width and height for both fields.

```rust
let stdout = std::io::stdout();
let mut backend = CrosstermBackend::new(stdout);
println!("{:#?}", backend.window_size()?;
```

```text
WindowSize {
    columns_rows: Size {
        width: 240,
        height: 30,
    },
    pixels: Size {
        width: 0,
        height: 0,
    },
}
```

--------------------------------

### Tui struct terminal setup and teardown methods

Source: https://ratatui.rs/templates/component/tui-rs

The Tui struct provides methods to enter and exit the terminal, enabling raw mode, alternate screen, mouse capture, and bracketed paste. It also starts and stops the event loop task.

```rust
impl Tui {
    pub fn start(&mut self) {
        self.cancel(); // Cancel any existing task
        self.cancellation_token = CancellationToken::new();
        let event_loop = Self::event_loop(
            self.event_tx.clone(),
            self.cancellation_token.clone(),
            self.tick_rate,
            self.frame_rate,
        );
        self.task = tokio::spawn(async {
            event_loop.await;
        });
    }
    pub fn enter(&mut self) -> Result<()> {
        crossterm::terminal::enable_raw_mode()?;
        crossterm::execute!(stdout(), EnterAlternateScreen, cursor::Hide)?;
        if self.mouse {
            crossterm::execute!(stdout(), EnableMouseCapture)?;
        }
        if self.paste {
            crossterm::execute!(stdout(), EnableBracketedPaste)?;
        }
        self.start();
        Ok(())
    }

    pub fn exit(&mut self) -> Result<()> {
        self.stop()?;
        if crossterm::terminal::is_raw_mode_enabled()? {
            self.flush()?;
            if self.paste {
                crossterm::execute!(stdout(), DisableBracketedPaste)?;
            }
            if self.mouse {
                crossterm::execute!(stdout(), DisableMouseCapture)?;
            }
            crossterm::execute!(stdout(), LeaveAlternateScreen, cursor::Show)?;
            crossterm::terminal::disable_raw_mode()?;
        }
        Ok(())
    }

    pub fn stop(&self) -> Result<()> {
        self.cancel();
        let mut counter = 0;
        while !self.task.is_finished() {
            std::thread::sleep(Duration::from_millis(1));
            counter += 1;
            if counter > 50 {
                self.task.abort();
            }
            if counter > 100 {
                error!("Failed to abort task in 100 milliseconds for unknown reason");
                break;
            }
        }
        Ok(())
    }
}
```

```rust
self.task = tokio::spawn(async {
    event_loop.await;
});
```

--------------------------------

### Run site with mise

Source: https://ratatui.rs/developer-guide/website

Starts the local Astro/Starlight development server and prints a local URL to open in your browser.

```shell
mise run dev

```

--------------------------------

### Run the inline example

Source: https://ratatui.rs/examples/apps/inline

Clones the Ratatui repository at version v0.30.2 and runs the inline example with cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p inline
```

--------------------------------

### Ratatui Hello World with manual event loop

Source: https://ratatui.rs/faq

Example of a Ratatui application that manually handles the event loop, terminal setup, and redrawing. It uses crossterm for input and terminal control, and demonstrates a centered paragraph with a border. Requires more code but gives precise control over the UI.

```rust
use ratatui::{
    Terminal,
    backend::CrosstermBackend,
    crossterm,
    layout::{Alignment, Constraint, Direction, Layout, Rect},
    widgets::{Block, Borders, Paragraph},
};

fn init() -> Result<(), Box<dyn std::error::Error>> {
  crossterm::terminal::enable_raw_mode()?;
  crossterm::execute!(std::io::stderr(), crossterm::terminal::EnterAlternateScreen)?;
  Ok(())
}

fn exit() -> Result<(), Box<dyn std::error::Error>> {
  crossterm::execute!(std::io::stderr(), crossterm::terminal::LeaveAlternateScreen)?;
  crossterm::terminal::disable_raw_mode()?;
  Ok(())
}

fn centered_rect(r: Rect, percent_x: u16, percent_y: u16) -> Rect {
  let popup_layout = Layout::default()
    .direction(Direction::Vertical)
    .constraints([
      Constraint::Percentage((100 - percent_y) / 2),
      Constraint::Percentage(percent_y),
      Constraint::Percentage((100 - percent_y) / 2),
    ])
    .split(r);

  Layout::default()
    .direction(Direction::Horizontal)
    .constraints([
      Constraint::Percentage((100 - percent_x) / 2),
      Constraint::Percentage(percent_x),
      Constraint::Percentage((100 - percent_x) / 2),
    ])
    .split(popup_layout[1])[1]
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
  init()?;

  let mut terminal = Terminal::new(CrosstermBackend::new(std::io::stderr()))?;

  loop {
    terminal.draw(|f| {
      let rect = centered_rect(f.area(), 35, 35);
      f.render_widget(
        Paragraph::new("Hello World!\n\n\n'q' to quit")
          .block(
            Block::default().title("Ratatui").title_alignment(Alignment::Center).borders(Borders::all()),
          )
          .alignment(Alignment::Center),
        rect,
      );
    })?;

    if crossterm::event::poll(std::time::Duration::from_millis(250))? {
      if let crossterm::event::Event::Key(key) = crossterm::event::read()? {
        if key.code == crossterm::event::KeyCode::Char('q') {
          break;
        }
      }
    }
  }
  exit()?;

  Ok(())
}
```

--------------------------------

### Run the Shadow example

Source: https://ratatui.rs/examples/widgets/shadow

Clone the ratatui repository at version v0.30.2 and run the shadow example using cargo.

```shell
git clone https://github.com/ratatui/ratatui.git --branch ratatui-v0.30.2 --depth 1
cd ratatui
cargo run -p ratatui-widgets --example shadow
```

--------------------------------

### Install cargo-generate

Source: https://ratatui.rs/tutorials/hello-ratatui

Installs cargo-generate, a tool used to create a Rust project from a template. The installation instructions cover other options.

```shell
cargo install --locked cargo-generate
```

--------------------------------

### Counter App refactored using TEA

Source: https://ratatui.rs/concepts/application-patterns/the-elm-architecture

Complete Rust example of a counter TUI application using the Elm Architecture. It includes a Model struct, Message enum, main loop, view, event handling, update logic, and a tui module for terminal setup and cleanup. The app increments/decrements a counter with 'j'/'k' keys, resets at ±50, and quits with 'q'.

```rust
use std::time::Duration;

use ratatui::{
    crossterm::event::{self, Event, KeyCode},
    widgets::Paragraph,
    Frame,
};

#[derive(Debug, Default)]
struct Model {
    counter: i32,
    running_state: RunningState,
}

#[derive(Debug, Default, PartialEq, Eq)]
enum RunningState {
    #[default]
    Running,
    Done,
}

#[derive(PartialEq)]
enum Message {
    Increment,
    Decrement,
    Reset,
    Quit,
}

fn main() -> color_eyre::Result<()> {
    tui::install_panic_hook();
    let mut terminal = tui::init_terminal()?;
    let mut model = Model::default();

    while model.running_state != RunningState::Done {
        // Render the current view
        terminal.draw(|f| view(&mut model, f))?;

        // Handle events and map to a Message
        let mut current_msg = handle_event(&model)?;

        // Process updates as long as they return a non-None message
        while current_msg.is_some() {
            current_msg = update(&mut model, current_msg.unwrap());
        }
    }

    tui::restore_terminal()?;
    Ok(())
}

fn view(model: &mut Model, frame: &mut Frame) {
    frame.render_widget(
        Paragraph::new(format!("Counter: {}", model.counter)),
        frame.area(),
    );
}

/// Convert Event to Message
///
/// We don't need to pass in a `model` to this function in this example
/// but you might need it as your project evolves
fn handle_event(_: &Model) -> color_eyre::Result<Option<Message>> {
    if event::poll(Duration::from_millis(250))?
        && let Event::Key(key) = event::read()?
        && key.kind == event::KeyEventKind::Press
    {
        return Ok(handle_key(key));
    }
    Ok(None)
}

fn handle_key(key: event::KeyEvent) -> Option<Message> {
    match key.code {
        KeyCode::Char('j') => Some(Message::Increment),
        KeyCode::Char('k') => Some(Message::Decrement),
        KeyCode::Char('q') => Some(Message::Quit),
        _ => None,
    }
}

fn update(model: &mut Model, msg: Message) -> Option<Message> {
    match msg {
        Message::Increment => {
            model.counter += 1;
            if model.counter > 50 {
                return Some(Message::Reset);
            }
        }
        Message::Decrement => {
            model.counter -= 1;
            if model.counter < -50 {
                return Some(Message::Reset);
            }
        }
        Message::Reset => model.counter = 0,
        Message::Quit => {
            // You can handle cleanup and exit here
            model.running_state = RunningState::Done;
        }
    };
    None
}

mod tui {
    use ratatui::{
        backend::{Backend, CrosstermBackend},
        crossterm::{
            terminal::{
                disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen,
            },
            ExecutableCommand,
        },
        Terminal,
    };
    use std::{io::{self, stdout}, panic};

    pub fn init_terminal() -> color_eyre::Result<Terminal<impl Backend<Error = io::Error>>> {
        enable_raw_mode()?;
        stdout().execute(EnterAlternateScreen)?;
        let terminal = Terminal::new(CrosstermBackend::new(stdout()))?;
        Ok(terminal)
    }

    pub fn restore_terminal() -> color_eyre::Result<()> {
        stdout().execute(LeaveAlternateScreen)?;
        disable_raw_mode()?;
        Ok(())
    }

    pub fn install_panic_hook() {
        let original_hook = panic::take_hook();
        panic::set_hook(Box::new(move |panic_info| {
            stdout().execute(LeaveAlternateScreen).unwrap();
            disable_raw_mode().unwrap();
            original_hook(panic_info);
        }));
    }
}

```

--------------------------------

### constraint-explorer.rs - full example source

Source: https://ratatui.rs/examples/layout/constraint-explorer

Complete Rust source for the constraint explorer. Demonstrates layout constraints (Length, Percentage, Ratio, Min, Max, Fill) with keyboard controls: 1-6 to swap constraints, +/- to change spacing, x/a to delete/insert blocks, j/k/h/l to adjust value and navigate. Requires color-eyre, crossterm, itertools, ratatui, strum.

```rust
use std::cmp::Ordering;

/// A Ratatui example that demonstrates how different layout constraints work.
///
/// It also supports swapping constraints, adding and removing blocks, and changing the spacing
/// between blocks.
///
/// This example runs with the Ratatui library code in the branch that you are currently
/// reading. See the [`latest`] branch for the code which works with the most recent Ratatui
/// release.
///
/// [`latest`]: https://github.com/ratatui/ratatui/tree/latest
use color_eyre::Result;
use crossterm::event::{self, KeyCode};
use itertools::Itertools;
use ratatui::DefaultTerminal;
use ratatui::buffer::Buffer;
use ratatui::layout::Constraint::{self, Fill, Length, Max, Min, Percentage, Ratio};
use ratatui::layout::{Flex, Layout, Rect};
use ratatui::style::palette::tailwind::{BLUE, SKY, SLATE, STONE};
use ratatui::style::{Color, Style, Stylize};
use ratatui::symbols::{self, line};
use ratatui::text::{Line, Span, Text};
use ratatui::widgets::{Block, Paragraph, Widget, Wrap};
use strum::{Display, EnumIter, FromRepr};

fn main() -> Result<()> {
    color_eyre::install()?;
    ratatui::run(|terminal| App::default().run(terminal))
}

#[derive(Default)]
struct App {
    mode: AppMode,
    spacing: i16,
    constraints: Vec<Constraint>,
    selected_index: usize,
    value: u16,
}

#[derive(Debug, Default, PartialEq, Eq)]
enum AppMode {
    #[default]
    Running,
    Quit,
}

/// A variant of [`Constraint`] that can be rendered as a tab.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, EnumIter, FromRepr, Display)]
enum ConstraintName {
    #[default]
    Length,
    Percentage,
    Ratio,
    Min,
    Max,
    Fill,
}

/// A widget that renders a [`Constraint`] as a block. E.g.:
/// ```plain
/// ┌──────────────┐
/// │  Length(16)  │
/// │     16px     │
/// └──────────────┘
/// ```
struct ConstraintBlock {
    constraint: Constraint,
    legend: bool,
    selected: bool,
}

/// A widget that renders a spacer with a label indicating the width of the spacer. E.g.:
///
/// ```plain
/// ┌      ┐
///   8 px
/// └      ┘
/// ```
struct SpacerBlock;

// App behaviour
impl App {
    fn run(mut self, terminal: &mut DefaultTerminal) -> Result<()> {
        self.insert_test_defaults();

        while self.is_running() {
            terminal.draw(|frame| frame.render_widget(&self, frame.area()))?;
            self.handle_events()?;
        }
        Ok(())
    }

    // TODO remove these - these are just for testing
    fn insert_test_defaults(&mut self) {
        self.constraints = vec![
            Constraint::Length(20),
            Constraint::Length(20),
            Constraint::Length(20),
        ];
        self.value = 20;
    }

    fn is_running(&self) -> bool {
        self.mode == AppMode::Running
    }

    fn handle_events(&mut self) -> Result<()> {
        if let Some(key) = event::read()?.as_key_press_event() {
            match key.code {
                KeyCode::Char('q') | KeyCode::Esc => self.exit(),
                KeyCode::Char('1') => self.swap_constraint(ConstraintName::Min),
                KeyCode::Char('2') => self.swap_constraint(ConstraintName::Max),
                KeyCode::Char('3') => self.swap_constraint(ConstraintName::Length),
                KeyCode::Char('4') => self.swap_constraint(ConstraintName::Percentage),
                KeyCode::Char('5') => self.swap_constraint(ConstraintName::Ratio),
                KeyCode::Char('6') => self.swap_constraint(ConstraintName::Fill),
                KeyCode::Char('+') => self.increment_spacing(),
                KeyCode::Char('-') => self.decrement_spacing(),
                KeyCode::Char('x') => self.delete_block(),
                KeyCode::Char('a') => self.insert_block(),
                KeyCode::Char('k') | KeyCode::Up => self.increment_value(),
                KeyCode::Char('j') | KeyCode::Down => self.decrement_value(),
                KeyCode::Char('h') | KeyCode::Left => self.prev_block(),
                KeyCode::Char('l') | KeyCode::Right => self.next_block(),
                _ => {}
            }
        }
        Ok(())
    }
```
Tokens:
Raw