Struct zng::focus::FOCUS

pub struct FOCUS;

Keyboard focus service.

Provider

This service is provided by the FocusManager extension.

Implementations

impl FOCUS

pub fn auto_highlight(&self) -> ArcVar<Option<Duration>>

If set to a duration, starts highlighting focus when a focus change happen within the duration of a keyboard input event.

Default is 300.ms().

pub fn focus_disabled_widgets(&self) -> ArcVar<bool>

If DISABLED widgets can receive focus.

This is true by default, allowing disabled widgets to receive focus can provide a better experience for users, as the keyboard navigation stays the same, this is also of special interest for accessibility users, screen readers tend to only vocalize the focused content.

Widgets should use a different focused visual for disabled focus, it must be clear that the widget has the keyboard focus only as a navigation waypoint and cannot provide its normal function.

pub fn focus_hidden_widgets(&self) -> ArcVar<bool>

If Hidden widgets can receive focus.

This is true by default, with the expectation that hidden widgets are made visible once they receive focus, this is particularly important to enable auto-scrolling to view, as widgets inside scroll regions that are far away from the viewport are auto-hidden.

Note that widgets can be explicitly made not focusable, so you can disable focus and hide a widget without needing to disable this feature globally. Note also that this feature does not apply to collapsed widgets.

pub fn navigation_origin(&self) -> ArcVar<Option<WidgetId>>

Override the starting point of the next focus move.

Focus requests that move the focus relative to the current focus will move from this widget instead if it is found in the focused window. This widget does not need to be focusable.

The variable is cleared every time the focus is moved. Auto focus by click or touch also sets the navigation origin if the clicked widget is not focusable.

If not set the focused widget is the origin.

pub fn focused( &self, ) -> ReadOnlyVar<Option<InteractionPath>, ArcVar<Option<InteractionPath>>>

Current focused widget.

pub fn return_focused( &self, scope_id: WidgetId, ) -> ReadOnlyVar<Option<InteractionPath>, ArcVar<Option<InteractionPath>>>

Current return focus of a scope.

pub fn is_window_focused(&self, window_id: WindowId) -> impl Var<bool>

If the focused path is in the given window_id.

pub fn is_focus_within(&self, widget_id: WidgetId) -> impl Var<bool>

If the focused path contains the given widget_id.

pub fn is_focused(&self, widget_id: WidgetId) -> impl Var<bool>

If the focused path is to the given widget_id.

pub fn alt_return( &self, ) -> ReadOnlyVar<Option<InteractionPath>, ArcVar<Option<InteractionPath>>>

Current ALT return focus.

pub fn in_alt(&self) -> impl Var<bool>

If focus is in an ALT scope.

pub fn is_highlighting(&self) -> ReadOnlyVar<bool, ArcVar<bool>>

If the current focused widget is visually indicated.

pub fn focus(&self, request: FocusRequest)

Request a focus update.

All other focus request methods call this method.

pub fn highlight(&self)

Schedules enabling of is_highlighting for next update.

pub fn focus_widget(&self, widget_id: impl Into<WidgetId>, highlight: bool)

Focus the widget if it is focusable and change the highlight.

If the widget is not focusable the focus does not move, in this case the highlight changes for the current focused widget.

If the widget is in a window that does not have focus, but is open and not minimized and the app has keyboard focus in another window; the window is focused and the request is processed when the focus event is received. The FocusRequest type has other more advanced window focus configurations.

This makes a focus request using FocusRequest::direct.

pub fn focus_widget_or_exit( &self, widget_id: impl Into<WidgetId>, navigation_origin: bool, highlight: bool, )

Focus the widget if it is focusable, else focus the first focusable parent, also changes the highlight.

If the widget and no parent are focusable the focus does not move, in this case the highlight changes for the current focused widget.

If navigation_origin is true the target becomes the navigation_origin when the first focusable ancestor is focused because the target is not focusable.

This makes a focus request using FocusRequest::direct_or_exit.

pub fn focus_widget_or_enter( &self, widget_id: impl Into<WidgetId>, navigation_origin: bool, highlight: bool, )

Focus the widget if it is focusable, else focus the first focusable descendant, also changes the highlight.

If the widget and no child are focusable the focus does not move, in this case the highlight changes for the current focused widget.

If navigation_origin is true the target becomes the navigation_origin when the first focusable descendant is focused because the target is not focusable.

This makes a focus request FocusRequest::direct_or_enter.

pub fn focus_widget_or_related( &self, widget_id: impl Into<WidgetId>, navigation_origin: bool, highlight: bool, )

Focus the widget if it is focusable, else focus the first focusable descendant, else focus the first focusable ancestor.

If the widget no focusable widget is found the focus does not move, in this case the highlight changes for the current focused widget.

If navigation_origin is true the target becomes the navigation_origin when the first focusable relative is focused because the target is not focusable.

This makes a focus request using FocusRequest::direct_or_related.

pub fn focus_enter(&self)

Focus the first logical descendant that is focusable from the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::enter.

pub fn focus_exit(&self)

Focus the first logical ancestor that is focusable from the navigation origin or the current focus or the return focus from ALT scopes.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::exit.

pub fn focus_next(&self)

Focus the logical next widget from the navigation origin or the current focus.

Does nothing if no origin of focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::next.

pub fn focus_prev(&self)

Focus the logical previous widget from the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::prev.

pub fn focus_up(&self)

Focus the nearest upward widget from the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::up.

pub fn focus_right(&self)

Focus the nearest widget to the right of the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::right.

pub fn focus_down(&self)

Focus the nearest downward widget from the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::down.

pub fn focus_left(&self)

Focus the nearest widget to the left of the navigation origin or the current focus.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::left.

pub fn focus_alt(&self)

Focus the ALT scope from the navigation origin or the current focus or escapes the current ALT scope.

Does nothing if no origin or focus is set. Continues highlighting the new focus if the current is highlighted.

This is makes a focus request using FocusRequest::alt.