Skip to content

Add debugPaintFocusBoxes#188288

Merged
auto-submit[bot] merged 5 commits into
flutter:masterfrom
loic-sharma:debug_focus
Jul 6, 2026
Merged

Add debugPaintFocusBoxes#188288
auto-submit[bot] merged 5 commits into
flutter:masterfrom
loic-sharma:debug_focus

Conversation

@loic-sharma

@loic-sharma loic-sharma commented Jun 21, 2026

Copy link
Copy Markdown
Member

Adds a new debug global, debugPaintFocusBoxes, to visualize the focus tree:

  • Green box: the primary focus node
  • Blue boxes: focus nodes that are ancestors of the primary focus node
  • Cyan boxes: focus nodes that are focusable and traversable
  • Yellow boxes: focus nodes that are focusable but not traversable
  • Red boxes: focus nodes that are not focusable

Demo

void main() {
  debugPaintFocusBoxes = true;
  runApp(const CalendarDatePickerApp());
}
Screen.Recording.2026-06-21.at.2.24.06.PM.mov

Pre-launch Checklist

  • I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
  • I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools.
  • I read the [Tree Hygiene] wiki page, which explains my responsibilities.
  • I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement].
  • I signed the [CLA].
  • I listed at least one issue that this PR fixes in the description above.
  • I updated/added relevant documentation (doc comments with ///).
  • I added new tests to check the change I am making, or this PR is [test-exempt].
  • I followed the [breaking change policy] and added [Data Driven Fixes] where supported.
  • All existing and new tests are passing.

@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Jun 21, 2026
@github-actions github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. f: focus Focus traversal, gaining or losing focus labels Jun 21, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Jun 21, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new debugging flag, debugPaintFocusBoxes, which draws colored borders around Focus widgets to visually indicate their focus state, and adds corresponding unit tests. The review feedback suggests adding missing imports for painting and rendering classes, using triple-slash documentation comments for private members to align with the style guide, and optimizing ListenableBuilder usage by leveraging its child parameter. Additionally, the reviewer recommends using addTearDown in tests to safely reset the debugging flag and avoid test pollution, which also allows for the removal of manual resets.

Comment thread packages/flutter/lib/src/widgets/focus_scope.dart
Comment thread packages/flutter/lib/src/widgets/focus_scope.dart Outdated
Comment thread packages/flutter/lib/src/widgets/focus_scope.dart
Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated

testWidgets('adds a border on each Focus widget if enabled',
(WidgetTester tester) async {
debugPaintFocusBoxes = true;

@gemini-code-assist gemini-code-assist Bot Jun 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To prevent test pollution, use addTearDown to reset debugPaintFocusBoxes to false. This ensures the flag is reset even if the test fails or throws an exception.

Suggested change
debugPaintFocusBoxes = true;
debugPaintFocusBoxes = true;
addTearDown(() => debugPaintFocusBoxes = false);

@loic-sharma loic-sharma Jun 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, using a teardown to cleanup debug globals results in an exception:

The value of a widget debug variable was changed by the test.

When the exception was thrown, this was the stack:
#0      debugAssertAllWidgetVarsUnset.<anonymous closure> (package:flutter/src/widgets/debug.dart:569:7)
#1      debugAssertAllWidgetVarsUnset (package:flutter/src/widgets/debug.dart:572:4)
#2      TestWidgetsFlutterBinding._verifyInvariants (package:flutter_test/src/binding.dart:2019:7)
#3      AutomatedTestWidgetsFlutterBinding._verifyInvariants (package:flutter_test/src/binding.dart:2525:11)
#4      TestWidgetsFlutterBinding._runTestBody (package:flutter_test/src/binding.dart:1974:7)

The pattern these tests use mirrors other debug global tests. Also, AutomatedTestWidgetsFlutterBinding._verifyInvariants strictly enforces that no tests pollute debug globals.

Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated
Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated
Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated
Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated
Comment thread packages/flutter/test/widgets/focus_scope_test.dart Outdated
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 21, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 21, 2026
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 22, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 22, 2026
@Piinks
Piinks requested a review from elliette June 23, 2026 22:11
elliette
elliette reviewed Jun 23, 2026
View reviewed changes
Comment thread packages/flutter/lib/src/widgets/debug.dart
Comment thread packages/flutter/lib/src/widgets/focus_scope.dart
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 24, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 24, 2026
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 24, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 24, 2026
elliette
elliette previously approved these changes Jun 24, 2026
View reviewed changes

@elliette elliette left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One optional change, but otherwise LGTM!

elliette
elliette reviewed Jun 24, 2026
View reviewed changes
Comment thread packages/flutter/lib/src/widgets/focus_scope.dart
final Widget child;

Color get _borderColor {
if (node.hasPrimaryFocus) {

@elliette elliette Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider changing the colors here (and maybe modifying the border - perhaps making it thicker / semi transparent)? These colors match the ones used in the overlay guidelines (see debugPaint, etc) making it hard to distinguish between the two when both are enabled.

Focus boxes only:
Image

Overlay guidelines only:
Image

Overlay guidelines and focus boxes:
Image

@loic-sharma loic-sharma Jun 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I played with using different colors, but I wasn't able to find a set that I liked as much that was also easily distinguishable from the overlay guidelines. I did bump up the thickness and the add some transparency though!

@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 25, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 25, 2026
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 25, 2026
@loic-sharma loic-sharma added the CICD Run CI/CD label Jun 25, 2026
@github-actions github-actions Bot removed the CICD Run CI/CD label Jun 25, 2026
@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Jun 25, 2026
@justinmc
justinmc requested a review from elliette June 30, 2026 22:25
@loic-sharma loic-sharma added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 3, 2026
@auto-submit auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 3, 2026
@auto-submit

auto-submit Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

autosubmit label was removed for flutter/flutter/188288, because The base commit of the PR is older than 7 days and can not be merged. Please merge the latest changes from the main into this branch and resubmit the PR.

@loic-sharma loic-sharma added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 6, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Jul 6, 2026
Merged via the queue into flutter:master with commit 89412d5 Jul 6, 2026
20 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 6, 2026
This was referenced Jul 6, 2026
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Jul 8, 2026
@engine-flutter-autoroll
Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) (#…
52d84d6 
…12137)

Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions)

Manual roll requested by [email protected]

flutter/flutter@6995038...91939cc

2026-07-07 [email protected] Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067)
2026-07-07 [email protected] Bump customer testing version for new registrants (flutter/flutter#189070)
2026-07-07 [email protected] Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069)
2026-07-07 [email protected] fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043)
2026-07-07 [email protected] Bump goldctl (flutter/flutter#189030)
2026-07-07 [email protected] Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060)
2026-07-07 [email protected] Collect analytics on AI agent usage (flutter/flutter#187630)
2026-07-07 [email protected] Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054)
2026-07-07 [email protected] Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052)
2026-07-07 [email protected] Fix RenderSliverPadding setter assertion (flutter/flutter#187353)
2026-07-07 [email protected] Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037)
2026-07-07 [email protected] Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294)
2026-07-07 [email protected] Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035)
2026-07-07 [email protected] Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163)
2026-07-07 [email protected] Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835)
2026-07-07 [email protected] Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031)
2026-07-07 [email protected] Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032)
2026-07-06 [email protected] Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894)
2026-07-06 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#189025)
2026-07-06 [email protected] Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017)
2026-07-06 [email protected] Skip locked issues in no-response check (flutter/flutter#188950)
2026-07-06 [email protected] Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830)
2026-07-06 [email protected] ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020)
2026-07-06 [email protected] Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021)
2026-07-06 [email protected] [AGP 9] Update Flutter Template Versions (flutter/flutter#188762)
2026-07-06 [email protected] fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476)
2026-07-06 [email protected] [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454)
2026-07-06 [email protected] [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452)
2026-07-06 [email protected] [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921)
2026-07-06 [email protected] Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015)
2026-07-06 [email protected] [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745)
2026-07-06 [email protected] [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922)
2026-07-06 [email protected] Roll pub packages (flutter/flutter#189009)
2026-07-06 [email protected] Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006)
2026-07-06 [email protected] Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007)
2026-07-06 [email protected] Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004)
2026-07-06 [email protected] Fixing multiline GetBoxesForRange (flutter/flutter#188803)
2026-07-06 [email protected] Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000)
2026-07-06 [email protected] Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992)
2026-07-06 [email protected] Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991)
2026-07-06 [email protected] Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990)
2026-07-06 [email protected] Add debugPaintFocusBoxes (flutter/flutter#188288)
2026-07-05 [email protected] Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989)
2026-07-05 [email protected] Roll Skia from 75a4bf6706bd to 7f99eee20fd6 (2 revisions) (flutter/flutter#188988)
...
kalyujniy pushed a commit to brickit-app/camera that referenced this pull request Jul 8, 2026
@engine-flutter-autoroll @kalyujniy
Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) (f…
0897332 
…lutter#12137)

Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions)

