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

{@tool dartpad} 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.

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

See also:

• FocusScopeNode, which represents a scope node in the focus hierarchy.
• FocusNode, which represents a node in the focus hierarchy and has an explanation of the focus system.
• Focus, a widget that manages a FocusNode and allows easy access to managing focus without having to manage the node.
• FocusManager, a singleton that manages the 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 used to configure the focus traversal policy for a widget subtree.

Inheritance

• Object
• DiagnosticableTree
• Widget
• StatelessWidget
• SingleChildStatelessModifier
• FocusModifier
• FocusScopeModifier

Available extensions

• ModifierTransformer

Constructors

FocusScopeModifier({Key? key, FocusScopeNode? node, required Widget child, bool autofocus = false, ValueChanged<bool>? onFocusChange, bool? canRequestFocus, bool? skipTraversal, FocusOnKeyEventCallback? onKeyEvent, FocusOnKeyCallback? onKey, String? debugLabel})

Creates a widget that manages a FocusScopeNode.

const

FocusScopeModifier.withExternalFocusNode({Key? key, required Widget child, required FocusScopeNode focusScopeNode, bool autofocus, 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.

final, inherited

canRequestFocus → bool?

If true, this widget may request the primary focus.

final, inherited

debugLabel → String?

A debug label for this widget.

final, inherited

descendantsAreFocusable → bool?

If false, will make this widget's descendants unfocusable.

final, inherited

descendantsAreTraversable → bool?

If false, will make this widget's descendants untraversable.

final, inherited

focusNode → FocusNode?

An optional focus node to use as the focus node for this widget.

final, inherited

hashCode → int

The hash code for this object.

no setter, inherited

includeSemantics → bool

Include semantics information in this widget.

final, inherited

key → Key?

Controls how one widget replaces another widget in the tree.

final, inherited

modifierKey → Key?

The actual key of the widget, which Modifier wrapped

final, inherited

onFocusChange → ValueChanged<bool>?

Handler called when the focus changes.

final, inherited

onKey → FocusOnKeyCallback?

A handler for keys that are pressed when this object or one of its children has focus.

final, inherited

onKeyEvent → FocusOnKeyEventCallback?

A handler for keys that are pressed when this object or one of its children has focus.

final, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

skipTraversal → bool?

Sets the FocusNode.skipTraversal flag on the focus node so that it won't be visited by the FocusTraversalPolicy.

final, inherited

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.

inherited

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

modified() → Modifier

Available on Widget, provided by the ModifierTransformer extension

Transform normal widget to Modifier

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, 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 short, textual description of this widget.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited