This crate is a part of rat-salsa.

For examples see rat-focus GitHub.

• Changes

Focus handling for ratatui

This crate works by adding a FocusFlag to each widget' s state.

FocusBuilder then is used to collect an ordered list of all widgets that should be considered for focus handling. It builds up the Focus which has next, prev and focus_at which can do the navigation.

from <focus_input1.rs>

    fn focus_input(state: &mut State) -> Focus {
    let mut fb = FocusBuilder::default();
    fb.widget(&state.input1)
        .widget(&state.input2)
        .widget(&state.input3)
        .widget(&state.input4);
    fb.build()
}

fn handle_input(
    event: &crossterm::event::Event,
    _data: &mut Data,
    _istate: &mut MiniSalsaState,
    state: &mut State,
) -> Result<Outcome, anyhow::Error> {

    // Handle events for focus.
    let f = focus_input(state).handle(event, Regular);

    // ...

    Ok(f)
}

• Keeps the focus-state close to the widgets code.
• Rebuilt for each event.
  • No need to update the widget list when the application state changes.
  • FocusBuilder can be passed on all over the application to build the current widget list.

Event handling

React to focus events

Event handling is implemented for crossterm. It uses Tab+BackTab for navigation and handles mouse clicks on the widget's area.

Focus implements HandleEvent, and there is the fn handle_focus to invoke it.

    // Handle events for focus.
let f = focus_input(state).handle(event, Regular);

It returns Outcome::Changed whenever something interesting has happened.

Widget events

If the widgets has it's own FocusFlag, it will decide the appropriate event handling using this state. No external control needed.

If it doesn't you can use a [FocusAdapter] to keep track of the focus. Use that state to call the appropriate functions defined by the widget.

Traits and Widgets

HasFocus

[HasFocus] is the interface for single widgets.

It is implemented for the widget state struct and provides access to

• focus() - FocusFlag
• area() - Rendered area.
• z_areas() - Extended area info.
• navigable() - Control flag.

The widget can then use the FocusFlag for rendering and event-handling as it sees fit.

FocusContainer

[FocusContainer] is the interface for container widgets.

This is used to recursively add widgets for focus handling.

• build() - Uses the FocusBuilder to construct the current widget structure.
• container() - Optional. Similar to FocusFlag, identifies the container and collects the states of the contained widgets.
• area() - Optional. Area for the whole container. Used for mouse events too.