Fix RouteAware.didPushNext documentation inaccuracy#183097
Fix RouteAware.didPushNext documentation inaccuracy#183097auto-submit[bot] merged 10 commits intoflutter:masterfrom
Conversation
The documentation incorrectly states that didPushNext is called when "the current route is no longer visible". In reality, didPushNext is called synchronously during the push operation, before the transition animation completes. At this point, the current route may still be partially visible as it animates out. This commit corrects the documentation to accurately describe the timing and provides guidance on how to detect when a route is fully obscured. Fixes flutter#24594
github-actions
bot
added
framework
![gemini-code-assist[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for RouteAware.didPushNext to clarify that it's called before the route transition animation completes. The change is accurate and improves the documentation. I've suggested adding a small code example to further illustrate how to perform actions after the animation is complete, which would make the documentation even more helpful for developers.
| /// Called when a new route has been pushed. | ||
| /// | ||
| /// Note that this is called during the push operation, before the transition | ||
| /// animation completes. At this point the current route may still be | ||
| /// partially visible as it animates out. To perform actions after the route | ||
| /// is fully obscured, consider using [ModalRoute.animation] to listen for | ||
| /// animation completion. |
There was a problem hiding this comment.
This documentation update is a great improvement in accuracy. To make it even more helpful for developers, consider adding a small code snippet showing how to use ModalRoute.animation as you've suggested. This aligns with the Flutter style guide's recommendation to provide sample code where helpful.
/// Called when a new route has been pushed.
///
/// Note that this is called during the push operation, before the transition
/// animation completes. At this point the current route may still be
/// partially visible as it animates out. To perform actions after the route
/// is fully obscured, consider using [ModalRoute.animation] to listen for
/// animation completion, for example:
///
/// ```dart
/// ModalRoute.of(context)?.animation?.addStatusListener((AnimationStatus status) {
/// if (status == AnimationStatus.completed) {
/// // The new route is now fully visible and the old route is fully obscured.
/// }
/// });
/// ```References
- The style guide recommends providing sample code to make documentation more useful. Adding a snippet for
ModalRoute.animationwould be a good example of this. (link)
There was a problem hiding this comment.
Thanks for the suggestion! I've added a code snippet demonstrating how to use ModalRoute.animation with a status listener, as recommended. This should make it clearer for developers how to perform actions after the transition animation fully completes.
victorsanni
left a comment
victorsanni
left a comment
There was a problem hiding this comment.
This PR will need a test exemption, can you request for one on discord?
|
|
||
| /// Called when a new route has been pushed, and the current route is no | ||
| /// longer visible. | ||
| /// Called when a new route has been pushed. |
There was a problem hiding this comment.
This will mean didPush and didPushNext have the same API docs preview in RouteAware's documentation, can we somehow differentiate them in the opening line?
There was a problem hiding this comment.
Good catch! Updated the opening line to "Called when a new route has been pushed on top of this route, temporarily obscuring it." which better captures the semantics and distinguishes it from didPush.
| /// visible as it animates out. To perform actions after the route is fully | ||
| /// obscured, consider using [ModalRoute.animation] to listen for animation | ||
| /// completion, for example: |
There was a problem hiding this comment.
After the route is fully obscured, wouldn't ModalRoute.animation be completed? Should we listen for the secondaryAnimation instead? Asking for clarification.
There was a problem hiding this comment.
You are right! ModalRoute.animation is the route's own entrance animation, which is already completed by the time didPushNext fires. The correct one is secondaryAnimation, which is driven by the incoming route and goes from 0 to 1 as the new route transitions in. Updated the snippet to use secondaryAnimation instead.
…aryAnimation, add tool snippet template
@victorsanni Per the docs "a bot will comment on your PR if you need an explicit exemption". There's no bot comment here (because the bot knows that |
auto-submit
bot
removed
the
autosubmit
|
autosubmit label was removed for flutter/flutter/183097, because - The status or check suite Google testing has failed. Please fix the issues identified (or deflake) before re-applying this label. |
auto-submit
bot
removed
the
autosubmit
|
auto label is removed for flutter/flutter/183097, Failed to enqueue flutter/flutter/183097 with HTTP 400: GraphQL mutate failed. |
|
Hey @ishaquehassan can you rebase this with the latest from the master branch? This cannot land with a base commit older than 7 days. |
Done! |
|
I am not sure that updated the base commit, merging in master is not the same as rebasing. But we'll see what the bot thinks. :) |
flutter-dashboard
bot
removed
the
autosubmit
Roll Flutter from 732e05dd483c to d117642c18e0 (47 revisions) flutter/flutter@732e05d...d117642 2026-03-17 [email protected] Roll Skia from fa3bb1f60d99 to dba893a44d7a (1 revision) (flutter/flutter#183783) 2026-03-17 [email protected] [ios][pv]fix admob banner scrollable on ios 18.2 (flutter/flutter#183274) 2026-03-17 [email protected] Roll Packages from 0f2eeae to a9d36fb (2 revisions) (flutter/flutter#183782) 2026-03-17 [email protected] Update goldctl version (flutter/flutter#183538) 2026-03-17 [email protected] Roll Skia from 69be1087807b to fa3bb1f60d99 (1 revision) (flutter/flutter#183779) 2026-03-17 [email protected] Roll Dart SDK from 38dedf00c2cd to 30cdd2634429 (1 revision) (flutter/flutter#183778) 2026-03-17 [email protected] Roll Fuchsia Linux SDK from s7rq9m8tH2aZtX-kP... to zYBvfzIH95BY3cCzL... (flutter/flutter#183777) 2026-03-17 [email protected] Roll Skia from 4ea039236580 to 69be1087807b (2 revisions) (flutter/flutter#183772) 2026-03-17 [email protected] Roll Skia from fb402093cfb5 to 4ea039236580 (1 revision) (flutter/flutter#183770) 2026-03-17 [email protected] Roll Skia from d6bc6d17d637 to fb402093cfb5 (8 revisions) (flutter/flutter#183765) 2026-03-17 [email protected] Roll Dart SDK from ff50ab8ecea4 to 38dedf00c2cd (2 revisions) (flutter/flutter#183764) 2026-03-17 [email protected] Wrap EGL image usage in a GObject (flutter/flutter#183539) 2026-03-17 [email protected] Adds platform_view_test_macos_impeller (flutter/flutter#183760) 2026-03-17 [email protected] Adds flush to metal screenshotter. (flutter/flutter#183758) 2026-03-16 [email protected] Add a platform OpenGL context. (flutter/flutter#183715) 2026-03-16 [email protected] Fix formatting, capitalization, and grammar in activation issue template (flutter/flutter#183061) 2026-03-16 [email protected] Roll Dart SDK from 4a6febbf882e to ff50ab8ecea4 (2 revisions) (flutter/flutter#183739) 2026-03-16 [email protected] docs: add code review guidance to CONTRIBUTING.md (flutter/flutter#182778) 2026-03-16 [email protected] Filter 'waiting for customer response' issues from macOS triage (flutter/flutter#183552) 2026-03-16 [email protected] Adds github action to reset cicd when new branches come (flutter/flutter#183675) 2026-03-16 [email protected] Adds macos impeller complex layout performance test (flutter/flutter#183669) 2026-03-16 [email protected] Roll Dart SDK from b74e5b537d71 to 4a6febbf882e (2 revisions) (flutter/flutter#183695) 2026-03-16 [email protected] Use properties to configure leak_tracking and test_randomization_off in .ci.yaml (flutter/flutter#183605) 2026-03-16 [email protected] [flutter_tools] Avoid File.exists and File.stat, as per enforced lint rule (flutter/flutter#183463) 2026-03-16 [email protected] Properly parse URIs for testPath when the host is running on Windows. (flutter/flutter#176881) 2026-03-16 [email protected] Roll Packages from 91f7c33 to 0f2eeae (6 revisions) (flutter/flutter#183730) 2026-03-16 [email protected] Roll Skia from a6ccaf95c6e0 to d6bc6d17d637 (5 revisions) (flutter/flutter#183726) 2026-03-16 [email protected] Roll Fuchsia Linux SDK from WOfyEFkxf9JX26VS-... to s7rq9m8tH2aZtX-kP... (flutter/flutter#183723) 2026-03-15 [email protected] Roll Skia from 34ace196b838 to a6ccaf95c6e0 (2 revisions) (flutter/flutter#183712) 2026-03-14 [email protected] Roll Fuchsia Linux SDK from vAWG8mRvsQHblDBsy... to WOfyEFkxf9JX26VS-... (flutter/flutter#183694) 2026-03-14 [email protected] Roll Skia from 06106120c6bf to 34ace196b838 (1 revision) (flutter/flutter#183677) 2026-03-14 [email protected] Roll Dart SDK from 6a3dc9d4f881 to b74e5b537d71 (2 revisions) (flutter/flutter#183676) 2026-03-14 [email protected] Add some quality of life improvements to the release GitHub workflows. (flutter/flutter#183658) 2026-03-14 [email protected] Fix RouteAware.didPushNext documentation inaccuracy (flutter/flutter#183097) 2026-03-13 [email protected] Adds complex layout impeller startup benchmark (flutter/flutter#183655) 2026-03-13 [email protected] Adds switch for sdf rendering plus golden tests (flutter/flutter#183543) 2026-03-13 [email protected] Made complex_layout_scroll_perf explicitly skia (flutter/flutter#183663) 2026-03-13 [email protected] Update android integration test to match the current android semantics (flutter/flutter#183548) 2026-03-13 [email protected] Roll Skia from 6c0346103c24 to 06106120c6bf (3 revisions) (flutter/flutter#183654) 2026-03-13 [email protected] Roll Dart SDK from d5f6d3c17499 to 6a3dc9d4f881 (1 revision) (flutter/flutter#183652) 2026-03-13 [email protected] Fix PinnedHeaderSliver semantics focus capture (flutter/flutter#179023) 2026-03-13 [email protected] [a11y][android] In Android 16, sendWindowContentChangeEvent when check state changes (flutter/flutter#183606) 2026-03-13 [email protected] Update gradle utils to know about kgp 2.3.10 constraints (flutter/flutter#183416) 2026-03-13 [email protected] Roll Skia from 029229d8be91 to 6c0346103c24 (5 revisions) (flutter/flutter#183648) 2026-03-13 [email protected] Roll Fuchsia Linux SDK from jJbpv4J_tjW-wuKDq... to vAWG8mRvsQHblDBsy... (flutter/flutter#183646) 2026-03-13 [email protected] [flutter_tools] Support flavors and transformers for shaders (flutter/flutter#181889) ...
4 participants
The documentation for
RouteAware.didPushNextincorrectly states that the method is called when "the current route is no longer visible". However, tracing through the source code inroutes.dartshows thatdidPushNextis called synchronously during the push operation inRouteObserver.didPush(), before the transition animation completes. At this point, the current route may still be partially visible as it animates out.This PR corrects the documentation to accurately describe when
didPushNextis called and provides guidance for developers who need to perform actions after the route is fully obscured.This PR implements the analysis from my earlier comment on this issue.
Fixes #24594
Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the
gemini-code-assistbot 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.