Struct App 

pub struct App<S> { /* private fields */ }

Application runner that manages the main loop.

Handles window setup, input polling, and timing so you can focus on your application logic. Can run in event-driven mode (default) or with a fixed frame rate for animated applications (and possibly games in the future).

Implementations

impl<S> App<S>

pub fn new(initial_state: S) -> Result<Self>

Creates a new app with the given initial state.

Examples found in repository

examples/widget_usage.rs (line 19)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Quit on 'q' (supports both modifier-aware and legacy events).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            let (w, h) = window.get_size();
            create_app_layout(w, h).draw(window)?;
            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/custom_colors.rs (line 37)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Return false to exit.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            let (width, height) = window.get_size();

            // Title
            window.write_str(0, 0, "RGB Color & Gradient Demo (press 'q' to quit)")?;

            // --- All drawing calls happen here ---
            draw_rainbow_gradient(window, 2, width)?;
            draw_color_themes(window, 6)?;
            draw_vertical_gradient(window, 12, width, height)?;
            draw_color_blocks(window, height)?;

            window.end_frame()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/syntax_profile_demo.rs (lines 22-25)

fn main() -> minui::Result<()> {
    let profile_store = Arc::new(Mutex::new(None));

    let mut app = App::new(DemoState {
        frame_count: 0,
        latest_profile: Arc::clone(&profile_store),
    })?
    .with_frame_rate(Duration::from_millis(16))
    .with_frame_budget(Duration::from_millis(16));

    {
        let store = Arc::clone(&profile_store);
        app.set_frame_profile_hook(move |profile| {
            if let Ok(mut slot) = store.lock() {
                *slot = Some(*profile);
            }
        });
    }

    app.run(
        |state, event| {
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => return false,
                Event::Character('q') => return false,
                Event::Frame => {
                    state.frame_count = state.frame_count.saturating_add(1);
                }
                _ => {}
            }
            true
        },
        |state, window| {
            draw_header(window)?;
            draw_code(window)?;
            draw_profile_footer(state, window)?;
            window.flush()?;
            Ok(())
        },
    )
}

examples/app_runner.rs (line 27)

