Allow `OverlayPortal.overlayChild` to compute the paint transform from `OverlayPortal.child` to the target overlay #163575

LongCatIsLooong · 2025-02-19T00:40:27Z

This change makes overlayChild unreachable via regular layout treewalk, so the paint transform from OverlayPortal.child to the target overlay can be reliably computed during layout (assuming the paint transform of all nodes in the path are known during layout, see the comments below).

This is part of the changes that will eventually (hopefully) enable an Overlay API that allows an accessory view to change its size and location based on the main view's size and location in the Overlay (similar to CompositedTransform{Target, Follower}) .

Notable use cases of such an API:

Autocomplete, where the options view is anchored to the input field, but its size is also limited by the gap between the input field and the edge of the Overlay (and currently computing that has an 1-frame delay).
Various text field context menus / tooltips that situate themselves at the bottom of the input field if the top of the input field is too close to the app bar / top edge of the screen.
Slider value indicators that change shape to avoid running into screen edges.

This PR does not enable the API by itself, since the accessory view would need to be marked as needing relayout when the main view's paint transform within the Overlay changes. See <PR #TBD> for the implementation that marks the overlay child dirty when the paint transform changes.

Differences between the new API and `CompositedTransform{Target, Follower}`

The new API's use cases largely overlap that of CompositedTransform{Target, Follower}, but it additionally:

allows the layout of the overlay child to depend on the paint transform of the regular overlay child, while CompositedTransformFollower can only follow.
does not have the paint order restriction CompositedTransformFollower has (that the CompositedTransformTarget must come earlier in the paint order than this CompositedTransformFollower).

On the other hand:

