Struct Focus 

pub struct Focus { /* private fields */ }

Focus deals with all focus-related issues.

Use FocusBuilder to construct the current Focus.

This is usually quick enough to do it for each event. It has to be rebuilt if any area has changed, so rebuilding it after a render() is fine.

Implementations

impl Focus

pub fn enable_log(&self)

Writes a log for each operation.

pub fn disable_log(&self)

Writes a log for each operation.

pub fn enable_panic(&self)

Enable insta-panic if any function is called with a widget that is not part of the Focus.

pub fn disable_panic(&self)

Disable insta-panic.

pub fn focus(&self, widget_state: &dyn HasFocus)

Sets the focus to the given widget.

This changes the focus and the gained/lost flags. If this ends up with the same widget as before gained and lost flags are not set.

This will ignore the Navigation flag of the currently focused widget.

You can also use a container-widget for this. It will set the focus to the first navigable widget of the container.

pub fn by_widget_id(&self, widget_id: usize)

Sets the focus to the widget by its widget-id.

This can be useful if you want to store references to widgets in some extra subsystem and can’t use a clone of the FocusFlag for that.

This changes the focus and the gained/lost flags. If this ends up with the same widget as before gained and lost flags are not set.

This will ignore the Navigation flag of the currently focused widget.

You can also use a container-widget for this. It will set the focus to the first widget of the container.

pub fn first(&self)

Set the focus to the first navigable widget.

This changes the focus and the gained/lost flags. If this ends up with the same widget as before gained and lost flags are not set.

This will ignore the Navigation flag of the currently focused widget.

pub fn first_in(&self, container: &dyn HasFocus)

👎Deprecated since 1.1.2: use focus() instead

pub fn none(&self)

Clear the focus for all widgets.

This will reset the focus, gained and lost flags for all widgets.

pub fn future(&self, widget_state: &dyn HasFocus)

This widget will have the focus, but it is not yet part of the focus cycle. And the focus cycle can’t be properly rebuilt at this point.

If the widget is part of the focus this will behave just like [focus].

Caveat:

If the widget will be in a container in the future, the container-flag itself will not be set.

pub fn focus_at(&self, col: u16, row: u16) -> bool

Change to focus to the widget at the given position.

This changes the focus and the gained/lost flags. If this ends up with the same widget as before gained and lost flags are not set.

If the current widget has a Navigation::Lock, this will do nothing.

pub fn next(&self) -> bool

Focus the next widget in the cycle.

This function will use the Navigation of the current widget and only focus the next widget if it is Leave, ReachLeaveBack or Regular.

If no field has the focus the first navigable one gets it. Sets the focus, gained and lost flags. If this ends up with the same widget as before focus, gained and lost flag are not set.

pub fn prev(&self) -> bool

Focus the previous widget in the cycle.

This function will use the Navigation of the current widget and only focus the next widget if it is Leave, ReachLeaveFront or Regular.

If no field has the focus the first navigable one gets it. Sets the focus, gained and lost flags. If this ends up with the same widget as before focus, gained and lost flag are not set.

pub fn next_force(&self) -> bool

Focus the next widget in the cycle.

Applies some extra force to this action and allows leaving widgets that have Navigation Reach and ReachLeaveFront in addition to the regular Leave, ReachLeaveBack or Regular.

If no field has the focus the first navigable one gets it.

Sets the focus, gained and lost flags. If this ends up with the same widget as before focus, gained and lost flag are not set.

pub fn prev_force(&self) -> bool

Focus the previous widget in the cycle.

Applies some extra force to this action and allows leaving widgets that have Navigation Reach and ReachLeaveBack in addition to the regular Leave, ReachLeaveFront or Regular.

If no field has the focus the first navigable one gets it.

Sets the focus, gained and lost flags. If this ends up with the same widget as before focus, gained and lost flag are not set.

pub fn is_valid_widget(&self, widget_state: &dyn HasFocus) -> bool

Is this widget part of this focus-cycle?

