FocusScope class

A FocusScope is similar to a Focus, but also serves as a scope for its descendants, restricting focus traversal to the scoped controls.

For example a new FocusScope is created automatically when a route is pushed, keeping the focus traversal from moving to a control in a previous route.

If you just want to group widgets together in a group so that they are traversed in a particular order, but the focus can still leave the group, use a FocusTraversalGroup.

Like Focus, FocusScope provides an onFocusChange as a way to be notified when the focus is given to or removed from this widget.

The onKey argument allows specification of a key event handler that is invoked when this node or one of its children has focus. Keys are handed to the primary focused widget first, and then they propagate through the ancestors of that node, stopping if one of them returns KeyEventResult.handled from onKey, indicating that it has handled the event.

Managing a FocusScopeNode 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 FocusScopeNode for more information about the details of what node management entails if you are not using a FocusScope widget and you need to do it yourself.

FocusScopeNodes remember the last FocusNode that was focused within their descendants, and can move that focus to the next/previous node, or a node in a particular direction when the FocusNode.nextFocus, FocusNode.previousFocus, or FocusNode.focusInDirection are called on a FocusNode or FocusScopeNode.

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

This example demonstrates using a FocusScope to restrict focus to a particular portion of the app. In this case, restricting focus to the visible part of a Stack.

To create a local project with this code sample, run:
flutter create --sample=widgets.FocusScope.1 mysample

Constructors

FocusScope({Key? key, FocusScopeNode? node, FocusNode? parentNode, required Widget child, bool autofocus = false, ValueChanged<bool>? onFocusChange, bool? canRequestFocus, bool? skipTraversal, FocusOnKeyEventCallback? onKeyEvent, FocusOnKeyCallback? onKey, String? debugLabel, bool includeSemantics = true, bool? descendantsAreFocusable, bool? descendantsAreTraversable}): Creates a widget that manages a FocusScopeNode.
const
FocusScope.withExternalFocusNode({Key? key, required Widget child, required FocusScopeNode focusScopeNode, FocusNode? parentNode, bool autofocus, bool includeSemantics, ValueChanged<bool>? onFocusChange}): Creates a FocusScope widget that uses the given focusScopeNode 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.
finalinherited
canRequestFocus → bool: If true, this widget may request the primary focus.
no setterinherited
child → Widget: The child widget of this Focus.
finalinherited
debugLabel → String?: A debug label for this widget.
no setterinherited
descendantsAreFocusable → bool: If false, will make this widget's descendants unfocusable.
no setterinherited
descendantsAreTraversable → bool: If false, will make this widget's descendants untraversable.
no setterinherited
focusNode → FocusNode?: An optional focus node to use as the focus node for this widget.
finalinherited
hashCode → int: The hash code for this object.
no setterinherited
includeSemantics → bool: Include semantics information in this widget.
finalinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
onFocusChange → ValueChanged<bool>?: Handler called when the focus changes.
finalinherited
onKey → FocusOnKeyCallback?: A handler for keys that are pressed when this object or one of its children has focus.
no setterinherited
onKeyEvent → FocusOnKeyEventCallback?: A handler for keys that are pressed when this object or one of its children has focus.
no setterinherited
parentNode → FocusNode?: The optional parent node to use when reparenting the focusNode for this Focus widget.
finalinherited
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.
no setterinherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<Focus>: Creates the mutable state for this widget at a given location in the tree.
override
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

Static Methods

of(BuildContext context, {bool createDependency = true}) → FocusScopeNode: Returns the FocusNode.nearestScope of the Focus or FocusScope that most tightly encloses the given context.
override