From 1d699b214678f679484d77dc93e8e6d9dac90109 Mon Sep 17 00:00:00 2001 From: Hixie Date: Thu, 17 Mar 2016 12:44:55 -0700 Subject: [PATCH] Improve Stack documentation. --- packages/flutter/lib/src/rendering/stack.dart | 37 ++++++++++--------- packages/flutter/lib/src/widgets/basic.dart | 35 +++++++++++++++--- 2 files changed, 48 insertions(+), 24 deletions(-) diff --git a/packages/flutter/lib/src/rendering/stack.dart b/packages/flutter/lib/src/rendering/stack.dart index d360f5cbb2..a0c23ba996 100644 --- a/packages/flutter/lib/src/rendering/stack.dart +++ b/packages/flutter/lib/src/rendering/stack.dart @@ -18,7 +18,6 @@ import 'object.dart'; /// If you create the RelativeRect with null values, the methods on /// RelativeRect will not work usefully (or at all). class RelativeRect { - /// Creates a RelativeRect with the given values. const RelativeRect.fromLTRB(this.left, this.top, this.right, this.bottom); @@ -136,16 +135,16 @@ class RelativeRect { /// Parent data for use with [RenderStack] class StackParentData extends ContainerBoxParentDataMixin { - /// The offset of the child's top edge from the top of the stack. + /// The distance by which the child's top edge is inset from the top of the stack. double top; - /// The offset of the child's right edge from the right of the stack. + /// The distance by which the child's right edge is inset from the right of the stack. double right; - /// The offset of the child's bottom edge from the bottom of the stack. + /// The distance by which the child's bottom edge is inset from the bottom of the stack. double bottom; - /// The offset of the child's left edge from the left of the stack. + /// The distance by which the child's left edge is inset from the left of the stack. double left; /// The child's width. @@ -167,9 +166,9 @@ class StackParentData extends ContainerBoxParentDataMixin { left = value.left; } - /// Whether this child is considered positioned + /// Whether this child is considered positioned. /// - /// A child is positioned if any of the top, right, bottom, or left offsets + /// A child is positioned if any of the top, right, bottom, or left properties /// are non-null. Positioned children do not factor into determining the size /// of the stack but are instead placed relative to the non-positioned /// children in the stack. @@ -411,7 +410,7 @@ abstract class RenderStackBase extends RenderBox /// In a stack layout, the children are positioned on top of each other in the /// order in which they appear in the child list. First, the non-positioned /// children (those with null values for top, right, bottom, and left) are -/// initially layed out and placed in the upper-left corner of the stack. The +/// laid out and initially placed in the upper-left corner of the stack. The /// stack is then sized to enclose all of the non-positioned children. If there /// are no non-positioned children, the stack becomes as large as possible. /// @@ -419,23 +418,25 @@ abstract class RenderStackBase extends RenderBox /// parameter. The left of each non-positioned child becomes the /// difference between the child's width and the stack's width scaled by /// alignment.x. The top of each non-positioned child is computed -/// similarly and scaled by alignement.y. So if the alignment x and y properties +/// similarly and scaled by alignment.y. So if the alignment x and y properties /// are 0.0 (the default) then the non-positioned children remain in the /// upper-left corner. If the alignment x and y properties are 0.5 then the /// non-positioned children are centered within the stack. /// /// Next, the positioned children are laid out. If a child has top and bottom /// values that are both non-null, the child is given a fixed height determined -/// by deflating the width of the stack by the sum of the top and bottom values. -/// Similarly, if the child has rigth and left values that are both non-null, -/// the child is given a fixed width. Otherwise, the child is given unbounded -/// space in the non-fixed dimensions. +/// by subtracting the sum of the top and bottom values from the height of the stack. +/// Similarly, if the child has right and left values that are both non-null, +/// the child is given a fixed width derived from the stack's width. +/// Otherwise, the child is given unbounded constraints in the non-fixed dimensions. /// -/// Once the child is laid out, the stack positions the child according to the -/// top, right, bottom, and left offsets. For example, if the top value is 10.0, -/// the top edge of the child will be placed 10.0 pixels from the top edge of -/// the stack. If the child extends beyond the bounds of the stack, the stack -/// will clip the child's painting to the bounds of the stack. +/// Once the child is laid out, the stack positions the child +/// according to the top, right, bottom, and left properties of their +/// [StackParentData]. For example, if the bottom value is 10.0, the +/// bottom edge of the child will be inset 10.0 pixels from the bottom +/// edge of the stack. If the child extends beyond the bounds of the +/// stack, the stack will clip the child's painting to the bounds of +/// the stack. class RenderStack extends RenderStackBase { RenderStack({ List children, diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 3e88be0136..e9d8c49a95 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -1161,6 +1161,12 @@ class IndexedStack extends StackRenderObjectWidgetBase { /// to its enclosing [Stack] must contain only [StatelessWidget]s or /// [StatefulWidget]s (not other kinds of widgets, like [RenderObjectWidget]s). class Positioned extends ParentDataWidget { + /// Creates a Positioned object with the given values. + /// + /// Only two out of the three horizontal values ([left], [right], + /// [width]), and only two out of the three vertical values ([top], + /// [bottom], [height]), can be set. In each case, at least one of + /// the three must be null. Positioned({ Key key, Widget child, @@ -1175,6 +1181,11 @@ class Positioned extends ParentDataWidget { assert(top == null || bottom == null || height == null); } + /// Creates a Positioned object with the values from the given [Rect]. + /// + /// This sets the [left], [top], [width], and [height] properties + /// from the given [Rect]. The [right] and [bottom] properties are + /// set to null. Positioned.fromRect({ Key key, Widget child, @@ -1187,27 +1198,39 @@ class Positioned extends ParentDataWidget { bottom = null, super(key: key, child: child); - /// The offset of the child's left edge from the left of the stack. + /// The distance that the child's left edge is inset from the left of the stack. + /// + /// Only two out of the three horizontal values ([left], [right], [width]) can be + /// set. The third must be null. final double left; - /// The offset of the child's top edge from the top of the stack. + /// The distance that the child's top edge is inset from the top of the stack. + /// + /// Only two out of the three vertical values ([top], [bottom], [height]) can be + /// set. The third must be null. final double top; - /// The offset of the child's right edge from the right of the stack. + /// The distance that the child's right edge is inset from the right of the stack. + /// + /// Only two out of the three horizontal values ([left], [right], [width]) can be + /// set. The third must be null. final double right; - /// The offset of the child's bottom edge from the bottom of the stack. + /// The distance that the child's bottom edge is inset from the bottom of the stack. + /// + /// Only two out of the three vertical values ([top], [bottom], [height]) can be + /// set. The third must be null. final double bottom; /// The child's width. /// - /// Only two out of the three horizontal values (left, right, width) can be + /// Only two out of the three horizontal values ([left], [right], [width]) can be /// set. The third must be null. final double width; /// The child's height. /// - /// Only two out of the three vertical values (top, bottom, height) can be + /// Only two out of the three vertical values ([top], [bottom], [height]) can be /// set. The third must be null. final double height;