firka/flutter
firka/flutter
4
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve Stack documentation.

Browse Source
This commit is contained in:
Hixie 2016-03-17 12:44:55 -07:00
parent 50a249e3ec
commit 1d699b2146
2 changed files with 48 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
packages/flutter/lib/src/rendering/stack.dart
View File

@ -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<RenderBox> {
/// 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<RenderBox> {
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<RenderBox> children,

35
packages/flutter/lib/src/widgets/basic.dart
View File

@ -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<StackRenderObjectWidgetBase> {
/// 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<StackRenderObjectWidgetBase> {
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<StackRenderObjectWidgetBase> {
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;