Skip to content

Commit 2a2a79d

Browse files
authored
Clear cached directional focus history on a non-directional focus request (flutter#187957)
Fixes flutter#85941 When a user traverses focus nodes directionally (e.g. using `up`, `down` arrow keys), we maintain a history stack of visited nodes (called `policyData`). This allows us to avoid [hysteresis](https://en.wikipedia.org/wiki/Hysteresis) when a user switches direction (i.e. switching from `down` to `up`) - meaning, the forward traversal path and the reversed traversal path should match. However, before this change, we were not detecting when a focus request occurred due to some outside event (e.g. a direct focus request from a tap on the screen). That means when a user switched direction, we would include the node they had tapped on in the history stack, and unexpectedly visit it. We now clear the stack (see method `propagateFocusRequest`) if a node is focused on outside of a directional navigation event. **Before:** <img width="454" height="656" alt="before" src="https://github.com/user-attachments/assets/26e3cdd2-2f39-4dc8-9616-4f21d4afcc52" /> **With fix:** <img width="454" height="656" alt="fixed" src="https://github.com/user-attachments/assets/0e795e0c-8e07-4422-beed-f371407b4ae6" /> ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 5f8d728 commit 2a2a79d

2 files changed

Lines changed: 204 additions & 26 deletions

File tree

‎packages/flutter/lib/src/widgets/focus_traversal.dart‎

Lines changed: 97 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1123,6 +1123,7 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
11231123
TraversalDirection direction,
11241124
FocusScopeNode nearestScope,
11251125
FocusNode focusedChild,
1126+
_FocusTraversalGroupNode? groupNode,
11261127
) {
11271128
final _DirectionalPolicyData? policyData = _policyData[nearestScope];
11281129
if (policyData != null &&
@@ -1154,7 +1155,7 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
11541155
case TraversalDirection.down:
11551156
alignmentPolicy = ScrollPositionAlignmentPolicy.keepVisibleAtEnd;
11561157
}
1157-
requestFocusCallback(lastNode, alignmentPolicy: alignmentPolicy);
1158+
_requestFocus(lastNode, alignmentPolicy: alignmentPolicy, groupNode);
11581159
return true;
11591160
}
11601161

