Crate rat_focus

Source
Expand description

Current status: BETA

crates.io Documentation License License

This crate is a part of rat-salsa.

For examples see rat-focus GitHub.

§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.

Modules§

  • event
    Rexported eventhandling traits.

Macros§

  • focus_debug
  • match_focus
    Does a match on the state struct of a widget. If widget_state.is_focused() is true the block is executed. There is a _ branch too, that is evaluated if none of the given widget-states has the focus.
  • on_gained
    Does a match on the state struct of a widget. If widget_state.gained_focus() is true the block is executed. This requires that widget_state implements HasFocus, but that’s the basic requirement for this whole crate.
  • on_lost
    Does a match on the state struct of a widget. If widget_state.lost_focus() is true the block is executed. This requires that widget_state implements HasFocus, but that’s the basic requirement for this whole crate.

Structs§

Enums§

Traits§

Functions§