FocusScopeNode class

A subclass ofFocusNode that acts as a scope for its descendants,maintaining information about which descendant is currently or was lastfocused.

Please see theFocusScope andFocus widgets, which are utility widgetsthat manage their ownFocusScopeNodes andFocusNodes, respectively. Ifthey aren't appropriate,FocusScopeNodes can be managed directly.

FocusScopeNode organizesFocusNodes intoscopes. Scopes form sub-treesof nodes that can be traversed as a group. Within a scope, the most recentnodes to have focus are remembered, and if a node is focused and thenremoved, the original node receives focus again.

From aFocusScopeNode, callingsetFirstFocus, sets the given focus scopeas thefocusedChild of this node, adopting if it isn't already part of thefocus tree.

Lifecycle

There are several actors involved in the lifecycle of aFocusNode/FocusScopeNode. They are created and disposed by theirowner, attached, detached, and re-parented using aFocusAttachment bytheirhost (which must be owned by theState of aStatefulWidget), andthey are managed by theFocusManager. Different parts of theFocusNodeAPI are intended for these different actors.

FocusNodes (and henceFocusScopeNodes) are persistent objects that formpart of afocus tree that is a sparse representation of the widgets in thehierarchy that are interested in receiving keyboard events. They must bemanaged like other persistent state, which is typically done by aStatefulWidget that owns the node. A stateful widget that owns a focusscope node must calldispose from itsState.dispose method.

Once created, aFocusNode must be attached to the widget tree via aFocusAttachment object. This attachment is created by callingattach,usually from theState.initState method. If the hosting widget is updatedto have a different focus node, then the updated node needs to be attachedinState.didUpdateWidget, after callingFocusAttachment.detach on thepreviousFocusAttachment.

BecauseFocusNodes form a sparse representation of the widget tree, theymust be updated whenever the widget tree is rebuilt. This is done by callingFocusAttachment.reparent, usually from theState.build orState.didChangeDependencies methods of the widget that represents thefocused region, so that theBuildContext assigned to theFocusScopeNodecan be tracked (the context is used to obtain theRenderObject, from whichthe geometry of focused regions can be determined).

Creating aFocusNode each timeState.build is invoked will cause thefocus to be lost each time the widget is built, which is usually not desiredbehavior (callunfocus if losing focus is desired).

If, as is common, the hostingStatefulWidget is also the owner of thefocus node, then it will also calldispose from itsState.dispose (inwhich case theFocusAttachment.detach may be skipped, since dispose willautomatically detach). If another object owns the focus node, then it mustcalldispose when the node is done being used.

Key Event Propagation

TheFocusManager receives key events fromHardwareKeyboard and will passthem to the focused nodes. It starts with the node with the primary focus,and will call theonKeyEvent callback for that node. If the callbackreturnsKeyEventResult.ignored, indicating that it did not handle theevent, theFocusManager will move to the parent of that node and call itsonKeyEvent. If thatonKeyEvent returnsKeyEventResult.handled, then itwill stop propagating the event. If it reaches the rootFocusScopeNode,FocusManager.rootScope, the event is discarded.

Constructors

FocusScopeNode({String?debugLabel,FocusOnKeyEventCallback?onKeyEvent,@Deprecated('Use onKeyEvent instead. ' 'This feature was deprecated after v3.18.0-2.0.pre.')FocusOnKeyCallback?onKey,boolskipTraversal =false,boolcanRequestFocus =true,TraversalEdgeBehaviortraversalEdgeBehavior =TraversalEdgeBehavior.closedLoop,TraversalEdgeBehaviordirectionalTraversalEdgeBehavior =TraversalEdgeBehavior.stop}): Creates aFocusScopeNode.

Properties

