focus constant

Move the input focus to the respective widget.

Most commonly, the input focus determines which widget will receive keyboard input. Semantics nodes that can receive this action are expected to have SemanticsFlag.isFocusable set. Examples of such focusable widgets include buttons, checkboxes, switches, and text fields.

Upon receiving this action, the corresponding widget must move input focus to itself. Doing otherwise is likely to lead to a poor user experience, such as user input routed to a wrong widget. Text fields in particular, must immediately become editable, opening a virtual keyboard, if needed. Buttons must respond to tap/click events from the keyboard.

Widget reaction to this action must be idempotent. It is possible to receive this action more than once, or when the widget is already focused.

Focus behavior is specific to the platform and to the assistive technology used. Typically on desktop operating systems, such as Windows, macOS, and Linux, moving accessibility focus will also move the input focus. On mobile it is more common for the accessibility focus to be detached from the input focus. In order to synchronize the two, a user takes an explicit action (e.g. double-tap to activate). Sometimes this behavior is configurable. For example, VoiceOver on macOS can be configured in the global OS user settings to either move the input focus together with the VoiceOver focus, or to keep the two detached. For this reason, widgets should not expect to receive didGainAccessibilityFocus and focus actions to be reported in any particular combination or order.

On the web, the DOM "focus" event is equivalent to SemanticsAction.focus. Accessibility focus is not observable from within the browser. Instead, the browser, based on the platform features and user preferences, makes the determination on whether input focus should be moved to an element and, if so, fires a DOM "focus" event. This event is forwarded to the framework as SemanticsAction.focus. For this reason, on the web, the engine never sends didGainAccessibilityFocus.

On Android input focus is observable as AccessibilityAction#ACTION_FOCUS and is separate from accessibility focus, which is observed as AccessibilityAction#ACTION_ACCESSIBILITY_FOCUS.

See also:

• didGainAccessibilityFocus, which informs the framework about accessibility focus ring, such as the TalkBack (Android) and VoiceOver (iOS), moving which does not move the input focus.