Struct FocusRing 

pub struct FocusRing { /* private fields */ }

Tracks which child in a list of focusable items is currently focused.

A FocusRing is a simple index tracker with wrap-around cycling. Parent components own it and use it to route events to the focused child and style focused vs. unfocused items during rendering.

Usage

use tui::{FocusRing, FocusOutcome};

let mut ring = FocusRing::new(3);
assert_eq!(ring.focused(), 0);

ring.focus_next();
assert_eq!(ring.focused(), 1);

// Wraps around at the end
ring.focus_next();
ring.focus_next();
assert_eq!(ring.focused(), 0);

Key methods

• new(len) — Create a ring with wrapping enabled, focused at index 0.
• without_wrap() — Disable wrap-around (builder pattern).
• focused() / is_focused(index) — Query the current focus.
• focus_next() / focus_prev() — Advance or retreat. Returns true if focus changed.
• focus(index) — Programmatically set focus. Returns false if out of bounds.
• set_len(len) — Update the item count, clamping focus if needed.
• handle_key(key_event) — Handle Tab/BackTab and return a FocusOutcome.

FocusOutcome

Returned by handle_key:

• FocusChanged — Focus moved to a different index.
• Unchanged — A focus key was pressed but focus didn’t move (e.g. at boundary without wrap).
• Ignored — The key was not Tab or BackTab.

Implementations

impl FocusRing

pub fn new(len: usize) -> Self

Create a new FocusRing with wrapping enabled.

Focus starts at index 0. If len is 0, all navigation is a no-op.

pub fn without_wrap(self) -> Self

Disable wrap-around: focus_next at the last item and focus_prev at the first item will not cycle.

pub fn focused(&self) -> usize

The currently focused index.

pub fn is_focused(&self, index: usize) -> bool

Returns true if index is the currently focused index.

pub fn len(&self) -> usize

The number of focusable items.

pub fn is_empty(&self) -> bool

Returns true if there are no focusable items.

pub fn set_len(&mut self, len: usize)

Update the number of focusable items. Clamps focused if it would be out of bounds.

pub fn focus(&mut self, index: usize) -> bool

Programmatically set focus to index. Returns false if index is out of bounds (focus unchanged).

pub fn focus_next(&mut self) -> bool

Move focus to the next item. Returns true if focus changed.

pub fn focus_prev(&mut self) -> bool

Move focus to the previous item. Returns true if focus changed.

pub fn handle_key(&mut self, key_event: KeyEvent) -> FocusOutcome

Handle Tab (next) and BackTab (previous) key events.

Returns FocusOutcome::FocusChanged if focus moved, FocusOutcome::Unchanged if a focus key was pressed but focus didn’t move, or FocusOutcome::Ignored for all other keys.