ancestors→Iterable<FocusNode>: AnIterable over the ancestors of this node.
no setterinherited
canRequestFocus↔bool: If true, this focus node may request the primary focus.
getter/setter pairinherited
children→Iterable<FocusNode>: An iterator over the children of this node.
no setterinherited
context→BuildContext?: The context that was supplied toattach.
no setterinherited
debugLabel↔String?: A debug label that is used for diagnostic output.
getter/setter pairinherited
descendants→Iterable<FocusNode>: AnIterable over the hierarchy of children below this one, indepth-first order.
no setterinherited
descendantsAreFocusable↔bool: If false, will disable focus for all of this node's descendants.
getter/setter pairinherited-setteroverride-getter
descendantsAreTraversable↔bool: If false, tells the focus traversal policy to skip over for all of thisnode's descendants for purposes of the traversal algorithm.
getter/setter pairinherited
directionalTraversalEdgeBehavior↔TraversalEdgeBehavior: Controls the directional transfer of focus when the focus is on the first or last item.
getter/setter pair
enclosingScope→FocusScopeNode?: Returns the nearest enclosing scope node above this node, or null if thenode has not yet be added to the focus tree.
no setterinherited
focusedChild→FocusNode?: Returns the child of this node that should receive focus if this scopenode receives focus.
no setter
hasFocus→bool: Whether this node has input focus.
no setterinherited
hashCode→int: The hash code for this object.
no setterinherited
hasListeners→bool: Whether any listeners are currently registered.
no setterinherited
hasPrimaryFocus→bool: Returns true if this node currently has the application-wide input focus.
no setterinherited
highlightMode→FocusHighlightMode: Returns theFocusHighlightMode that is currently in effect for this node.
no setterinherited
isFirstFocus→bool: Returns true if this scope is the focused child of its parent scope.
no setter
nearestScope→FocusScopeNode: Returns the nearest enclosing scope node above this node, includingthis node, if it's a scope.
no setteroverride
offset→Offset: Returns the global offset to the upper left corner of the attachedwidget'sRenderObject, in logical units.
no setterinherited
onKey↔FocusOnKeyCallback?: Called if this focus node receives a key event while focused (i.e. whenhasFocus returns true).
getter/setter pairinherited
onKeyEvent↔FocusOnKeyEventCallback?: Called if this focus node receives a key event while focused (i.e. whenhasFocus returns true).
getter/setter pairinherited
parent→FocusNode?: Returns the parent node for this object.
no setterinherited
rect→Rect: Returns the global rectangle of the attached widget'sRenderObject, inlogical units.
no setterinherited
runtimeType→Type: A representation of the runtime type of the object.
no setterinherited
size→Size: Returns the size of the attached widget'sRenderObject, in logicalunits.
no setterinherited
skipTraversal↔bool: If true, tells the focus traversal policy to skip over this node forpurposes of the traversal algorithm.
getter/setter pairinherited
traversalChildren→Iterable<FocusNode>: An iterator over the children that are allowed to be traversed by theFocusTraversalPolicy.
no setteroverride
traversalDescendants→Iterable<FocusNode>: Returns all descendants which do not have theskipTraversal and do havethecanRequestFocus flag set.
no setteroverride
traversalEdgeBehavior↔TraversalEdgeBehavior: Controls the transfer of focus beyond the first and the last items of aFocusScopeNode.
getter/setter pair

Methods

addListener(VoidCallbacklistener)→ void: Register a closure to be called when the object changes.
inherited
attach(BuildContext?context, {FocusOnKeyEventCallback?onKeyEvent,FocusOnKeyCallback?onKey})→FocusAttachment: Called by thehostStatefulWidget to attach aFocusNode to thewidget tree.
inherited
autofocus(FocusNodenode)→ void: If this scope lacks a focus, request that the given node become the focus.
consumeKeyboardToken()→bool: Removes the keyboard token from this focus node if it has one.
inherited
debugDescribeChildren()→List<DiagnosticsNode>: Returns a list ofDiagnosticsNode objects describing this node'schildren.
inherited
debugFillProperties(DiagnosticPropertiesBuilderproperties)→ void: Add additional properties associated with the node.
override
dispose()→ void: Discards any resources used by the object. After this is called, theobject is not in a usable state and should be discarded (calls toaddListener will throw after the object is disposed).
inherited
focusInDirection(TraversalDirectiondirection)→bool: Request to move the focus to the nearest focus node in the givendirection, by calling theFocusTraversalPolicy.inDirection method.
inherited
nextFocus()→bool: Request to move the focus to the next focus node, by calling theFocusTraversalPolicy.next method.
inherited
noSuchMethod(Invocationinvocation)→ dynamic: Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners()→ void: Call all the registered listeners.
inherited
previousFocus()→bool: Request to move the focus to the previous focus node, by calling theFocusTraversalPolicy.previous method.
inherited
removeListener(VoidCallbacklistener)→ void: Remove a previously registered closure from the list of closures that arenotified when the object changes.
inherited
requestFocus([FocusNode?node])→ void: Requests the primary focus for this node, or for a suppliednode, whichwill also give focus to itsancestors.
inherited
requestScopeFocus()→ void: Requests that the scope itself receive focus, without trying to finda descendant that should receive focus.
setFirstFocus(FocusScopeNodescope)→ void: Make the givenscope the active child scope for this scope.
toDiagnosticsNode({String?name,DiagnosticsTreeStyle?style})→DiagnosticsNode: Returns a debug representation of the object that is used by debuggingtools and byDiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevelminLevel =DiagnosticLevel.info})→String: A string representation of this object.
inherited
toStringDeep({StringprefixLineOne ='',String?prefixOtherLines,DiagnosticLevelminLevel =DiagnosticLevel.debug,intwrapWidth =65})→String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({Stringjoiner =', ',DiagnosticLevelminLevel =DiagnosticLevel.debug})→String: Returns a one-line detailed description of the object.
inherited
toStringShort()→String: A brief description of this object, usually just theruntimeType and thehashCode.
inherited
unfocus({UnfocusDispositiondisposition =UnfocusDisposition.scope})→ void: Removes the focus on this node by moving the primary focus to another node.
inherited

Operators

operator ==(Objectother)→bool: The equality operator.
inherited

Flutter
widgets
FocusScopeNode class

Movatterモバイル変換