Manual roll requested by [email protected]

flutter/flutter@6995038...91939cc

2026-07-07 [email protected] Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067)
2026-07-07 [email protected] Bump customer testing version for new registrants (flutter/flutter#189070)
2026-07-07 [email protected] Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069)
2026-07-07 [email protected] fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043)
2026-07-07 [email protected] Bump goldctl (flutter/flutter#189030)
2026-07-07 [email protected] Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060)
2026-07-07 [email protected] Collect analytics on AI agent usage (flutter/flutter#187630)
2026-07-07 [email protected] Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054)
2026-07-07 [email protected] Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052)
2026-07-07 [email protected] Fix RenderSliverPadding setter assertion (flutter/flutter#187353)
2026-07-07 [email protected] Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037)
2026-07-07 [email protected] Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294)
2026-07-07 [email protected] Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035)
2026-07-07 [email protected] Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163)
2026-07-07 [email protected] Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835)
2026-07-07 [email protected] Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031)
2026-07-07 [email protected] Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032)
2026-07-06 [email protected] Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894)
2026-07-06 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#189025)
2026-07-06 [email protected] Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017)
2026-07-06 [email protected] Skip locked issues in no-response check (flutter/flutter#188950)
2026-07-06 [email protected] Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830)
2026-07-06 [email protected] ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020)
2026-07-06 [email protected] Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021)
2026-07-06 [email protected] [AGP 9] Update Flutter Template Versions (flutter/flutter#188762)
2026-07-06 [email protected] fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476)
2026-07-06 [email protected] [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454)
2026-07-06 [email protected] [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452)
2026-07-06 [email protected] [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921)
2026-07-06 [email protected] Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015)
2026-07-06 [email protected] [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745)
2026-07-06 [email protected] [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922)
2026-07-06 [email protected] Roll pub packages (flutter/flutter#189009)
2026-07-06 [email protected] Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006)
2026-07-06 [email protected] Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007)
2026-07-06 [email protected] Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004)
2026-07-06 [email protected] Fixing multiline GetBoxesForRange (flutter/flutter#188803)
2026-07-06 [email protected] Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000)
2026-07-06 [email protected] Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992)
2026-07-06 [email protected] Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991)
2026-07-06 [email protected] Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990)
2026-07-06 [email protected] Add debugPaintFocusBoxes (flutter/flutter#188288)
2026-07-05 [email protected] Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989)
2026-07-05 [email protected] Roll Skia from 75a4bf6706bd to 7f99eee20fd6 (2 revisions) (flutter/flutter#188988)
...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@elliette elliette elliette approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD f: focus Focus traversal, gaining or losing focus framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@loic-sharma @elliette