tui-world 0.1.4

A state and event management library for TUIs built with ratatui
Documentation

Crates.io Downloads Documentation CI Dependencies License

Core Concepts

  • World - A container that holds application state
  • Keybindings - Key binding registry with built-in help display
  • Focus - Tracks which widget currently has keyboard focus
  • Pointer - Tracks widget areas and handles mouse click/drag/up events
  • InputEvent - Unified input event handling for keyboard and mouse

//! - [World] - A type-safe container that holds application state and resources //! - [Keybindings] - Key binding registry with built-in help display //! - [Focus] - Tracks which widget currently has keyboard focus //! - [Pointer] - Tracks widget areas and handles mouse click/drag/up events //! - [InputEvent] - Unified input event handling for keyboard and mouse

Example

const WIDGET_ID: WidgetId = WidgetId("MyWidget");

let mut world = World::default();

// Store state in world
world.insert(MyAppState::default());

// Register keybindings
world.get_mut::<Keybindings>().bind(WIDGET_ID, KeyCode::Enter, "Select", |world| {
    world.get_mut::<MyAppState>().select();
});

// Check focus
if world.get::<Focus>().is_focused(WIDGET_ID) {
    // widget has focus
}

// Handle key events
InputEvent::Key(key).handle(&mut world, &[WIDGET_ID]);

Mouse Handling

// Register click handlers
world.get_mut::<Pointer>().on_click(WIDGET_ID, |world, area, x, y| {
    let clicked_index = y.saturating_sub(area.y) as usize;
    world.get_mut::<MyAppState>().select(clicked_index);
});

// Register widget area in render function
world.get_mut::<Pointer>().set(WIDGET_ID, area);

// Handle mouse events
InputEvent::Mouse(mouse).handle(&mut world, &[WIDGET_ID]);

See examples/todo and examples/help.rs for complete examples.

License

MIT