fn main() -> minui::Result<()> {
    // Start with player at position (5, 5)
    let initial_state = MyCoolApp { x: 5, y: 5 };

    // Enable a fixed frame rate (timed updates) every 100ms
    let mut app = App::new(initial_state)?.with_frame_rate(Duration::from_millis(100));

    // Run the main loop with update and draw functions
    app.run(
        // Update function: handle events and modify state
        // Return false to exit, true to continue
        |state, event| {
            match event {
                // Prefer modifier-aware key events (the keyboard handler may emit these for most keys).
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Char('q') => return false,
                    KeyKind::Up => state.y = state.y.saturating_sub(1),
                    KeyKind::Down => state.y += 1,
                    KeyKind::Left => state.x = state.x.saturating_sub(1),
                    KeyKind::Right => state.x += 1,
                    _ => {}
                },

                // Legacy fallback.
                Event::Character('q') => return false,

                Event::KeyUp => state.y = state.y.saturating_sub(1),
                Event::KeyDown => state.y += 1,
                Event::KeyLeft => state.x = state.x.saturating_sub(1),
                Event::KeyRight => state.x += 1,

                Event::Frame => {
                    // Automatic movement every frame event (100ms)
                    state.x += 1;
                }
                _ => {}
            }
            // Keep running
            true
        },
        // Draw function: render the current state
        |state, window| {
            window.write_str(state.y, state.x, "@")?;
            window.write_str(0, 0, "Press 'q' to quit")?;
            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/basic_usage.rs (line 83)

fn main() -> minui::Result<()> {
    // Create a new application instance with unit state `()`.
    // This is the simplest case - we don't need to track any application state.
    // For more complex apps, you'd pass a struct like `MyAppState { ... }`.
    let mut app = App::new(())?;

    // Run the application with update and draw closures.
    // The app handles the event loop, window management, and rendering for you.
    app.run(
        // ========== UPDATE CLOSURE ==========
        // Called whenever there's an input event (keyboard, mouse, etc.)
        // Purpose: Update application state based on user input
        // Returns: true to continue running, false to exit
        |_state, event| {
            // Handle the 'q' key to quit the application.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        // ========== DRAW CLOSURE ==========
        // Called after each update to render the current application state
        // Purpose: Draw the UI based on the current state
        // The window parameter is where you draw everything
        |_state, window| {
            // Create a simple label widget centered on the screen
            let label = Label::new("Press 'q' to quit").with_alignment(Alignment::Center);

            // Draw the label to the window
            // MinUI handles positioning, sizing, and rendering automatically
            label.draw(window)?;

            // Flush buffered rendering (App no longer auto-flushes after draw)
            window.flush()?;

            // Return Ok(()) to indicate drawing succeeded
            Ok(())
        },
    )?;

    // If we reach here, the app exited successfully
    Ok(())
}

examples/color_usage.rs (line 12)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Return false to exit.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            // Display title at the top
            window.write_str(0, 0, "Color Demo (press 'q' to quit)")?;

            // Demonstrate all available foreground colors on black background
            let colors = [
                Color::Red,
                Color::Green,
                Color::Yellow,
                Color::Blue,
                Color::Magenta,
                Color::Cyan,
                Color::White,
            ];

            // Display each color name in its corresponding color
            for (i, &color) in colors.iter().enumerate() {
                let color_pair = ColorPair::new(color, Color::Black);
                window.write_str_colored(
                    2,               // Row 2
                    (i as u16) * 10, // Column 0, 10, 20, etc.
                    &format!("{:?}", color),
                    color_pair,
                )?;
            }

            // Show practical examples of color usage for different types of messages
            window.write_str_colored(
                4,
                0,
                "Error: Something went wrong!",
                ColorPair::new(Color::Red, Color::Black),
            )?;

            window.write_str_colored(
                5,
                0,
                "Success: Operation completed!",
                ColorPair::new(Color::Green, Color::Black),
            )?;

            window.write_str_colored(
                6,
                0,
                "Warning: Disk space low",
                ColorPair::new(Color::Yellow, Color::Black),
            )?;

            // Example of using background color for emphasis
            window.write_str_colored(
                7,
                0,
                "URGENT: System failure! jk :)",
                ColorPair::new(Color::Black, Color::Red),
            )?;

            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

Additional examples can be found in:

• examples/movement.rs
• examples/table_demo.rs
• examples/text_input_demo.rs
• examples/input_demo.rs
• examples/scroll_demo.rs

pub fn window(&self) -> &TerminalWindow

Returns an immutable reference to the underlying terminal window.

This is useful for advanced configuration (e.g. querying capabilities).

pub fn window_mut(&mut self) -> &mut TerminalWindow

Returns a mutable reference to the underlying terminal window.

This enables advanced configuration prior to calling run(), for example:

• toggling mouse movement tracking
• adjusting keybind handlers
• overriding terminal capabilities (color fallback behavior)

Examples found in repository

examples/text_input_demo.rs (line 70)

fn main() -> minui::Result<()> {
    let mut plain = TextInputState::new();
    plain.set_focused(true);

    let mut wrapped = TextInputState::new();
    wrapped.set_focused(false);

    let initial = State {
        focus: Focus::Plain,
        plain,
        wrapped,
        last_submit: String::from("(press Enter to submit focused field)"),

        ui: UiScene::new(),

        mouse_down: false,
        dragging: false,
    };

    let mut app = App::new(initial)?;

    // Ignore mouse-move spam; click/drag events still work.
    app.window_mut().mouse_mut().set_movement_tracking(false);

    app.run(
        // ============================
        // Update
        // ============================
        |state, event| {
            // Apply common scene policies:
            // - observe mouse position
            // - tab traversal (if enabled; this demo uses manual toggle on Tab)
            // - click-to-focus + mouse capture
            let _effects = state.ui.apply_policies(&event);

            // Ignore noisy events we don't use in this demo.
            if matches!(event, Event::MouseMove { .. } | Event::Unknown) {
                return true;
            }

            // Prefer modifier-aware key events first (the keyboard handler may emit these for most keys),
            // with legacy fallback for older event paths.
            if let Event::KeyWithModifiers(k) = event {
                match k.key {
                    KeyKind::Char('q') => return false,
                    KeyKind::Tab => {
                        // Many backends emit modifier-aware Tab (`KeyWithModifiers`) but may not emit
                        // the legacy `Event::Tab`. Since this demo has exactly two fields, we keep a
                        // deterministic, backend-agnostic behavior: toggle focus between them.
                        //
                        // Note: UiScene's built-in tab traversal depends on per-frame registration order
                        // (available after draw), so we intentionally do not use it here.
                        toggle_focus(state);
                        return true;
                    }
                    KeyKind::Enter => {
                        state.last_submit = match state.focus {
                            Focus::Plain => format!("plain: {}", state.plain.text()),
                            Focus::Wrapped => format!("wrapped: {}", state.wrapped.text()),
                        };
                        return true;
                    }
                    _ => {}
                }
            }

            // Quit (legacy fallback)
            if matches!(event, Event::Character('q')) {
                return false;
            }

            // Focus switching (legacy fallback)
            if matches!(event, Event::Tab) {
                // `UiScene` tab traversal relies on the current frame's registered focusables
                // (which only exists after draw). In this demo, we keep a simple, deterministic
                // fallback: toggle between the two fields.
                toggle_focus(state);
                return true;
            }

            // Mouse focus + selection, routed via InteractionCache.
            match event {
                Event::MouseClick { x, y, button: _ } => {
                    state.mouse_down = true;
                    state.dragging = false;

                    // Hit-test against the most recently drawn frame's registry.
                    let hit = state.ui.hit_test_id(x, y);

                    match hit {
                        Some(ID_PLAIN) => {
                            set_focus(state, Focus::Plain);
                            state.plain.click_set_cursor(x);
                            return true;
                        }
                        Some(ID_WRAPPED) => {
                            set_focus(state, Focus::Wrapped);
                            state.wrapped.click_set_cursor(x);
                            return true;
                        }
                        _ => {
                            // Click outside: cancel drag/selection tracking.
                            state.mouse_down = false;
                            state.dragging = false;
                            return true;
                        }
                    }
                }
                Event::MouseDrag { x, y: _, button: _ } => {
                    if !state.mouse_down {
                        return true;
                    }
                    state.dragging = true;

                    // Selection clamps to the field bounds internally.
                    match state.focus {
                        Focus::Plain => {
                            state.plain.drag_select_to(x);
                            return true;
                        }
                        Focus::Wrapped => {
                            state.wrapped.drag_select_to(x);
                            return true;
                        }
                    }
                }
                Event::MouseRelease { x, y: _, button: _ } => {
                    // Finalize drag (one last update on release), then stop tracking.
                    if state.mouse_down && state.dragging {
                        match state.focus {
                            Focus::Plain => state.plain.drag_select_to(x),
                            Focus::Wrapped => state.wrapped.drag_select_to(x),
                        }
                    }

                    state.mouse_down = false;
                    state.dragging = false;
                    return true;
                }
                _ => {}
            }

            // Submit on Enter: copy current focused value to output area (legacy fallback)
            if matches!(event, Event::Enter) {
                state.last_submit = match state.focus {
                    Focus::Plain => format!("plain: {}", state.plain.text()),
                    Focus::Wrapped => format!("wrapped: {}", state.wrapped.text()),
                };
                return true;
            }

            // Route remaining events to the focused field.
            let consumed = match state.focus {
                Focus::Plain => state.plain.handle_event(event),
                Focus::Wrapped => state.wrapped.handle_event(event),
            };

            // If the input didn't consume it, ignore
            consumed
        },
        // ============================
        // Draw
        // ============================
        |state, window| {
            let (w, h) = window.get_size();

            // Begin a fresh immediate-mode scene frame (clears registrations, focusables, owners).
            state.ui.begin_frame();

            // Clear any stale cursor request; focused inputs will request one during draw.
            window.clear_cursor_request();

            // Layout constants
            let margin: u16 = 2;
            let row_gap: u16 = 2;

            // Header
            window.write_str(
                0,
                0,
                "TextInput Demo — click fields, type, Enter to submit, Tab to switch, q to quit",
            )?;

            // Compute field geometry
            let field_w = w.saturating_sub(margin * 2);

            // Plain field at y = 2.
            let plain_y = 2;
            let plain = TextInput::new()
                .with_position(margin, plain_y)
                .with_width(field_w)
                .with_border(true)
                .with_placeholder("Plain input (click to focus)…");

            // Wrapped-in-container field below.
            let wrapped_container_y = plain_y + row_gap + 2;

            // Fixed-height container; input sits on the content line.
            let container_h: u16 = 3;

            let container = Container::new()
                .with_position_and_size(margin, wrapped_container_y, field_w, container_h)
                .with_border()
                .with_border_chars(BorderChars::single_line())
                .with_border_color(ColorPair::new(Color::LightCyan, Color::Transparent))
                .with_title("Wrapped in Container")
                .with_title_alignment(TitleAlignment::Left)
                .with_padding(minui::widgets::ContainerPadding::uniform(0));

            // Output area near bottom
            let output_y = h.saturating_sub(3);
            let output_w = w.saturating_sub(margin * 2);
            let output_prefix = "Last submit: ";
            let output_text = format!("{}{}", output_prefix, state.last_submit);
            let output_line = fit_to_cells(&output_text, output_w, TabPolicy::SingleCell, true);

            // Draw + register plain field
            // NOTE: `TextInput::draw_with_id(...)` registers into an InteractionCache, so we pass
            // the underlying cache from UiScene.
            plain.draw_with_id(window, &mut state.plain, state.ui.cache_mut(), ID_PLAIN)?;

            // Draw container + wrapped field
            container.draw(window)?;

            let inner_x = margin + 1;
            let inner_y = wrapped_container_y + 1;
            let inner_w = field_w.saturating_sub(2);

            let wrapped = TextInput::new()
                .with_position(inner_x, inner_y)
                .with_width(inner_w)
                .with_border(false)
                .with_placeholder("Wrapped input (click to focus)…");

            // Draw + register wrapped field
            wrapped.draw_with_id(window, &mut state.wrapped, state.ui.cache_mut(), ID_WRAPPED)?;

            // Output area box
            window.write_str_colored(
                output_y.saturating_sub(1),
                margin,
                "─ Output ─",
                ColorPair::new(Color::Yellow, Color::Transparent),
            )?;
            window.write_str_colored(
                output_y,
                margin,
                &output_line,
                ColorPair::new(Color::LightGray, Color::Transparent),
            )?;
            window.write_str_colored(
                output_y + 1,
                margin,
                "Tip: Tab switches focus • Enter copies focused text here",
                ColorPair::new(Color::DarkGray, Color::Transparent),
            )?;

            window.end_frame()?;
            Ok(())
        },
    )?;

    Ok(())
}

pub fn with_frame_rate(self, frame_rate: Duration) -> Self

Enables a fixed frame rate (useful for animations and realtime-style terminal apps).

Your update function will receive Event::Frame at regular intervals.

Examples found in repository

examples/syntax_profile_demo.rs (line 26)

fn main() -> minui::Result<()> {
    let profile_store = Arc::new(Mutex::new(None));

    let mut app = App::new(DemoState {
        frame_count: 0,
        latest_profile: Arc::clone(&profile_store),
    })?
    .with_frame_rate(Duration::from_millis(16))
    .with_frame_budget(Duration::from_millis(16));

    {
        let store = Arc::clone(&profile_store);
        app.set_frame_profile_hook(move |profile| {
            if let Ok(mut slot) = store.lock() {
                *slot = Some(*profile);
            }
        });
    }

    app.run(
        |state, event| {
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => return false,
                Event::Character('q') => return false,
                Event::Frame => {
                    state.frame_count = state.frame_count.saturating_add(1);
                }
                _ => {}
            }
            true
        },
        |state, window| {
            draw_header(window)?;
            draw_code(window)?;
            draw_profile_footer(state, window)?;
            window.flush()?;
            Ok(())
        },
    )
}

examples/app_runner.rs (line 27)

fn main() -> minui::Result<()> {
    // Start with player at position (5, 5)
    let initial_state = MyCoolApp { x: 5, y: 5 };

    // Enable a fixed frame rate (timed updates) every 100ms
    let mut app = App::new(initial_state)?.with_frame_rate(Duration::from_millis(100));

    // Run the main loop with update and draw functions
    app.run(
        // Update function: handle events and modify state
        // Return false to exit, true to continue
        |state, event| {
            match event {
                // Prefer modifier-aware key events (the keyboard handler may emit these for most keys).
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Char('q') => return false,
                    KeyKind::Up => state.y = state.y.saturating_sub(1),
                    KeyKind::Down => state.y += 1,
                    KeyKind::Left => state.x = state.x.saturating_sub(1),
                    KeyKind::Right => state.x += 1,
                    _ => {}
                },

                // Legacy fallback.
                Event::Character('q') => return false,

                Event::KeyUp => state.y = state.y.saturating_sub(1),
                Event::KeyDown => state.y += 1,
                Event::KeyLeft => state.x = state.x.saturating_sub(1),
                Event::KeyRight => state.x += 1,

                Event::Frame => {
                    // Automatic movement every frame event (100ms)
                    state.x += 1;
                }
                _ => {}
            }
            // Keep running
            true
        },
        // Draw function: render the current state
        |state, window| {
            window.write_str(state.y, state.x, "@")?;
            window.write_str(0, 0, "Press 'q' to quit")?;
            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/movement.rs (line 19)

fn main() -> minui::Result<()> {
    let initial_state = MovementState { x: 2, y: 2 };

    let mut app = App::new(initial_state)?.with_frame_rate(Duration::from_millis(50));

    app.run(
        |state, event| {
            let (width, height) = (80u16, 24u16); // Reasonable defaults

            match event {
                // Prefer modifier-aware key events first (the keyboard handler may emit these for most keys).
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Char('q') | KeyKind::Escape => return false,

                    KeyKind::Up => {
                        if state.y > 0 {
                            state.y -= 1;
                        }
                    }
                    KeyKind::Down => {
                        if state.y < height - 1 {
                            state.y += 1;
                        }
                    }
                    KeyKind::Left => {
                        if state.x > 0 {
                            state.x -= 1;
                        }
                    }
                    KeyKind::Right => {
                        if state.x < width - 1 {
                            state.x += 1;
                        }
                    }
                    _ => {}
                },

                // Legacy fallback.
                Event::Character('q') | Event::Escape => return false,
                Event::KeyUp => {
                    if state.y > 0 {
                        state.y -= 1;
                    }
                }
                Event::KeyDown => {
                    if state.y < height - 1 {
                        state.y += 1;
                    }
                }
                Event::KeyLeft => {
                    if state.x > 0 {
                        state.x -= 1;
                    }
                }
                Event::KeyRight => {
                    if state.x < width - 1 {
                        state.x += 1;
                    }
                }

                _ => {}
            }

            true
        },
        |state, window| {
            let (width, height) = window.get_size();

            // Draw instructions
            let instructions =
                Label::new("Use arrow keys to move, 'q' to quit").with_text_color(Color::Cyan);
            instructions.draw(window)?;

            // Draw the player character
            window.write_str_colored(
                state.y,
                state.x,
                "@",
                ColorPair::new(Color::Green, Color::Transparent),
            )?;

            // Draw boundary indicators
            window.write_str(
                height - 1,
                0,
                &format!(
                    "Position: ({}, {}) | Terminal: {}x{}",
                    state.x, state.y, width, height
                ),
            )?;

            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/input_demo.rs (line 37)

fn main() -> minui::Result<()> {
    let initial_state = InputDemoState {
        event_log: {
            let mut log = VecDeque::new();
            log.push_back("Welcome to MinUI Input Demo!".to_string());
            log.push_back("Try typing, moving mouse, clicking...".to_string());
            log.push_back("Double-click quickly to see double-click detection!".to_string());
            log.push_back("Press 'q' to quit".to_string());
            log
        },
        mouse_pos: (0, 0),
        click_tracker: ClickTracker::new(),
    };

    let mut app = App::new(initial_state)?.with_frame_rate(Duration::from_millis(16));

    app.run(
        |state, event| {
            // Return false to exit (supports modifier-aware and legacy events).
            if let Event::KeyWithModifiers(k) = event {
                if matches!(k.key, KeyKind::Char('q')) {
                    return false;
                }
            }
            if matches!(event, Event::Character('q')) {
                return false;
            }

            // Handle events and update state
            match event {
                // Prefer modifier-aware keyboard events (the keyboard handler may emit these for most keys).
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Char(c) => {
                        state.event_log.push_back(format!(
                            "Key: '{}' (mods: shift={}, ctrl={}, alt={}, super={})",
                            c, k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Up => {
                        state.event_log.push_back(format!(
                            "Key: ↑ Up (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Down => {
                        state.event_log.push_back(format!(
                            "Key: ↓ Down (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Left => {
                        state.event_log.push_back(format!(
                            "Key: ← Left (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Right => {
                        state.event_log.push_back(format!(
                            "Key: → Right (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Enter => {
                        state.event_log.push_back(format!(
                            "Key: ⏎ Enter (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Escape => {
                        state.event_log.push_back(format!(
                            "Key: Escape (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Backspace => {
                        state.event_log.push_back(format!(
                            "Key: ⌫ Backspace (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Delete => {
                        state.event_log.push_back(format!(
                            "Key: ⌦ Delete (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Tab => {
                        state.event_log.push_back(format!(
                            "Key: Tab (mods: shift={}, ctrl={}, alt={}, super={})",
                            k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::Function(n) => {
                        state.event_log.push_back(format!(
                            "Key: F{} (mods: shift={}, ctrl={}, alt={}, super={})",
                            n, k.mods.shift, k.mods.ctrl, k.mods.alt, k.mods.super_key
                        ));
                    }
                    KeyKind::CapsLock => todo!(),
                },

                // Legacy fallback keyboard events (some backends may still emit these).
                Event::Character(c) => {
                    state.event_log.push_back(format!("Key: '{}'", c));
                }
                Event::Paste(text) => {
                    // Keep the log readable for large pastes
                    let preview: String = text.chars().take(60).collect();
                    if text.chars().count() > 60 {
                        state.event_log.push_back(format!(
                            "Paste: \"{}…\" ({} chars)",
                            preview,
                            text.chars().count()
                        ));
                    } else {
                        state.event_log.push_back(format!("Paste: \"{}\"", preview));
                    }
                }
                Event::KeyUp => {
                    state.event_log.push_back("Key: ↑ Up".to_string());
                }
                Event::KeyDown => {
                    state.event_log.push_back("Key: ↓ Down".to_string());
                }
                Event::KeyLeft => {
                    state.event_log.push_back("Key: ← Left".to_string());
                }
                Event::KeyRight => {
                    state.event_log.push_back("Key: → Right".to_string());
                }
                Event::Enter => {
                    state.event_log.push_back("Key: ⏎ Enter".to_string());
                }
                Event::Escape => {
                    state.event_log.push_back("Key: Escape".to_string());
                }
                Event::Backspace => {
                    state.event_log.push_back("Key: ⌫ Backspace".to_string());
                }
                Event::Delete => {
                    state.event_log.push_back("Key: ⌦ Delete".to_string());
                }
                Event::FunctionKey(n) => {
                    state.event_log.push_back(format!("Key: F{}", n));
                }

                // Handle mouse events
                Event::MouseMove { x, y } => {
                    state.mouse_pos = (x, y);
                    // Only log occasional moves to avoid spam
                    if x % 3 == 0 && y % 3 == 0 {
                        state
                            .event_log
                            .push_back(format!("Mouse: Moved to ({}, {})", x, y));
                    }
                }
                Event::MouseClick { x, y, button } => {
                    state.mouse_pos = (x, y);
                    let button_name = match button {
                        MouseButton::Left => "Left",
                        MouseButton::Right => "Right",
                        MouseButton::Middle => "Middle",
                        MouseButton::Other(_) => "Other",
                    };

                    // Check for double-click
                    if state.click_tracker.is_double_click(x, y) {
                        state.event_log.push_back(format!(
                            "Mouse: DOUBLE-CLICK! {} button at ({}, {})",
                            button_name, x, y
                        ));
                    } else {
                        state
                            .event_log
                            .push_back(format!("Mouse: {} click at ({}, {})", button_name, x, y));
                    }
                }
                Event::MouseDrag { x, y, button } => {
                    state.mouse_pos = (x, y);
                    let button_name = match button {
                        MouseButton::Left => "Left",
                        MouseButton::Right => "Right",
                        MouseButton::Middle => "Middle",
                        MouseButton::Other(_) => "Other",
                    };
                    state
                        .event_log
                        .push_back(format!("Mouse: {} drag to ({}, {})", button_name, x, y));
                }
                Event::MouseScroll { delta } => {
                    let direction = if delta > 0 { "up" } else { "down" };
                    state
                        .event_log
                        .push_back(format!("Mouse: Scroll {} ({})", direction, delta));
                }
                Event::MouseScrollHorizontal { delta } => {
                    let direction = if delta > 0 { "right" } else { "left" };
                    state
                        .event_log
                        .push_back(format!("Mouse: Scroll {} ({})", direction, delta));
                }
                Event::MouseRelease { x, y, button } => {
                    state.mouse_pos = (x, y);
                    let button_name = match button {
                        MouseButton::Left => "Left",
                        MouseButton::Right => "Right",
                        MouseButton::Middle => "Middle",
                        MouseButton::Other(_) => "Other",
                    };
                    state
                        .event_log
                        .push_back(format!("Mouse: {} release at ({}, {})", button_name, x, y));
                }

                Event::Resize { width, height } => {
                    state
                        .event_log
                        .push_back(format!("Terminal: Resized to {}x{}", width, height));
                }
                _ => {}
            }

            // Keep the log at reasonable size
            if state.event_log.len() > MAX_EVENTS {
                state.event_log.pop_front();
            }

            true
        },
        |state, window| {
            let (term_width, term_height) = window.get_size();

            // Create a container to display the events.
            //
            // Panel has been absorbed into Container: use borders + title + padding, and put
            // content widgets inside as children.
            // NOTE: `ContainerPadding` is the name exported by the prelude for Container's padding type.
            // (The underlying type in `container.rs` is `Padding`.)
            use minui::widgets::ContainerPadding;

            let panel_x: u16 = 2u16;
            let panel_y: u16 = 1u16;
            let panel_w: u16 = term_width.saturating_sub(4u16);
            let panel_h: u16 = term_height.saturating_sub(4u16);

            // Render the log as stacked labels so each event appears on its own line.
            // We display the newest entries at the top (reverse chronological).
            let mut log_container = Container::vertical().with_row_gap(Gap::Pixels(0u16));
            if state.event_log.is_empty() {
                log_container = log_container.add_child(Label::new("No events yet..."));
            } else {
                for line in state.event_log.iter().rev().take(MAX_EVENTS) {
                    log_container = log_container.add_child(Label::new(line.clone()));
                }
            }

            let panel = Container::new()
                .with_position_and_size(panel_x, panel_y, panel_w, panel_h)
                .with_border()
                .with_border_chars(BorderChars::double_line())
                .with_border_color(ColorPair::new(Color::Cyan, Color::Black))
                .with_title("MinUI Input Demo")
                .with_title_alignment(TitleAlignment::Center)
                .with_padding(ContainerPadding::uniform(1u16))
                .add_child(log_container);

            panel.draw(window)?;

            // Draw mouse position info at bottom
            let mouse_info = format!("Mouse: ({}, {})", state.mouse_pos.0, state.mouse_pos.1);
            let info_y = term_height.saturating_sub(2);
            window.write_str_colored(
                info_y,
                2,
                &mouse_info,
                ColorPair::new(Color::Cyan, Color::Transparent),
            )?;

            // Draw instructions at the very bottom
            let help_text = "Press 'q' to quit | Try typing, clicking, scrolling!";
            let help_x = (term_width.saturating_sub(help_text.len() as u16)) / 2;
            let help_y = term_height.saturating_sub(1);
            window.write_str_colored(
                help_y,
                help_x,
                help_text,
                ColorPair::new(Color::DarkGray, Color::Transparent),
            )?;

            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

pub fn with_frame_budget(self, budget: Duration) -> Self

Sets a soft frame-time budget used for profiling.

Frame pacing is controlled by App::with_frame_rate.

Examples found in repository

examples/syntax_profile_demo.rs (line 27)

fn main() -> minui::Result<()> {
    let profile_store = Arc::new(Mutex::new(None));

    let mut app = App::new(DemoState {
        frame_count: 0,
        latest_profile: Arc::clone(&profile_store),
    })?
    .with_frame_rate(Duration::from_millis(16))
    .with_frame_budget(Duration::from_millis(16));

    {
        let store = Arc::clone(&profile_store);
        app.set_frame_profile_hook(move |profile| {
            if let Ok(mut slot) = store.lock() {
                *slot = Some(*profile);
            }
        });
    }

    app.run(
        |state, event| {
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => return false,
                Event::Character('q') => return false,
                Event::Frame => {
                    state.frame_count = state.frame_count.saturating_add(1);
                }
                _ => {}
            }
            true
        },
        |state, window| {
            draw_header(window)?;
            draw_code(window)?;
            draw_profile_footer(state, window)?;
            window.flush()?;
            Ok(())
        },
    )
}

pub fn set_frame_profile_hook<F>(&mut self, hook: F)

where F: FnMut(&FrameProfile) + 'static,

Installs a per-frame profiling hook.

Examples found in repository

examples/syntax_profile_demo.rs (lines 31-35)

fn main() -> minui::Result<()> {
    let profile_store = Arc::new(Mutex::new(None));

    let mut app = App::new(DemoState {
        frame_count: 0,
        latest_profile: Arc::clone(&profile_store),
    })?
    .with_frame_rate(Duration::from_millis(16))
    .with_frame_budget(Duration::from_millis(16));

    {
        let store = Arc::clone(&profile_store);
        app.set_frame_profile_hook(move |profile| {
            if let Ok(mut slot) = store.lock() {
                *slot = Some(*profile);
            }
        });
    }

    app.run(
        |state, event| {
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => return false,
                Event::Character('q') => return false,
                Event::Frame => {
                    state.frame_count = state.frame_count.saturating_add(1);
                }
                _ => {}
            }
            true
        },
        |state, window| {
            draw_header(window)?;
            draw_code(window)?;
            draw_profile_footer(state, window)?;
            window.flush()?;
            Ok(())
        },
    )
}

pub fn clear_frame_profile_hook(&mut self)

Removes the current profiling hook.

pub fn run<U, D>(&mut self, update: U, draw: D) -> Result<()>

where U: FnMut(&mut S, Event) -> bool, D: FnMut(&mut S, &mut dyn Window) -> Result<()>,

Runs the main application loop.

• update: Called for each event. Return false to exit.
• draw: Called to render the current state.

Examples found in repository

examples/widget_usage.rs (lines 21-36)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Quit on 'q' (supports both modifier-aware and legacy events).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            let (w, h) = window.get_size();
            create_app_layout(w, h).draw(window)?;
            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/custom_colors.rs (lines 39-67)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Return false to exit.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            let (width, height) = window.get_size();

            // Title
            window.write_str(0, 0, "RGB Color & Gradient Demo (press 'q' to quit)")?;

            // --- All drawing calls happen here ---
            draw_rainbow_gradient(window, 2, width)?;
            draw_color_themes(window, 6)?;
            draw_vertical_gradient(window, 12, width, height)?;
            draw_color_blocks(window, height)?;

            window.end_frame()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/syntax_profile_demo.rs (lines 38-57)

fn main() -> minui::Result<()> {
    let profile_store = Arc::new(Mutex::new(None));

    let mut app = App::new(DemoState {
        frame_count: 0,
        latest_profile: Arc::clone(&profile_store),
    })?
    .with_frame_rate(Duration::from_millis(16))
    .with_frame_budget(Duration::from_millis(16));

    {
        let store = Arc::clone(&profile_store);
        app.set_frame_profile_hook(move |profile| {
            if let Ok(mut slot) = store.lock() {
                *slot = Some(*profile);
            }
        });
    }

    app.run(
        |state, event| {
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => return false,
                Event::Character('q') => return false,
                Event::Frame => {
                    state.frame_count = state.frame_count.saturating_add(1);
                }
                _ => {}
            }
            true
        },
        |state, window| {
            draw_header(window)?;
            draw_code(window)?;
            draw_profile_footer(state, window)?;
            window.flush()?;
            Ok(())
        },
    )
}

examples/app_runner.rs (lines 30-69)

fn main() -> minui::Result<()> {
    // Start with player at position (5, 5)
    let initial_state = MyCoolApp { x: 5, y: 5 };

    // Enable a fixed frame rate (timed updates) every 100ms
    let mut app = App::new(initial_state)?.with_frame_rate(Duration::from_millis(100));

    // Run the main loop with update and draw functions
    app.run(
        // Update function: handle events and modify state
        // Return false to exit, true to continue
        |state, event| {
            match event {
                // Prefer modifier-aware key events (the keyboard handler may emit these for most keys).
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Char('q') => return false,
                    KeyKind::Up => state.y = state.y.saturating_sub(1),
                    KeyKind::Down => state.y += 1,
                    KeyKind::Left => state.x = state.x.saturating_sub(1),
                    KeyKind::Right => state.x += 1,
                    _ => {}
                },

                // Legacy fallback.
                Event::Character('q') => return false,

                Event::KeyUp => state.y = state.y.saturating_sub(1),
                Event::KeyDown => state.y += 1,
                Event::KeyLeft => state.x = state.x.saturating_sub(1),
                Event::KeyRight => state.x += 1,

                Event::Frame => {
                    // Automatic movement every frame event (100ms)
                    state.x += 1;
                }
                _ => {}
            }
            // Keep running
            true
        },
        // Draw function: render the current state
        |state, window| {
            window.write_str(state.y, state.x, "@")?;
            window.write_str(0, 0, "Press 'q' to quit")?;
            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

examples/basic_usage.rs (lines 87-122)

fn main() -> minui::Result<()> {
    // Create a new application instance with unit state `()`.
    // This is the simplest case - we don't need to track any application state.
    // For more complex apps, you'd pass a struct like `MyAppState { ... }`.
    let mut app = App::new(())?;

    // Run the application with update and draw closures.
    // The app handles the event loop, window management, and rendering for you.
    app.run(
        // ========== UPDATE CLOSURE ==========
        // Called whenever there's an input event (keyboard, mouse, etc.)
        // Purpose: Update application state based on user input
        // Returns: true to continue running, false to exit
        |_state, event| {
            // Handle the 'q' key to quit the application.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        // ========== DRAW CLOSURE ==========
        // Called after each update to render the current application state
        // Purpose: Draw the UI based on the current state
        // The window parameter is where you draw everything
        |_state, window| {
            // Create a simple label widget centered on the screen
            let label = Label::new("Press 'q' to quit").with_alignment(Alignment::Center);

            // Draw the label to the window
            // MinUI handles positioning, sizing, and rendering automatically
            label.draw(window)?;

            // Flush buffered rendering (App no longer auto-flushes after draw)
            window.flush()?;

            // Return Ok(()) to indicate drawing succeeded
            Ok(())
        },
    )?;

    // If we reach here, the app exited successfully
    Ok(())
}

examples/color_usage.rs (lines 14-86)

fn main() -> minui::Result<()> {
    let mut app = App::new(())?;

    app.run(
        |_state, event| {
            // Return false to exit.
            //
            // The keyboard handler may emit:
            // - `Event::KeyWithModifiers(KeyKind::Char('q'))` (modifier-aware), or
            // - `Event::Character('q')` (legacy fallback).
            match event {
                Event::KeyWithModifiers(k) if matches!(k.key, KeyKind::Char('q')) => false,
                Event::Character('q') => false,
                _ => true,
            }
        },
        |_state, window| {
            // Display title at the top
            window.write_str(0, 0, "Color Demo (press 'q' to quit)")?;

            // Demonstrate all available foreground colors on black background
            let colors = [
                Color::Red,
                Color::Green,
                Color::Yellow,
                Color::Blue,
                Color::Magenta,
                Color::Cyan,
                Color::White,
            ];

            // Display each color name in its corresponding color
            for (i, &color) in colors.iter().enumerate() {
                let color_pair = ColorPair::new(color, Color::Black);
                window.write_str_colored(
                    2,               // Row 2
                    (i as u16) * 10, // Column 0, 10, 20, etc.
                    &format!("{:?}", color),
                    color_pair,
                )?;
            }

            // Show practical examples of color usage for different types of messages
            window.write_str_colored(
                4,
                0,
                "Error: Something went wrong!",
                ColorPair::new(Color::Red, Color::Black),
            )?;

            window.write_str_colored(
                5,
                0,
                "Success: Operation completed!",
                ColorPair::new(Color::Green, Color::Black),
            )?;

            window.write_str_colored(
                6,
                0,
                "Warning: Disk space low",
                ColorPair::new(Color::Yellow, Color::Black),
            )?;

            // Example of using background color for emphasis
            window.write_str_colored(
                7,
                0,
                "URGENT: System failure! jk :)",
                ColorPair::new(Color::Black, Color::Red),
            )?;

            window.flush()?;
            Ok(())
        },
    )?;

    Ok(())
}

Additional examples can be found in:

• examples/movement.rs
• examples/table_demo.rs
• examples/text_input_demo.rs
• examples/input_demo.rs
• examples/scroll_demo.rs