Focus class

A widget that manages a FocusNode to allow keyboard focus to be given to this widget and its descendants.

When the focus is gained or lost, onFocusChange is called.

For keyboard events, onKey and onKeyEvent are called if FocusNode.hasFocus is true for this widget's focusNode, unless a focused descendant's onKey or onKeyEvent callback returned KeyEventResult.handled when called.

This widget does not provide any visual indication that the focus has changed. Any desired visual changes should be made when onFocusChange is called.

To access the FocusNode of the nearest ancestor Focus widget and establish a relationship that will rebuild the widget when the focus changes, use the Focus.of and FocusScope.of static methods.

To access the focused state of the nearest Focus widget, use FocusNode.hasFocus from a build method, which also establishes a relationship between the calling widget and the Focus widget that will rebuild the calling widget when the focus changes.

Managing a FocusNode means managing its lifecycle, listening for changes in focus, and re-parenting it when needed to keep the focus hierarchy in sync with the widget hierarchy. This widget does all of those things for you. See FocusNode for more information about the details of what node management entails if you are not using a Focus widget and you need to do it yourself.

If the Focus default constructor is used, then this widget will manage any given focusNode by overwriting the appropriate values of the focusNode with the values of FocusNode.onKey, FocusNode.onKeyEvent, FocusNode.skipTraversal, FocusNode.canRequestFocus, and FocusNode.descendantsAreFocusable whenever the Focus widget is updated.

If the Focus.withExternalFocusNode is used instead, then the values returned by onKey, onKeyEvent, skipTraversal, canRequestFocus, and descendantsAreFocusable will be the values in the external focus node, and the external focus node's values will not be overwritten when the widget is updated.

To collect a sub-tree of nodes into an exclusive group that restricts focus traversal to the group, use a FocusScope. To collect a sub-tree of nodes into a group that has a specific order to its traversal but allows the traversal to escape the group, use a FocusTraversalGroup.

To move the focus, use methods on FocusNode by getting the FocusNode through the of method. For instance, to move the focus to the next node in the focus traversal order, call Focus.of(context).nextFocus(). To unfocus a widget, call Focus.of(context).unfocus().

See also:

• FocusNode, which represents a node in the focus hierarchy and FocusNode's API documentation includes a detailed explanation of its role in the overall focus system.
• FocusScope, a widget that manages a group of focusable widgets using a FocusScopeNode.
• FocusScopeNode, a node that collects focus nodes into a group for traversal.
• FocusManager, a singleton that manages the primary focus and distributes key events to focused nodes.
• FocusTraversalPolicy, an object used to determine how to move the focus to other nodes.
• FocusTraversalGroup, a widget that groups together and imposes a traversal policy on the Focus nodes below it in the widget hierarchy.