@@ -1214,23 +1215,32 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
12141215
FocusNode node,
12151216
FocusScopeNode nearestScope,
12161217
TraversalDirection direction,
1218+
_FocusTraversalGroupNode? groupNode,
12171219
) {
12181220
if (node is FocusScopeNode) {
12191221
if (node.focusedChild != null) {
1220-
return _requestTraversalFocusInDirection(currentNode, node.focusedChild!, node, direction);
1222+
return _requestTraversalFocusInDirection(
1223+
currentNode,
1224+
node.focusedChild!,
1225+
node,
1226+
direction,
1227+
groupNode,
1228+
);
12211229
}
12221230
final FocusNode firstNode = findFirstFocusInDirection(node, direction) ?? currentNode;
12231231
switch (direction) {
12241232
case TraversalDirection.up:
12251233
case TraversalDirection.left:
1226-
requestFocusCallback(
1234+
_requestFocus(
12271235
firstNode,
1236+
groupNode,
12281237
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtStart,
12291238
);
12301239
case TraversalDirection.right:
12311240
case TraversalDirection.down:
1232-
requestFocusCallback(
1241+
_requestFocus(
12331242
firstNode,
1243+
groupNode,
12341244
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtEnd,
12351245
);
12361246
}
@@ -1240,20 +1250,44 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
12401250
switch (direction) {
12411251
case TraversalDirection.up:
12421252
case TraversalDirection.left:
1243-
requestFocusCallback(
1253+
_requestFocus(
12441254
node,
1255+
groupNode,
12451256
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtStart,
12461257
);
12471258
case TraversalDirection.right:
12481259
case TraversalDirection.down:
1249-
requestFocusCallback(node, alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtEnd);
1260+
_requestFocus(
1261+
node,
1262+
groupNode,
1263+
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtEnd,
1264+
);
12501265
}
12511266
return !nodeHadPrimaryFocus;
12521267
}
12531268

1269+
void _requestFocus(
1270+
FocusNode node,
1271+
_FocusTraversalGroupNode? groupNode, {
1272+
ScrollPositionAlignmentPolicy? alignmentPolicy,
1273+
double? alignment,
1274+
Duration? duration,
1275+
Curve? curve,
1276+
}) {
1277+
groupNode?.lastRequestedFocus = node;
1278+
requestFocusCallback(
1279+
node,
1280+
alignmentPolicy: alignmentPolicy,
1281+
alignment: alignment,
1282+
duration: duration,
1283+
curve: curve,
1284+
);
1285+
}
1286+
12541287
bool _onEdgeForDirection(
12551288
FocusNode currentNode,
12561289
FocusNode focusedChild,
1290+
_FocusTraversalGroupNode? groupNode,
12571291
TraversalDirection direction, {
12581292
FocusScopeNode? scope,
12591293
}) {
@@ -1275,7 +1309,13 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
12751309
direction,
12761310
);
12771311
if (found == null) {
1278-
return _onEdgeForDirection(currentNode, focusedChild, direction, scope: nearestScope);
1312+
return _onEdgeForDirection(
1313+
currentNode,
1314+
focusedChild,
1315+
groupNode,
1316+
direction,
1317+
scope: nearestScope,
1318+
);
12791319
}
12801320
} else {
12811321
found = _findNextFocusInDirection(
@@ -1296,7 +1336,13 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
12961336
return false;
12971337
}
12981338
if (found != null) {
1299-
return _requestTraversalFocusInDirection(currentNode, found, nearestScope, direction);
1339+
return _requestTraversalFocusInDirection(
1340+
currentNode,
1341+
found,
1342+
nearestScope,
1343+
direction,
1344+
groupNode,
1345+
);
13001346
}
13011347
return false;
13021348
}
@@ -1321,27 +1367,31 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
13211367
@mustCallSuper
13221368
@override
13231369
bool inDirection(FocusNode currentNode, TraversalDirection direction) {
1370+
final _FocusTraversalGroupNode? groupNode = FocusTraversalGroup._getGroupNode(currentNode);
13241371
final FocusScopeNode nearestScope = currentNode.nearestScope!;
13251372
final FocusNode? focusedChild = nearestScope.focusedChild;
13261373
if (focusedChild == null) {
1327-
final FocusNode firstFocus = findFirstFocusInDirection(currentNode, direction) ?? currentNode;
1374+
final FocusNode firstFocus =
1375+
findFirstFocusInDirection(currentNode, direction) ?? currentNode;
13281376
switch (direction) {
13291377
case TraversalDirection.up:
13301378
case TraversalDirection.left:
1331-
requestFocusCallback(
1379+
_requestFocus(
13321380
firstFocus,
13331381
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtStart,
1382+
groupNode,
13341383
);
13351384
case TraversalDirection.right:
13361385
case TraversalDirection.down:
1337-
requestFocusCallback(
1386+
_requestFocus(
13381387
firstFocus,
13391388
alignmentPolicy: ScrollPositionAlignmentPolicy.keepVisibleAtEnd,
1389+
groupNode,
13401390
);
13411391
}
13421392
return true;
13431393
}
1344-
if (_popPolicyDataIfNeeded(direction, nearestScope, focusedChild)) {
1394+
if (_popPolicyDataIfNeeded(direction, nearestScope, focusedChild, groupNode)) {
13451395
return true;
13461396
}
13471397
final FocusNode? found = _findNextFocusInDirection(
@@ -1351,9 +1401,15 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
13511401
);
13521402
if (found != null) {
13531403
_pushPolicyData(direction, nearestScope, focusedChild);
1354-
return _requestTraversalFocusInDirection(currentNode, found, nearestScope, direction);
1404+
return _requestTraversalFocusInDirection(
1405+
currentNode,
1406+
found,
1407+
nearestScope,
1408+
direction,
1409+
groupNode,
1410+
);
13551411
}
1356-
return _onEdgeForDirection(currentNode, focusedChild, direction);
1412+
return _onEdgeForDirection(currentNode, focusedChild, groupNode, direction);
13571413
}
13581414
}
13591415

@@ -2206,8 +2262,11 @@ class FocusTraversalGroup extends StatefulWidget {
22062262
}
22072263

22082264
// A special focus node subclass that only FocusTraversalGroup uses so that it
2209-
// can be used to cache the policy in the focus tree, and so that the traversal
2210-
// code can find groups in the focus tree.
2265+
// can be used to cache the following in the focus tree:
2266+
// - the focus traversal policy - this allows traversal code to find groups in
2267+
// the focus tree.
2268+
// - the last focused node - this allows the policy to be invalidated when a
2269+
// focus change was not triggered via a traversal request.
22112270
class _FocusTraversalGroupNode extends FocusNode {
22122271
_FocusTraversalGroupNode({super.debugLabel, required this.policy}) {
22132272
if (kFlutterMemoryAllocationsEnabled) {
@@ -2216,6 +2275,8 @@ class _FocusTraversalGroupNode extends FocusNode {
22162275
}
22172276

22182277
FocusTraversalPolicy policy;
2278+
2279+
FocusNode? lastRequestedFocus;
22192280
}
22202281

22212282
class _FocusTraversalGroupState extends State<FocusTraversalGroup> {
@@ -2232,11 +2293,13 @@ class _FocusTraversalGroupState extends State<FocusTraversalGroup> {
22322293
@override
22332294
void initState() {
22342295
super.initState();
2296+
FocusManager.instance.addListener(_handleFocusChanged);
22352297
widget.onFocusNodeCreated?.call(focusNode);
22362298
}
22372299

22382300
@override
22392301
void dispose() {
2302+
FocusManager.instance.removeListener(_handleFocusChanged);
22402303
focusNode.dispose();
22412304
super.dispose();
22422305
}
@@ -2262,6 +2325,24 @@ class _FocusTraversalGroupState extends State<FocusTraversalGroup> {
22622325
child: widget.child,
22632326
);
22642327
}
2328+
2329+
void _handleFocusChanged() {
2330+
final FocusNode? primaryFocus = FocusManager.instance.primaryFocus;
2331+
final FocusNode? lastRequestedFocus = focusNode.lastRequestedFocus;
2332+
2333+
if (lastRequestedFocus == null) {
2334+
return;
2335+
}
2336+
2337+
if (primaryFocus != lastRequestedFocus) {
2338+
FocusScopeNode? scope = primaryFocus?.nearestScope;
2339+
while (scope != null) {
2340+
widget.policy.invalidateScopeData(scope);
2341+
scope = scope.enclosingScope;
2342+
}
2343+
focusNode.lastRequestedFocus = null;
2344+
}
2345+
}
22652346
}
22662347

22672348
/// An intent for use with the [RequestFocusAction], which supplies the

0 commit comments

Comments
 (0)