FocusModifier 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().

{@tool dartpad} This example shows how to manage focus using the Focus and FocusScope widgets. See FocusNode for a similar example that doesn't use Focus or FocusScope.

** See code in examples/api/lib/widgets/focus_scope/focus.0.dart ** {@end-tool}

{@tool dartpad} This example shows how to wrap another widget in a Focus widget to make it focusable. It wraps a Container, and changes the container's color when it is set as the FocusManager.primaryFocus.

If you also want to handle mouse hover and/or keyboard actions on a widget, consider using a FocusableActionDetector, which combines several different widgets to provide those capabilities.

** See code in examples/api/lib/widgets/focus_scope/focus.1.dart ** {@end-tool}

{@tool dartpad} This example shows how to focus a newly-created widget immediately after it is created.

The focus node will not actually be given the focus until after the frame in which it has requested focus is drawn, so it is OK to call FocusNode.requestFocus on a node which is not yet in the focus tree.

** See code in examples/api/lib/widgets/focus_scope/focus.2.dart ** {@end-tool}

Constructors

FocusModifier({Key? key, Widget? child, Key? modifierKey, FocusNode? focusNode, bool autofocus = false, ValueChanged<bool>? onFocusChange, bool includeSemantics = true, bool? canRequestFocus, String? debugLabel, bool? descendantsAreFocusable, bool? descendantsAreTraversable, FocusOnKeyCallback? onKey, FocusOnKeyEventCallback? onKeyEvent, bool? skipTraversal}): Creates a widget that manages a FocusNode.
const
FocusModifier.withExternalFocusNode({Key? key, required Widget child, required FocusNode focusNode, bool autofocus, ValueChanged<bool>? onFocusChange, bool includeSemantics}): Creates a Focus widget that uses the given focusNode as the source of truth for attributes on the node, rather than the attributes of this widget.
const

factory

Properties

autofocus → bool: True if this widget will be selected as the initial focus when no other node in its scope is currently focused.
final
canRequestFocus → bool?: If true, this widget may request the primary focus.
final
debugLabel → String?: A debug label for this widget.
final
descendantsAreFocusable → bool?: If false, will make this widget's descendants unfocusable.
final
descendantsAreTraversable → bool?: If false, will make this widget's descendants untraversable.
final
focusNode → FocusNode?: An optional focus node to use as the focus node for this widget.
final
hashCode → int: The hash code for this object.
no setterinherited
includeSemantics → bool: Include semantics information in this widget.
final
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
modifierKey → Key?: The actual key of the widget, which Modifier wrapped
finalinherited
onFocusChange → ValueChanged<bool>?: Handler called when the focus changes.
final
onKey → FocusOnKeyCallback?: A handler for keys that are pressed when this object or one of its children has focus.
final
onKeyEvent → FocusOnKeyEventCallback?: A handler for keys that are pressed when this object or one of its children has focus.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
skipTraversal → bool?: Sets the FocusNode.skipTraversal flag on the focus node so that it won't be visited by the FocusTraversalPolicy.
final

Methods

build(BuildContext context) → Widget: Describes the part of the user interface represented by this widget.
inherited
buildWithChild(BuildContext context, Widget? child) → Widget: A build method that receives an extra child parameter.
override
createElement() → SingleChildStatelessElement: Create a SingleChildStatelessElement
inherited
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
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}) → 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 short, textual description of this widget.
inherited

Operators

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

FocusModifier class

Constructors

Properties

Methods

Operators

widgets library