Module focus 

Focus service, properties, events and other types.

Keyboard Focus

In an app instance only a single widget can receive keyboard input at a time, this widget has the keyboard focus. The operating system defines what window has keyboard focus and the app-process defines what widget has focus, these two systems work in conjunction to define the keyboard focus.

You can track the focused widget by listening to the FOCUS_CHANGED_EVENT event or the FOCUS.focused variable. The focus state of a widget can be tracked using the is_focused, is_focus_within, on_focus_changed and other properties on this module.

use zng::{focus, prelude::*};


focus::FOCUS_CHANGED_EVENT
    .on_pre_event(hn!(|args| {
        println!("new_focus: {:?}", args.new_focus);
    }))
    .perm();

Stack!(
    top_to_bottom,
    5,
    ui_vec![
        Wgt! {
            id = "subject";
            focus::focusable = true;

            layout::size = (100, 30);
            widget::background_color = colors::RED;
            when *#focus::is_focused {
                widget::background_color = colors::GREEN;
            }

            focus::on_focus = hn!(|_| {
                println!("subject on_focus");
            });
            focus::on_blur = hn!(|_| {
                println!("subject on_blur");
            });
        },
        Button! {
            child = Text!("Focus subject");
            on_click = hn!(|_| {
                FOCUS.focus_widget("subject", /*highlight: */ false);
            });
        },
        Text! {
            txt = FOCUS.focused().map(|f| formatx!("focused {f:?}"));
        }
    ]
)

Navigation

The keyboard focus can be moved from one widget to the next using the keyboard or the FOCUS service methods. There are two styles of movement: tabbing that follows the logical order and directional that follows the visual order.

Keyboard navigation behaves different depending on what region of the screen the current focused widget is in, these regions are called focus scopes. Every window is a focus scope that can be subdivided further.

Tab Navigation

Tab navigation follows a logical order, the position of the widget in the widget tree, optionally overridden using tab_index.

Focus is moved forward by pressing TAB or calling FOCUS.focus_next and backward by pressing SHIFT+TAB or calling FOCUS.focus_prev.

Directional Navigation

Directional navigation follows the visual position of the widget on the screen.

Focus is moved by pressing the arrow keys or calling the focus direction methods in the FOCUS service.

Focus Scopes

Focus scopes are widgets that configure how focus navigation happens inside then. They control what happens when the scope widget is focused, how the navigation flows inside their screen region and even if the navigation can naturally mode out of their region.

You can use the focus_scope property on a widget to turn it into a focus scope and use the tab_nav, directional_nav and other properties on this module to configure the focus scope.

Alt Scopes

Alt scopes are specially marked focus scopes that receive focus when the ALT key is pressed or FOCUS.focus_alt is called. The alt scope of a widget is selected by WidgetFocusInfo::alt_scope.

Alt scopes remember the previously focused widget as a return focus. The focus returns ALT is pressed again, or FOCUS.focus_exit is called and the parent is the focus scope.

Return Focus

Focus scopes can be configured to remember the last focused widget inside then, the focus than returns to this widget when the scope receives focus. Alt scopes also remember the widget from which the alt focus happened and can also return focus back to that widget.

You can track the return focus by listening to the RETURN_FOCUS_CHANGED_EVENT event or FOCUS.return_focused variable. Usually the window root scope remembers return focus and some widgets, like text fields visually indicate that they will be focused when the window is focused.

You can use the focus_scope_behavior property to configure a custom focus scope to remember the return focus.

Configuring Widgets

Focusable configuration is set as info metadata using the FocusInfoBuilder. You can use this type to make a widget focusable or a focus scope and customize how the focus manager interacts with the widget.

Note that the main crate already provides properties for configuring focus in widgets, you only need to set the FocusInfoBuilder directly if you are developing your own focus defining properties.

Querying

Focus information exists as metadata associated with a window widget tree. This metadata can be manually queried by creating a FocusInfoTree or directly from a widget info by using the WidgetInfoFocusExt extension methods.

Full API

See zng_ext_input::focus and zng_wgt_input::focus for the full focus API.

Modules

cmd

Commands that control focus and Command extensions.

iter

Focusable info tree iterators.

Structs

FOCUS

Keyboard focus service.

FocusChangedArgs

FOCUS_CHANGED_EVENT arguments.

FocusInfoBuilder

Builder for FocusInfo accessible in a WidgetInfoBuilder.

FocusInfoTree

A WidgetInfoTree wrapper for querying focus info out of the widget tree.

FocusNavAction

Represents the FocusTarget actions that move focus from the current focused widget.

FocusRequest

Focus change request.

FocusableMix

m Focusable widget mixin. Enables keyboard focusing on the widget and adds a focused highlight visual.

ReturnFocusChangedArgs

RETURN_FOCUS_CHANGED_EVENT arguments.

TabIndex

Widget tab navigation position within a focus scope.

WidgetFocusInfo

WidgetInfo wrapper that adds focus information for each widget.

Enums

DirectionalNav

Directional navigation configuration of a focus scope.

FocusChangedCause

The cause of a FOCUS_CHANGED_EVENT.

FocusClickBehavior

Behavior of a widget when a click event is send to it or a descendant.

FocusInfo

Focus metadata associated with a widget info tree.

FocusScopeOnFocus

Behavior of a focus scope when it receives direct focus.

FocusTarget

Focus request target.

TabNav

Tab navigation configuration of a focus scope.

Statics

FOCUS_CHANGED_EVENT

Keyboard focused widget changed event.

RETURN_FOCUS_CHANGED_EVENT

Scope return focus widget changed event.

Traits

WidgetInfoFocusExt

WidgetInfo extensions that build a WidgetFocusInfo.

Functions

alt_focus_scope

P Widget is the ALT focus scope.

directional_nav

P Keyboard arrows navigation within this focus scope.

focus_click_behavior

P Behavior of a widget when a click event is send to it or a descendant.

focus_highlight

P Sets the foreground highlight values used when the widget is focused and highlighted.

focus_on_init

P If the widget is focused on info init.

focus_scope

P Makes the widget into a focus scope when set to true.

focus_scope_behavior

P Behavior of a focus scope when it receives direct focus.

focus_shortcut

P Keyboard shortcuts that focus this widget or its first focusable descendant or its first focusable parent.

focusable

P Makes the widget focusable when set to true.

is_focus_within

P If the widget or one of its descendants has keyboard focus.

is_focus_within_hgl

P If the widget or one of its descendants has keyboard focus and the user is using the keyboard to navigate.

is_focused

P If the widget has keyboard focus.

is_focused_hgl

P If the widget has keyboard focus and the user is using the keyboard to navigate.

is_return_focus

P If the widget will be focused when a parent scope is focused.

is_return_focus_within

P If the widget or one of its descendants will be focused when a focus scope is focused.

on_blur

P Widget lost direct keyboard focus.

on_focus

P Widget got direct keyboard focus.

on_focus_changed

P Focus changed in the widget or its descendants.

on_focus_enter

P Widget or one of its descendants got focus.

on_focus_leave

P Widget or one of its descendants lost focus.

on_pre_blur

P Preview on_blur event.

on_pre_focus

P Preview on_focus event.

on_pre_focus_changed

P Preview on_focus_changed event.

on_pre_focus_enter

P Preview on_focus_enter event.

on_pre_focus_leave

P Preview on_focus_leave event.

return_focus_on_deinit

P If the widget return focus to the previous focus when it inited.

skip_directional

P If directional navigation from outside this widget skips over it and its descendants.

tab_index

P Customizes the widget order during TAB navigation.

tab_nav

P Tab navigation within this focus scope.