the new API only works in an Overlay. In rare cases the parent RenderObject may need the size of the follower (can't really think of one though).
the new API makes the assumption that the desired paint transform is up-to-date during the layout phase, which is not true if there's a RenderFollowerLayer in the path, as its paint transform is only updated in addToScene, way after the layout process is done. So it's a bit leaky since whether there's a RenderFollowerLayer is an implementation detail.

I'll try to add asserts to catch the incompatibility. If the new API works then i'd expect it to significantly reduce the use of CompositedTransformFollower.

Part 2 of this PR: LongCatIsLooong/flutter@OverlayPortal-always-add-to-dirty-list...LongCatIsLooong:flutter:OverlayPortal-paint-transform-builder

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
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.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Such that nobody `implements` it. Currently it has private APIs used by the `RenderObject` class (e.g., the dirty lists). If someone were to implement a `PipelineOwner` outside of object.dart, they will get a runtime crash since they won't be able to provide those private APIs and RenderObjects actually expect those APIs to exist.

This allows `overlyChild` to inspect the layout of the regular child (for example, computing the size and the paint transform from the Overlay to the regular child in `overlayChild`'s performLayout method).

…ays-add-to-dirty-list

…ongCatIsLooong/flutter into OverlayPortal-always-add-to-dirty-list

knopp · 2025-02-24T22:18:47Z

In case it is useful to someone: It is already possible to have overlay widget that tracks the anchor and can adjust size / position depending on available space without the 1 frame delay.

Here is it in action. You can see it in action by opening the overlay, making the window small and scrolling. In the example size is not adjusted but the constrains are calculated dynamically taking anchor location into action so it's possible.

EDIT: Actually, the size in example is adjusted dynamically so the popover always fits the bounds.

And here is the implementation. It relies on persistent frame callback to ensure the layout always up to date. but due to layout boundaries the overhead should be negligible.

LongCatIsLooong · 2025-02-24T23:23:44Z

In case it is useful to someone: It is already possible to have overlay widget that tracks the anchor and can adjust size / position depending on available space without the 1 frame delay.

Here is it in action. You can see it in action by opening the overlay, making the window small and scrolling. In the example size is not adjusted but the constrains are calculated dynamically taking anchor location into action so it's possible.

EDIT: Actually, the size in example is adjusted dynamically so the popover always fits the bounds.

And here is the implementation. It relies on persistent frame callback to ensure the layout always up to date. but due to layout boundaries the overhead should be negligible.

@knopp This is very interesting, thanks! Quick question after looking at the implementation: it looks like the implementation maintains its own persistent callback queue, which will be drained after RenderBinding.drawFrame (where PipelineOwner flushes layout/paint etc). The new persistent callbacks (_onFrame) added to the queue seem to only dirty render objects. So those dirty nodes will only redo layout in the next frame, since RenderBinding.drawFrame is called before _onFrame?

I couldn't find a way to schedule those markNeedsLayout calls before drawFrame so I decided to use transient callbacks and added a flag to prevent the transient callback from scheduling a new frame in #164034

knopp · 2025-02-25T09:55:57Z

It calls markNeedsLayout after the frame, but it doesn't schedule new frame. That basically means the layout is always dirty and will be computed on each frame, while the popover is visible, no matter what.

The second reason why this works is that the _RenderDeferredLayoutBox depth is always higher than the anchor, and because it's a relayout boundary we can be sure that the layout is always performed after the anchor layout is already done

(it's been a while since a wrote this so maybe I'm misremembering something, but this should be it).

goderbauer · 2025-03-04T17:31:07Z

In rare cases the parent RenderObject may need the size of the follower (can't really think of one though).

To check my own understanding: CompositedTransform{Target, Follower} also doesn't support this, right?

goderbauer

Overall this looks reasonable to me.

goderbauer · 2025-03-04T17:33:30Z

packages/flutter/lib/src/rendering/object.dart

  /// child undergoes layout. Otherwise, the child can change its layout
  /// information without informing this render object.
+  ///
+  /// It is recommended to establish / update the paint transform of this render


I assume this means you want applyPaintTransform to return the correct answer after layout? Maybe link to that method from here so people have context on what the "paint transform" is?

Maybe also have it link to getTransformTo for even more context.

Rephrased the paragraph. Note to myself to change the backticks to square brackets in PR2 for the OverlayPortal.overlayChildLayoutBuilder reference.

goderbauer · 2025-03-04T17:46:57Z

packages/flutter/lib/src/widgets/overlay.dart

+      // Instead of laying out this subtree via treewalk, adding it to the dirty
+      // list. This ensures:
+      //
+      //  1. this node will be laid out by the PipelineOwner *after* the two


For my own understanding (and worthwhile to document here): the after is guaranteed because this RO has a higher depth than the theater and surrogate?

goderbauer · 2025-03-04T17:50:38Z

packages/flutter/lib/src/widgets/overlay.dart

  }

+  @override
+  void layout(Constraints constraints, {bool parentUsesSize = false}) {


Is it okay that we completely ignore the parentUsesSize here? Maybe leave a comment on why? And should we also assert that it actually isn't set by the parent?

…ays-add-to-dirty-list

LongCatIsLooong · 2025-03-04T21:30:45Z

In rare cases the parent RenderObject may need the size of the follower (can't really think of one though).

To check my own understanding: CompositedTransform{Target, Follower} also doesn't support this, right?

I think I was thinking about the following case:

Flex(
  children: [ A, B,  CompositedTransformFollower_C, D]
)

where the parent render box would still reserve space for the transform follow (C), and at the same time C's offset is determined by something else (its Target). I don't know if there are practical use cases

This API allows the widget tree of an `OverlayPortal.overlayChild` to depend on various layout information (e.g. the incoming constraints, or the size of a RenderObject) from another child subtree of `Overlay` that does layout before the `overlayChild`. Most RenderObject subclasses can only access its child's or children's layout info, but not the layout info of its other descendants because of the "relayout boundary" optimization. Such locality makes the layout dependencies easier to reason about but it also makes it difficult to implement certain common UI patterns (see the examples in the description of the [previous PR](#163575)) The API is currently only available on `OverlayPortal` as it is the only Overlay API (AFAIK) that guarantees every render object in a "path" within the render tree has finished doing layout. TODO: polish the API docs and code comments TODO: more tests? TODO: markNeedsLayout should not imply markNeedsPaint in this case (or in layout builders in general). part1: #163575 diff this ... part1 LongCatIsLooong/flutter@OverlayPortal-always-add-to-dirty-list...LongCatIsLooong:flutter:OverlayPortal-paint-transform-builder ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] 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. If you need help, consider asking for advice on the #hackers-new channel on [Discord].  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [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

This API allows the widget tree of an `OverlayPortal.overlayChild` to depend on various layout information (e.g. the incoming constraints, or the size of a RenderObject) from another child subtree of `Overlay` that does layout before the `overlayChild`. Most RenderObject subclasses can only access its child's or children's layout info, but not the layout info of its other descendants because of the "relayout boundary" optimization. Such locality makes the layout dependencies easier to reason about but it also makes it difficult to implement certain common UI patterns (see the examples in the description of the [previous PR](flutter#163575)) The API is currently only available on `OverlayPortal` as it is the only Overlay API (AFAIK) that guarantees every render object in a "path" within the render tree has finished doing layout. TODO: polish the API docs and code comments TODO: more tests? TODO: markNeedsLayout should not imply markNeedsPaint in this case (or in layout builders in general). part1: flutter#163575 diff this ... part1 LongCatIsLooong/flutter@OverlayPortal-always-add-to-dirty-list...LongCatIsLooong:flutter:OverlayPortal-paint-transform-builder ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] 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. If you need help, consider asking for advice on the #hackers-new channel on [Discord].  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [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

LongCatIsLooong added 5 commits January 16, 2025 04:11

OverlayPortal always adds overlay child to the dirty list

91184d2

This allows `overlyChild` to inspect the layout of the regular child (for example, computing the size and the paint transform from the Overlay to the regular child in `overlayChild`'s performLayout method).

docs

4530b4f

Merge remote-tracking branch 'upstream/master' into OverlayPortal-alw…

b2f5087

…ays-add-to-dirty-list

add tests

330efb2

github-actions bot added the framework flutter/packages/flutter repository. See also f: labels. label Feb 19, 2025

Merge branch 'master' into OverlayPortal-always-add-to-dirty-list

04ab23b

This was referenced Feb 20, 2025

DropdownMenu Entries Not Positioned Correctly on Keyboard Appearance when requestFocusOnTap set to true #149037

Closed

[DropdownMenu] menu appears behind the keyboard #123395

Open

LongCatIsLooong added 3 commits February 23, 2025 19:35

Merge branch 'master' into OverlayPortal-always-add-to-dirty-list

7852fac

Merge remote-tracking branch 'upstream/master' into OverlayPortal-alw…

6b4d86a

…ays-add-to-dirty-list

Merge branch 'OverlayPortal-always-add-to-dirty-list' of github.com:L…

dace9dd

…ongCatIsLooong/flutter into OverlayPortal-always-add-to-dirty-list

LongCatIsLooong mentioned this pull request Feb 24, 2025

OverlayPortal.overlayChildLayoutBuilder #164034

Merged

9 tasks

leaks

b5f6b59

TahaTesser mentioned this pull request Feb 25, 2025

Allow the Slider to always show the value indicator. #162223

Merged

9 tasks

LongCatIsLooong marked this pull request as ready for review March 3, 2025 18:46

LongCatIsLooong requested a review from goderbauer March 3, 2025 18:46

goderbauer reviewed Mar 4, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/master' into OverlayPortal-alw…

1c991c0

…ays-add-to-dirty-list

LongCatIsLooong closed this Mar 5, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Allow `OverlayPortal.overlayChild` to compute the paint transform from `OverlayPortal.child` to the target overlay #163575

Allow `OverlayPortal.overlayChild` to compute the paint transform from `OverlayPortal.child` to the target overlay #163575

Uh oh!

LongCatIsLooong commented Feb 19, 2025 •

edited

Loading

Uh oh!

knopp commented Feb 24, 2025 •

edited

Loading

Uh oh!

LongCatIsLooong commented Feb 24, 2025 •

edited

Loading

Uh oh!

knopp commented Feb 25, 2025

Uh oh!

goderbauer commented Mar 4, 2025

Uh oh!

goderbauer left a comment

Uh oh!

goderbauer Mar 4, 2025

Uh oh!

goderbauer Mar 4, 2025

Uh oh!

LongCatIsLooong Mar 4, 2025

Uh oh!

goderbauer Mar 4, 2025

Uh oh!

goderbauer Mar 4, 2025

Uh oh!

LongCatIsLooong commented Mar 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Allow OverlayPortal.overlayChild to compute the paint transform from OverlayPortal.child to the target overlay #163575

Allow OverlayPortal.overlayChild to compute the paint transform from OverlayPortal.child to the target overlay #163575

Uh oh!

Conversation

LongCatIsLooong commented Feb 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Differences between the new API and CompositedTransform{Target, Follower}

Pre-launch Checklist

Uh oh!

knopp commented Feb 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LongCatIsLooong commented Feb 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knopp commented Feb 25, 2025

Uh oh!

goderbauer commented Mar 4, 2025

Uh oh!

goderbauer left a comment

Choose a reason for hiding this comment

Uh oh!

goderbauer Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

goderbauer Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

LongCatIsLooong Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

goderbauer Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

goderbauer Mar 4, 2025

Choose a reason for hiding this comment

Uh oh!

LongCatIsLooong commented Mar 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Allow `OverlayPortal.overlayChild` to compute the paint transform from `OverlayPortal.child` to the target overlay #163575

Allow `OverlayPortal.overlayChild` to compute the paint transform from `OverlayPortal.child` to the target overlay #163575

LongCatIsLooong commented Feb 19, 2025 •

edited

Loading

Differences between the new API and `CompositedTransform{Target, Follower}`

knopp commented Feb 24, 2025 •

edited

Loading

LongCatIsLooong commented Feb 24, 2025 •

edited

Loading