Skip to content

Commit e32918b

Browse files
Document that Positioned also works inside an Overlay (flutter#190607)
`Positioned` works inside an `Overlay` as well as a `Stack`, but its documentation only described the `Stack` case. This updates the documentation across `Positioned`, `PositionedDirectional`, the animated variants and the transition variants. Fixes flutter#107903. The path restriction now covers both `RenderObjectWidget`s and other `ParentDataWidget`s, including `Expanded`, and identifies the boundary for each of the three overlay builders. `Overlay` documents the positioned-child alignment and normal non-positioned-child sizing, with links to `canSizeOverlay` and `alwaysSizeToContent` for the cases where a child determines the overlay size. Documentation only; no behavior or API changes. Validation from the review rounds is recorded in the inline replies and summary comments. The latest corrections are in `a9cecb891`. ## 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]. This PR is test-exempt because it only edits dartdoc text, with no behavioral or API changes. - [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]. <!-- 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 --------- Co-authored-by: Victor Sanni <[email protected]>
1 parent e4083c9 commit e32918b

4 files changed

Lines changed: 91 additions & 28 deletions

File tree

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

Lines changed: 71 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4876,19 +4876,31 @@ class Stack extends MultiChildRenderObjectWidget {
48764876
}
48774877
}
48784878

4879-
/// A widget that controls where a child of a [Stack] is positioned.
4880-
///
4881-
/// A [Positioned] widget must be a descendant of a [Stack], and the path from
4882-
/// the [Positioned] widget to its enclosing [Stack] must contain only
4883-
/// [StatelessWidget]s or [StatefulWidget]s (not other kinds of widgets, like
4884-
/// [RenderObjectWidget]s).
4879+
/// A widget that positions its child within a [Stack] or an [Overlay].
4880+
///
4881+
/// A [Positioned] widget must be inside a [Stack], or inside the widget
4882+
/// subtree that an [Overlay] lays out: the widget returned by
4883+
/// [OverlayEntry.builder], by [OverlayPortal.overlayChildBuilder] or by the
4884+
/// builder passed to [OverlayPortal.overlayChildLayoutBuilder]. A [Stack] and
4885+
/// an [Overlay] both lay their children out with the stack layout algorithm
4886+
/// (see [RenderStack]). In either case, the path from the [Positioned] up to
4887+
/// that boundary must contain only widgets that build other widgets rather
4888+
/// than render anything themselves, such as [StatelessWidget]s,
4889+
/// [StatefulWidget]s and [InheritedWidget]s; it must not contain
4890+
/// [RenderObjectWidget]s or other [ParentDataWidget]s (such as [Expanded]).
4891+
///
4892+
/// For a [Stack], the boundary is the [Stack] itself. For an [Overlay], it is
4893+
/// the widget the builder returns, which is itself on that path and so must be
4894+
/// the [Positioned] or something that builds it, rather than a
4895+
/// [RenderObjectWidget] or another [ParentDataWidget].
48854896
///
48864897
/// {@youtube 560 315 https://www.youtube.com/watch?v=EgtPleVwxBQ}
48874898
///
48884899
/// If a widget is wrapped in a [Positioned], then it is a _positioned_ widget
4889-
/// in its [Stack]. If the [top] property is non-null, the top edge of this child
4890-
/// will be positioned [top] layout units from the top of the stack widget. The
4891-
/// [right], [bottom], and [left] properties work analogously.
4900+
/// in its [Stack] or [Overlay]. If the [top] property is non-null, the top edge
4901+
/// of this child will be positioned [top] layout units from the top of the
4902+
/// [Stack] or the [Overlay]. The [right], [bottom], and [left] properties work
4903+
/// analogously.
48924904
///
48934905
/// If both the [top] and [bottom] properties are non-null, then the child will
48944906
/// be forced to have exactly the height required to satisfy both constraints.
@@ -4898,10 +4910,12 @@ class Stack extends MultiChildRenderObjectWidget {
48984910
/// corresponding position property (e.g. [top] and [height]).
48994911
///
49004912
/// If all three values on a particular axis are null, then the
4901-
/// [Stack.alignment] property is used to position the child.
4913+
/// [Stack.alignment] property is used to position the child. An [Overlay] has
4914+
/// no such property; see [Overlay] for how it aligns such children.
49024915
///
4903-
/// If all six values are null, the child is a non-positioned child. The [Stack]
4904-
/// uses only the non-positioned children to size itself.
4916+
/// If all six values are null, the child is a non-positioned child, and a
4917+
/// [Stack] uses only its non-positioned children to size itself. See [Overlay]
4918+
/// for how it sizes such children.
49054919
///
49064920
/// See also:
49074921
///
@@ -4910,8 +4924,18 @@ class Stack extends MultiChildRenderObjectWidget {
49104924
/// * [PositionedTransition], which takes a provided [Animation] to transition
49114925
/// changes in the child's position over a given duration.
49124926
/// * [PositionedDirectional], which adapts to the ambient [Directionality].
4927+
/// * [Overlay], which lays its entries out using the same stack layout
4928+
/// algorithm, so that an [OverlayEntry] can position its contents with a
4929+
/// [Positioned].
4930+
/// * [OverlayPortal], the declarative API for showing a widget on an
4931+
/// [Overlay], whose overlay child can also be positioned with a
4932+
/// [Positioned].
4933+
/// * [CompositedTransformFollower], which positions its child relative to a
4934+
/// [CompositedTransformTarget] elsewhere in the tree, an alternative way to
4935+
/// position a widget that is shown on an [Overlay].
49134936
class Positioned extends ParentDataWidget<StackParentData> {
4914-
/// Creates a widget that controls where a child of a [Stack] is positioned.
4937+
/// Creates a widget that positions its child within a [Stack] or an
4938+
/// [Overlay].
49154939
///
49164940
/// Only two out of the three horizontal values ([left], [right],
49174941
/// [width]), and only two out of the three vertical values ([top],
@@ -4973,7 +4997,8 @@ class Positioned extends ParentDataWidget<StackParentData> {
49734997
}) : width = null,
49744998
height = null;
49754999

4976-
/// Creates a widget that controls where a child of a [Stack] is positioned.
5000+
/// Creates a widget that positions its child within a [Stack] or an
5001+
/// [Overlay].
49775002
///
49785003
/// Only two out of the three horizontal values (`start`, `end`,
49795004
/// [width]), and only two out of the three vertical values ([top],
@@ -5126,22 +5151,34 @@ class Positioned extends ParentDataWidget<StackParentData> {
51265151
}
51275152
}
51285153

5129-
/// A widget that controls where a child of a [Stack] is positioned without
5154+
/// A widget that positions its child within a [Stack] or an [Overlay] without
51305155
/// committing to a specific [TextDirection].
51315156
///
51325157
/// The ambient [Directionality] is used to determine whether [start] is to the
51335158
/// left or to the right.
51345159
///
5135-
/// A [PositionedDirectional] widget must be a descendant of a [Stack], and the
5136-
/// path from the [PositionedDirectional] widget to its enclosing [Stack] must
5137-
/// contain only [StatelessWidget]s or [StatefulWidget]s (not other kinds of
5138-
/// widgets, like [RenderObjectWidget]s).
5160+
/// A [PositionedDirectional] widget must be inside a [Stack], or inside the
5161+
/// widget subtree that an [Overlay] lays out: the widget returned by
5162+
/// [OverlayEntry.builder], by [OverlayPortal.overlayChildBuilder] or by the
5163+
/// builder passed to [OverlayPortal.overlayChildLayoutBuilder]. A [Stack] and
5164+
/// an [Overlay] both lay their children out with the stack layout algorithm
5165+
/// (see [RenderStack]). In either case, the path from the
5166+
/// [PositionedDirectional] up to that boundary must contain only widgets that
5167+
/// build other widgets rather than render anything themselves, such as
5168+
/// [StatelessWidget]s, [StatefulWidget]s and [InheritedWidget]s; it must not
5169+
/// contain [RenderObjectWidget]s or other [ParentDataWidget]s (such as
5170+
/// [Expanded]).
5171+
///
5172+
/// For a [Stack], the boundary is the [Stack] itself. For an [Overlay], it is
5173+
/// the widget the builder returns, which is itself on that path and so must be
5174+
/// the [PositionedDirectional] or something that builds it, rather than a
5175+
/// [RenderObjectWidget] or another [ParentDataWidget].
51395176
///
51405177
/// If a widget is wrapped in a [PositionedDirectional], then it is a
5141-
/// _positioned_ widget in its [Stack]. If the [top] property is non-null, the
5142-
/// top edge of this child/ will be positioned [top] layout units from the top
5143-
/// of the stack widget. The [start], [bottom], and [end] properties work
5144-
/// analogously.
5178+
/// _positioned_ widget in its [Stack] or [Overlay]. If the [top] property is
5179+
/// non-null, the top edge of this child will be positioned [top] layout units
5180+
/// from the top of the [Stack] or the [Overlay]. The [start], [bottom], and
5181+
/// [end] properties work analogously.
51455182
///
51465183
/// If both the [top] and [bottom] properties are non-null, then the child will
51475184
/// be forced to have exactly the height required to satisfy both constraints.
@@ -5158,8 +5195,18 @@ class Positioned extends ParentDataWidget<StackParentData> {
51585195
/// * [AnimatedPositionedDirectional], which automatically transitions
51595196
/// the child's position over a given duration whenever the given position
51605197
/// changes.
5198+
/// * [Overlay], which lays its entries out using the same stack layout
5199+
/// algorithm, so that an [OverlayEntry] can position its contents with a
5200+
/// [PositionedDirectional].
5201+
/// * [OverlayPortal], the declarative API for showing a widget on an
5202+
/// [Overlay], whose overlay child can also be positioned with a
5203+
/// [PositionedDirectional].
5204+
/// * [CompositedTransformFollower], which positions its child relative to a
5205+
/// [CompositedTransformTarget] elsewhere in the tree, an alternative way to
5206+
/// position a widget that is shown on an [Overlay].
51615207
class PositionedDirectional extends StatelessWidget {
5162-
/// Creates a widget that controls where a child of a [Stack] is positioned.
5208+
/// Creates a widget that positions its child within a [Stack] or an
5209+
/// [Overlay].
51635210
///
51645211
/// Only two out of the three horizontal values (`start`, `end`,
51655212
/// [width]), and only two out of the three vertical values ([top],

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1092,7 +1092,8 @@ class _AnimatedAlignState extends AnimatedWidgetBaseState<AnimatedAlign> {
10921092
///
10931093
/// {@youtube 560 315 https://www.youtube.com/watch?v=hC3s2YdtWt8}
10941094
///
1095-
/// Only works if it's the child of a [Stack].
1095+
/// Only works inside a [Stack] or an [Overlay]; see [Positioned] for the
1096+
/// exact restrictions.
10961097
///
10971098
/// This widget is a good choice if the _size_ of the child would end up
10981099
/// changing as a result of this animation. If the size is intended to remain
@@ -1281,7 +1282,8 @@ class _AnimatedPositionedState extends AnimatedWidgetBaseState<AnimatedPositione
12811282
/// The ambient [Directionality] is used to determine whether [start] is to the
12821283
/// left or to the right.
12831284
///
1284-
/// Only works if it's the child of a [Stack].
1285+
/// Only works inside a [Stack] or an [Overlay]; see [PositionedDirectional]
1286+
/// for the exact restrictions.
12851287
///
12861288
/// This widget is a good choice if the _size_ of the child would end up
12871289
/// changing as a result of this animation. If the size is intended to remain

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -458,6 +458,16 @@ class _OverlayEntryWidgetState extends State<_OverlayEntryWidget> {
458458
/// that it can resolve direction-sensitive coordinates of any
459459
/// [Positioned.directional] children.
460460
///
461+
/// The widget an entry builds, or that [OverlayPortal] shows on this overlay,
462+
/// can be a [Positioned], in which case it is laid out and placed the way a
463+
/// positioned child of a [Stack] would be. See [Positioned] for the
464+
/// restrictions that apply. Where such a child leaves an axis unspecified, it
465+
/// is aligned on that axis as if [Stack.alignment] were
466+
/// [AlignmentDirectional.topStart] — this is not configurable. Children that
467+
/// are not positioned normally fill the overlay, as the children of a [Stack]
468+
/// with [StackFit.expand] do. See [OverlayEntry.canSizeOverlay] and
469+
/// [alwaysSizeToContent] for when a child sizes the overlay instead.
470+
///
461471
/// For widgets drawn in an [OverlayEntry], do not assume that the size of the
462472
/// [Overlay] is the size returned by [MediaQuery.sizeOf]. Nested overlays can
463473
/// have different sizes.
@@ -477,6 +487,8 @@ class _OverlayEntryWidgetState extends State<_OverlayEntryWidget> {
477487
/// * [MaterialApp], which inserts an [Overlay] widget indirectly via its [Navigator].
478488
/// * [CupertinoApp], which inserts an [Overlay] widget indirectly via its [Navigator].
479489
/// * [Stack], which allows directly displaying a stack of widgets.
490+
/// * [Positioned], which the widget an entry builds can be, to position it
491+
/// within the overlay the same way it positions a child of a [Stack].
480492
class Overlay extends StatefulWidget {
481493
/// Creates an overlay.
482494
///

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -756,7 +756,8 @@ class RelativeRectTween extends Tween<RelativeRect> {
756756
/// [Animation<RelativeRect>] to transition the child's position from a start
757757
/// position to an end position over the lifetime of the animation.
758758
///
759-
/// Only works if it's the child of a [Stack].
759+
/// Only works inside a [Stack] or an [Overlay]; see [Positioned] for the
760+
/// exact restrictions.
760761
///
761762
/// Here's an illustration of the [PositionedTransition] widget, with it's [rect]
762763
/// animated by a [CurvedAnimation] set to [Curves.elasticInOut]:
@@ -809,7 +810,8 @@ class PositionedTransition extends AnimatedWidget {
809810
/// based on the value of [rect] relative to a bounding box with the
810811
/// specified [size].
811812
///
812-
/// Only works if it's the child of a [Stack].
813+
/// Only works inside a [Stack] or an [Overlay]; see [Positioned] for the
814+
/// exact restrictions.
813815
///
814816
/// Here's an illustration of the [RelativePositionedTransition] widget, with it's [rect]
815817
/// animated by a [CurvedAnimation] set to [Curves.elasticInOut]:

0 commit comments

Comments
 (0)