pub fn is_valid_container(&self, widget_state: &dyn HasFocus) -> bool

Is this a container that is part of this focus-cycle?

pub fn focused(&self) -> Option<FocusFlag>

Returns the focused widget as FocusFlag.

For control-flow crate::match_focus or crate::on_gained or crate::on_lost will be nicer.

pub fn focused_widget_id(&self) -> Option<usize>

Returns the focused widget as widget-id.

For control-flow crate::match_focus or crate::on_gained or crate::on_lost will be nicer.

pub fn focused_name(&self) -> Option<String>

Returns the debug name of the focused widget.

pub fn navigation(&self) -> Option<Navigation>

Returns the Navigation flag for the focused widget.

pub fn lost_focus(&self) -> Option<FocusFlag>

Returns the widget that lost the focus as FocusFlag.

For control-flow crate::match_focus or crate::on_gained or crate::on_lost will be nicer.

pub fn gained_focus(&self) -> Option<FocusFlag>

Returns the widget that gained the focus as FocusFlag.

For control-flow crate::match_focus or crate::on_gained or crate::on_lost will be nicer.

pub fn focus_no_lost(&self, widget_state: &dyn HasFocus)

Sets the focus to the given widget, but doesn’t set lost and gained. This can be used to prevent any side effects that use the gained/lost state.

This changes the focus and the gained/lost flags. If this ends up with the same widget as before gained and lost flags are not set.

This will ignore the Navigation flag of the currently focused widget.

You can also use a container-widget for this. It will set the focus to the first widget of the container.

pub fn expel_focus(&self, widget_state: &dyn HasFocus)

This expels the focus from the given widget/container.

This is sometimes useful to set the focus to somewhere else. This is especially useful when used for a container-widget that will be hidden. Ensures there is still some widget with focus afterward.

It will try to set the focus to the next widget or the next widget following the container. If this ends up within the given container it will set the focus to none.

This function doesn’t use the Navigation of the current widget.

pub fn remove_container(&mut self, container: &dyn HasFocus)

Dynamic change of the widget structure for a container widget.

This is only necessary if your widget structure changes during event-handling, and you need a programmatic focus-change for the new structure.

This resets the focus-flags of the removed container.

pub fn update_container(&mut self, container: &dyn HasFocus)

Dynamic change of the widget structure for a container.

This is only necessary if your widget structure changes during event-handling, and you need a programmatic focus-change for the new structure.

If the widget that currently has the focus is still part of the widget structure it keeps the focus. The focus-flags for all widgets that are no longer part of the widget structure are reset.

pub fn replace_container( &mut self, container: &dyn HasFocus, new: &dyn HasFocus, )

Dynamic change of the widget structure of a container.

This is only necessary if your widget structure changes during event-handling, and you need a programmatic focus-change.

This removes the widgets of one container and inserts the widgets of the other one in place.

If the widget that currently has the focus is still part of the widget structure it keeps the focus. The focus-flags for all widgets that are no longer part of the widget structure are reset.

pub fn reset_lost_gained(&self)

Reset lost + gained flags.

This is done automatically during event-handling. Lost+Gained flags will only be set while handling the original event that made the focus-change. The next event, whatever it is, will reset these flags.

pub fn clone_destruct( &self, ) -> (Vec<FocusFlag>, Vec<bool>, Vec<(Rect, u16)>, Vec<Navigation>, Vec<(FocusFlag, (Rect, u16), Range<usize>)>)

Debug destructuring.

Trait Implementations

impl Clone for Focus

fn clone(&self) -> Focus

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Focus

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Focus

fn default() -> Focus

Returns the “default value” for a type.

impl HandleEvent<Event, MouseOnly, Outcome> for Focus

fn handle(&mut self, event: &Event, _keymap: MouseOnly) -> Outcome

Handle an event.

impl HandleEvent<Event, Regular, Outcome> for Focus

fn handle(&mut self, event: &Event, _keymap: Regular) -> Outcome

Handle an event.