@@ -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].
49134936class 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].
51615207class 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] ,
0 commit comments