FocusManager class

Manages the focus tree.

The focus tree is a separate, sparser, tree from the widget tree that maintains the hierarchical relationship between focusable widgets in the widget tree.

The focus manager is responsible for tracking which FocusNode has the primary input focus (the primaryFocus), holding the FocusScopeNode that is the root of the focus tree (the rootScope), and what the current highlightMode is. It also distributes KeyEvents to the nodes in the focus tree.

The singleton FocusManager instance is held by the WidgetsBinding as WidgetsBinding.focusManager, and can be conveniently accessed using the FocusManager.instance static accessor.

To find the FocusNode for a given BuildContext, use Focus.of. To find the FocusScopeNode for a given BuildContext, use FocusScope.of.

If you would like notification whenever the primaryFocus changes, register a listener with addListener. When you no longer want to receive these events, as when your object is about to be disposed, you must unregister with removeListener to avoid memory leaks. Removing listeners is typically done in State.dispose on stateful widgets.

The highlightMode describes how focus highlights should be displayed on components in the UI. The highlightMode changes are notified separately via addHighlightModeListener and removed with removeHighlightModeListener. The highlight mode changes when the user switches from a mouse to a touch interface, or vice versa.

The widgets that are used to manage focus in the widget tree are:

  • Focus, a widget that manages a FocusNode in the focus tree so that the focus tree reflects changes in the widget hierarchy.
  • FocusScope, a widget that manages a FocusScopeNode in the focus tree, creating a new scope for restricting focus to a set of focus nodes.
  • FocusTraversalGroup, a widget that groups together nodes that should be traversed using an order described by a given FocusTraversalPolicy.

See also:

  • FocusNode, which is a node in the focus tree that can receive focus.
  • FocusScopeNode, which is a node in the focus tree used to collect subtrees into groups and restrict focus to them.
  • The primaryFocus global accessor, for convenient access from anywhere to the current focus manager state.
Mixed-in types

Constructors

FocusManager()
Creates an object that manages the focus tree.

Properties

hashCode int
The hash code for this object.
no setterinherited
hasListeners bool
Whether any listeners are currently registered.
no setterinherited
highlightMode FocusHighlightMode
Indicates the current interaction mode for focus highlights.
no setter
highlightStrategy FocusHighlightStrategy
Sets the strategy by which highlightMode is determined.
getter/setter pair
primaryFocus FocusNode?
The node that currently has the primary focus.
no setter
rootScope FocusScopeNode
The root FocusScopeNode in the focus tree.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited

Methods

addEarlyKeyEventHandler(OnKeyEventCallback handler) → void
Adds a key event handler to a set of handlers that are called before any key event handlers in the focus tree are called.
addHighlightModeListener(ValueChanged<FocusHighlightMode> listener) → void
Register a closure to be called when the FocusManager notifies its listeners that the value of highlightMode has changed.
addLateKeyEventHandler(OnKeyEventCallback handler) → void
Adds a key event handler to a set of handlers that are called if none of the key event handlers in the focus tree handle the event.
addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
applyFocusChangesIfNeeded() → void
Applies any pending focus changes and notifies listeners that the focus has changed.
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
override
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
dispose() → void
Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
override
listenToApplicationLifecycleChangesIfSupported() → void
Enables this FocusManager to listen to changes of the application lifecycle if it does not already have an application lifecycle listener active, and the app isn't running on a native mobile platform.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
registerGlobalHandlers() → void
Registers global input event handlers that are needed to manage focus.
removeEarlyKeyEventHandler(OnKeyEventCallback handler) → void
Removes a key handler added by calling addEarlyKeyEventHandler.
removeHighlightModeListener(ValueChanged<FocusHighlightMode> listener) → void
Remove a previously registered closure from the list of closures that the FocusManager notifies.
removeLateKeyEventHandler(OnKeyEventCallback handler) → void
Removes a key handler added by calling addLateKeyEventHandler.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Properties

instance FocusManager
Provides convenient access to the current FocusManager singleton from the WidgetsBinding instance.
no setter