diff --git a/packages/flutter/lib/src/rendering/custom_layout.dart b/packages/flutter/lib/src/rendering/custom_layout.dart index b8ea63f01f..5c04b61a6d 100644 --- a/packages/flutter/lib/src/rendering/custom_layout.dart +++ b/packages/flutter/lib/src/rendering/custom_layout.dart @@ -6,6 +6,7 @@ import 'box.dart'; import 'object.dart'; class MultiChildLayoutParentData extends ContainerBoxParentDataMixin { + /// An object representing the identity of this child. Object id; void merge(MultiChildLayoutParentData other) { @@ -17,6 +18,7 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin String toString() => '${super.toString()}; id=$id'; } +/// A delegate that controls the layout of multiple children. abstract class MultiChildLayoutDelegate { Map _idToChild; Set _debugChildrenNeedingLayout; @@ -94,6 +96,12 @@ abstract class MultiChildLayoutDelegate { void performLayout(Size size, BoxConstraints constraints); } +/// Defers the layout of multiple children to a delegate. +/// +/// The delegate can determine the layout constraints for each child and can +/// decide where to position each child. The delegate can also determine the +/// size of the parent, but the size of the parent cannot depend on the sizes of +/// the children. class RenderCustomMultiChildLayoutBox extends RenderBox with ContainerRenderObjectMixin, RenderBoxContainerDefaultsMixin { @@ -110,6 +118,7 @@ class RenderCustomMultiChildLayoutBox extends RenderBox child.parentData = new MultiChildLayoutParentData(); } + /// The delegate that controls the layout of the children. MultiChildLayoutDelegate get delegate => _delegate; MultiChildLayoutDelegate _delegate; void set delegate (MultiChildLayoutDelegate newDelegate) { diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index ccb2d2893a..031a1e86f5 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -21,7 +21,7 @@ export 'package:flutter/gestures.dart' show PointerUpEvent, PointerCancelEvent; -/// A base class for render objects that resemble their children +/// A base class for render objects that resemble their children. /// /// A proxy box has a single child and simply mimics all the properties of that /// child by calling through to the child for each function in the render box @@ -87,15 +87,16 @@ class RenderProxyBox extends RenderBox with RenderObjectWithChildMixin _stepWidth; double _stepWidth; void set stepWidth(double newStepWidth) { @@ -359,7 +360,7 @@ class RenderIntrinsicWidth extends RenderProxyBox { markNeedsLayout(); } - /// If non-null, force the child's height to be a multiple of this value + /// If non-null, force the child's height to be a multiple of this value. double get stepHeight => _stepHeight; double _stepHeight; void set stepHeight(double newStepHeight) { @@ -428,16 +429,13 @@ class RenderIntrinsicWidth extends RenderProxyBox { } } -/// Sizes its child to the child's intrinsic height -/// -/// This class will size its child's height to the child's maximum intrinsic -/// height. +/// Sizes its child to the child's intrinsic height. /// /// This class is useful, for example, when unlimited height is available and /// you would like a child that would otherwise attempt to expand infinitely to /// instead size itself to a more reasonable height. /// -/// Note: This class is relatively expensive. Avoid using it where possible. +/// This class is relatively expensive. Avoid using it where possible. class RenderIntrinsicHeight extends RenderProxyBox { RenderIntrinsicHeight({ @@ -486,20 +484,20 @@ class RenderIntrinsicHeight extends RenderProxyBox { } -/// Makes its child partially transparent +/// Makes its child partially transparent. /// /// This class paints its child into an intermediate buffer and then blends the /// child back into the scene partially transparent. /// -/// Note: This class is relatively expensive because it requires painting the -/// child into an intermediate buffer. +/// This class is relatively expensive because it requires painting the child +/// into an intermediate buffer. class RenderOpacity extends RenderProxyBox { RenderOpacity({ RenderBox child, double opacity }) : this._opacity = opacity, super(child) { assert(opacity >= 0.0 && opacity <= 1.0); } - /// The fraction to scale the child's alpha value + /// The fraction to scale the child's alpha value. /// /// An opacity of 1.0 is fully opaque. An opacity of 0.0 is fully transparent /// (i.e., invisible). @@ -566,7 +564,10 @@ class RenderShaderMask extends RenderProxyBox { } } +/// A class that provides custom clips. abstract class CustomClipper { + /// Returns a description of the clip given that the render object being + /// clipped is of the given size. T getClip(Size size); bool shouldRepaint(CustomClipper oldClipper); } @@ -577,6 +578,7 @@ abstract class _RenderCustomClip extends RenderProxyBox { CustomClipper clipper }) : _clipper = clipper, super(child); + /// If non-null, determines which clip to use on the child. CustomClipper get clipper => _clipper; CustomClipper _clipper; void set clipper (CustomClipper newClipper) { @@ -598,7 +600,7 @@ abstract class _RenderCustomClip extends RenderProxyBox { T get _clip => _clipper?.getClip(size) ?? _defaultClip; } -/// Clips its child using a rectangle +/// Clips its child using a rectangle. /// /// Prevents its child from painting outside its bounds. class RenderClipRect extends _RenderCustomClip { @@ -624,7 +626,7 @@ class RenderClipRect extends _RenderCustomClip { } } -/// Clips its child using a rounded rectangle +/// Clips its child using a rounded rectangle. /// /// Creates a rounded rectangle from its layout dimensions and the given x and /// y radius values and prevents its child from painting outside that rounded @@ -639,7 +641,7 @@ class RenderClipRRect extends RenderProxyBox { assert(_yRadius != null); } - /// The radius of the rounded corners in the horizontal direction in logical pixels + /// The radius of the rounded corners in the horizontal direction in logical pixels. /// /// Values are clamped to be between zero and half the width of the render /// object. @@ -653,7 +655,7 @@ class RenderClipRRect extends RenderProxyBox { markNeedsPaint(); } - /// The radius of the rounded corners in the vertical direction in logical pixels + /// The radius of the rounded corners in the vertical direction in logical pixels. /// /// Values are clamped to be between zero and half the height of the render /// object. @@ -676,7 +678,7 @@ class RenderClipRRect extends RenderProxyBox { } } -/// Clips its child using an oval +/// Clips its child using an oval. /// /// Inscribes an oval into its layout dimensions and prevents its child from /// painting outside that oval. @@ -717,16 +719,16 @@ class RenderClipOval extends _RenderCustomClip { } } -/// Where to paint a box decoration +/// Where to paint a box decoration. enum BoxDecorationPosition { - /// Paint the box decoration behind the children + /// Paint the box decoration behind the children. background, - /// Paint the box decoration in front of the children + /// Paint the box decoration in front of the children. foreground, } -/// Paints a [BoxDecoration] either before or after its child paints +/// Paints a [BoxDecoration] either before or after its child paints. class RenderDecoratedBox extends RenderProxyBox { RenderDecoratedBox({ @@ -740,7 +742,7 @@ class RenderDecoratedBox extends RenderProxyBox { assert(position != null); } - /// Where to paint the box decoration + /// Where to paint the box decoration. BoxDecorationPosition get position => _position; BoxDecorationPosition _position; void set position (BoxDecorationPosition newPosition) { @@ -750,7 +752,7 @@ class RenderDecoratedBox extends RenderProxyBox { markNeedsPaint(); } - /// What decoration to paint + /// What decoration to paint. BoxDecoration get decoration => _painter.decoration; void set decoration (BoxDecoration newDecoration) { assert(newDecoration != null); @@ -820,7 +822,7 @@ class RenderDecoratedBox extends RenderProxyBox { } } -/// Applies a transformation before painting its child +/// Applies a transformation before painting its child. class RenderTransform extends RenderProxyBox { RenderTransform({ Matrix4 transform, @@ -836,7 +838,7 @@ class RenderTransform extends RenderProxyBox { } /// The origin of the coordinate system (relative to the upper left corder of - /// this render object) in which to apply the matrix + /// this render object) in which to apply the matrix. /// /// Setting an origin is equivalent to conjugating the transform matrix by a /// translation. This property is provided just for convenience. @@ -866,7 +868,7 @@ class RenderTransform extends RenderProxyBox { // Note the lack of a getter for transform because Matrix4 is not immutable Matrix4 _transform; - /// The matrix to transform the child by during painting + /// The matrix to transform the child by during painting. void set transform(Matrix4 newTransform) { assert(newTransform != null); if (_transform == newTransform) @@ -875,37 +877,37 @@ class RenderTransform extends RenderProxyBox { markNeedsPaint(); } - /// Sets the transform to the identity matrix + /// Sets the transform to the identity matrix. void setIdentity() { _transform.setIdentity(); markNeedsPaint(); } - /// Concatenates a rotation about the x axis into the transform + /// Concatenates a rotation about the x axis into the transform. void rotateX(double radians) { _transform.rotateX(radians); markNeedsPaint(); } - /// Concatenates a rotation about the y axis into the transform + /// Concatenates a rotation about the y axis into the transform. void rotateY(double radians) { _transform.rotateY(radians); markNeedsPaint(); } - /// Concatenates a rotation about the z axis into the transform + /// Concatenates a rotation about the z axis into the transform. void rotateZ(double radians) { _transform.rotateZ(radians); markNeedsPaint(); } - /// Concatenates a translation by (x, y, z) into the transform + /// Concatenates a translation by (x, y, z) into the transform. void translate(x, [double y = 0.0, double z = 0.0]) { _transform.translate(x, y, z); markNeedsPaint(); } - /// Concatenates a scale into the transform + /// Concatenates a scale into the transform. void scale(x, [double y, double z]) { _transform.scale(x, y, z); markNeedsPaint(); @@ -963,13 +965,13 @@ class RenderTransform extends RenderProxyBox { } } -/// Called when a size changes +/// Called when a size changes. typedef void SizeChangedCallback(Size newSize); /// Calls [onSizeChanged] whenever the child's layout size changes /// -/// Note: Size observer calls its callback during layout, which means you cannot -/// dirty layout information during the callback. +/// Because size observer calls its callback during layout, you cannot modify +/// layout information during the callback. class RenderSizeObserver extends RenderProxyBox { RenderSizeObserver({ this.onSizeChanged, @@ -1007,13 +1009,13 @@ abstract class CustomPainter { /// current canvas and then paints its children. After painting its children, /// custom paint asks foregroundPainter to paint. The coodinate system of the /// canvas matches the coordinate system of the custom paint object. The -/// painters are expected to paint with in a rectangle starting at the origin +/// painters are expected to paint within a rectangle starting at the origin /// and encompassing a region of the given size. If the painters paints outside /// those bounds, there might be insufficient memory allocated to rasterize the /// painting commands and the resulting behavior is undefined. /// -/// Note: Custom paint calls its painters during paint, which means you cannot -/// dirty layout or paint information during the callback. +/// Because custom paint calls its painters during paint, you cannot dirty +/// layout or paint information during the callback. class RenderCustomPaint extends RenderProxyBox { RenderCustomPaint({ CustomPainter painter, diff --git a/packages/flutter/lib/src/rendering/shifted_box.dart b/packages/flutter/lib/src/rendering/shifted_box.dart index 15e60213eb..ba87eab8a6 100644 --- a/packages/flutter/lib/src/rendering/shifted_box.dart +++ b/packages/flutter/lib/src/rendering/shifted_box.dart @@ -72,15 +72,24 @@ abstract class RenderShiftedBox extends RenderBox with RenderObjectWithChildMixi } +/// Insets its child by the given padding. +/// +/// When passing layout constraints to its child, padding shrinks the +/// constraints by the given padding, causing the child to layout at a smaller +/// size. Padding then sizes itself to its child's size, inflated by the +/// padding, effectively creating empty space around the child. class RenderPadding extends RenderShiftedBox { - - RenderPadding({ EdgeDims padding, RenderBox child }) : super(child) { + RenderPadding({ + EdgeDims padding, + RenderBox child + }) : _padding = padding, super(child) { assert(padding != null); - this.padding = padding; + assert(padding.isNonNegative); } - EdgeDims _padding; + /// The amount to pad the child in each dimension. EdgeDims get padding => _padding; + EdgeDims _padding; void set padding (EdgeDims value) { assert(value != null); assert(value.isNonNegative); @@ -143,14 +152,12 @@ class RenderPadding extends RenderShiftedBox { } } +/// Aligns its child box within itself. +/// +/// For example, to align a box at the bottom right, you would pass this box a +/// tight constraint that is bigger than the child's natural size, +/// with horizontal and vertical set to 1.0. class RenderPositionedBox extends RenderShiftedBox { - - // This box aligns a child box within itself. It's only useful for - // children that don't always size to fit their parent. For example, - // to align a box at the bottom right, you would pass this box a - // tight constraint that is bigger than the child's natural size, - // with horizontal and vertical set to 1.0. - RenderPositionedBox({ RenderBox child, FractionalOffset alignment: const FractionalOffset(0.5, 0.5), @@ -160,9 +167,20 @@ class RenderPositionedBox extends RenderShiftedBox { _widthFactor = widthFactor, _heightFactor = heightFactor, super(child) { - assert(alignment != null); + assert(alignment != null && alignment.x != null && alignment.y != null); + assert(widthFactor == null || widthFactor >= 0.0); + assert(heightFactor == null || heightFactor >= 0.0); } + /// How to align the child. + /// + /// The x and y values of the alignment control the horizontal and vertical + /// alignment, respectively. An x value of 0.0 means that the left edge of + /// the child is aligned with the left edge of the parent whereas an x value + /// of 1.0 means that the right edge of the child is aligned with the right + /// edge of the parent. Other values interpolate (and extrapolate) linearly. + /// For example, a value of 0.5 means that the center of the child is aligned + /// with the center of the parent. FractionalOffset get alignment => _alignment; FractionalOffset _alignment; void set alignment (FractionalOffset newAlignment) { @@ -173,18 +191,26 @@ class RenderPositionedBox extends RenderShiftedBox { markNeedsLayout(); } - double _widthFactor; + /// If non-null, sets its width to the child's width multipled by this factor. + /// + /// Can be both greater and less than 1.0 but must be positive. double get widthFactor => _widthFactor; + double _widthFactor; void set widthFactor (double value) { + assert(value == null || value >= 0.0); if (_widthFactor == value) return; _widthFactor = value; markNeedsLayout(); } - double _heightFactor; + /// If non-null, sets its height to the child's height multipled by this factor. + /// + /// Can be both greater and less than 1.0 but must be positive. double get heightFactor => _heightFactor; + double _heightFactor; void set heightFactor (double value) { + assert(value == null || value >= 0.0); if (_heightFactor == value) return; _heightFactor = value; @@ -226,6 +252,12 @@ class OneChildLayoutDelegate { Point getPositionForChild(Size size, Size childSize) => Point.origin; } +/// Defers the layout of its single child to a delegate. +/// +/// The delegate can determine the layout constraints for the child and can +/// decide where to position the child. The delegate can also determine the size +/// of the parent, but the size of the parent cannot depend on the size of the +/// child. class RenderCustomOneChildLayoutBox extends RenderShiftedBox { RenderCustomOneChildLayoutBox({ RenderBox child, @@ -234,6 +266,7 @@ class RenderCustomOneChildLayoutBox extends RenderShiftedBox { assert(delegate != null); } + /// A delegate that controls this object's layout. OneChildLayoutDelegate get delegate => _delegate; OneChildLayoutDelegate _delegate; void set delegate (OneChildLayoutDelegate newDelegate) { diff --git a/packages/flutter/lib/src/rendering/viewport.dart b/packages/flutter/lib/src/rendering/viewport.dart index a0e3f12511..18157c68aa 100644 --- a/packages/flutter/lib/src/rendering/viewport.dart +++ b/packages/flutter/lib/src/rendering/viewport.dart @@ -21,13 +21,15 @@ enum ScrollDirection { both } -/// A render object that's bigger on the inside +/// A render object that's bigger on the inside. /// -/// A viewport is the core scrolling primitive in the render tree. The child of -/// a viewport can layout to a larger size than the viewport itself. If that -/// happens, only a portion of the child will be visible through the viewport. -/// The portiion of the child that is visible is controlled by the scroll -/// offset. +/// The child of a viewport can layout to a larger size than the viewport +/// itself. If that happens, only a portion of the child will be visible through +/// the viewport. The portion of the child that is visible is controlled by the +/// scroll offset. +/// +/// Viewport is the core scrolling primitive in the system, but it can be used +/// in other situations. class RenderViewport extends RenderBox with RenderObjectWithChildMixin { RenderViewport({ @@ -51,7 +53,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin _scrollOffset; @@ -64,7 +66,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin= 0.0 && opacity <= 1.0); } + /// The fraction to scale the child's alpha value. + /// + /// An opacity of 1.0 is fully opaque. An opacity of 0.0 is fully transparent + /// (i.e., invisible). final double opacity; RenderOpacity createRenderObject() => new RenderOpacity(opacity: opacity); @@ -119,6 +130,7 @@ class ShaderMask extends OneChildRenderObjectWidget { } } +/// Paints a [BoxDecoration] either before or after its child paints. class DecoratedBox extends OneChildRenderObjectWidget { DecoratedBox({ Key key, @@ -130,10 +142,13 @@ class DecoratedBox extends OneChildRenderObjectWidget { assert(position != null); } + /// What decoration to paint. final BoxDecoration decoration; + + /// Where to paint the box decoration. final BoxDecorationPosition position; - RenderObject createRenderObject() => new RenderDecoratedBox(decoration: decoration, position: position); + RenderDecoratedBox createRenderObject() => new RenderDecoratedBox(decoration: decoration, position: position); void updateRenderObject(RenderDecoratedBox renderObject, DecoratedBox oldWidget) { renderObject.decoration = decoration; @@ -141,11 +156,27 @@ class DecoratedBox extends OneChildRenderObjectWidget { } } +/// Delegates its painting. +/// +/// When asked to paint, custom paint first asks painter to paint with the +/// current canvas and then paints its children. After painting its children, +/// custom paint asks foregroundPainter to paint. The coodinate system of the +/// canvas matches the coordinate system of the custom paint object. The +/// painters are expected to paint within a rectangle starting at the origin +/// and encompassing a region of the given size. If the painters paints outside +/// those bounds, there might be insufficient memory allocated to rasterize the +/// painting commands and the resulting behavior is undefined. +/// +/// Because custom paint calls its painters during paint, you cannot dirty +/// layout or paint information during the callback. class CustomPaint extends OneChildRenderObjectWidget { CustomPaint({ Key key, this.painter, this.foregroundPainter, Widget child }) : super(key: key, child: child); + /// The painter that paints before the children. final CustomPainter painter; + + /// The painter that paints after the children. final CustomPainter foregroundPainter; RenderCustomPaint createRenderObject() => new RenderCustomPaint( @@ -164,9 +195,13 @@ class CustomPaint extends OneChildRenderObjectWidget { } } +/// Clips its child using a rectangle. +/// +/// Prevents its child from painting outside its bounds. class ClipRect extends OneChildRenderObjectWidget { ClipRect({ Key key, this.clipper, Widget child }) : super(key: key, child: child); + /// If non-null, determines which clip to use. final CustomClipper clipper; RenderClipRect createRenderObject() => new RenderClipRect(clipper: clipper); @@ -180,11 +215,25 @@ class ClipRect extends OneChildRenderObjectWidget { } } +/// Clips its child using a rounded rectangle. +/// +/// Creates a rounded rectangle from its layout dimensions and the given x and +/// y radius values and prevents its child from painting outside that rounded +/// rectangle. class ClipRRect extends OneChildRenderObjectWidget { ClipRRect({ Key key, this.xRadius, this.yRadius, Widget child }) : super(key: key, child: child); + /// The radius of the rounded corners in the horizontal direction in logical pixels. + /// + /// Values are clamped to be between zero and half the width of the render + /// object. final double xRadius; + + /// The radius of the rounded corners in the vertical direction in logical pixels. + /// + /// Values are clamped to be between zero and half the height of the render + /// object. final double yRadius; RenderClipRRect createRenderObject() => new RenderClipRRect(xRadius: xRadius, yRadius: yRadius); @@ -195,9 +244,14 @@ class ClipRRect extends OneChildRenderObjectWidget { } } +/// Clips its child using an oval. +/// +/// Inscribes an oval into its layout dimensions and prevents its child from +/// painting outside that oval. class ClipOval extends OneChildRenderObjectWidget { ClipOval({ Key key, this.clipper, Widget child }) : super(key: key, child: child); + /// If non-null, determines which clip to use. final CustomClipper clipper; RenderClipOval createRenderObject() => new RenderClipOval(clipper: clipper); @@ -214,14 +268,27 @@ class ClipOval extends OneChildRenderObjectWidget { // POSITIONING AND SIZING NODES +/// Applies a transformation before painting its child. class Transform extends OneChildRenderObjectWidget { Transform({ Key key, this.transform, this.origin, this.alignment, Widget child }) : super(key: key, child: child) { assert(transform != null); } + /// The matrix to transform the child by during painting. final Matrix4 transform; + + /// The origin of the coordinate system (relative to the upper left corder of + /// this render object) in which to apply the matrix. + /// + /// Setting an origin is equivalent to conjugating the transform matrix by a + /// translation. This property is provided just for convenience. final Offset origin; + + /// The alignment of the origin, relative to the size of the box. + /// + /// This is equivalent to setting an origin based on the size of the box. + /// If it is specificed at the same time as an offset, both are applied. final FractionalOffset alignment; RenderTransform createRenderObject() => new RenderTransform(transform: transform, origin: origin, alignment: alignment); @@ -233,12 +300,19 @@ class Transform extends OneChildRenderObjectWidget { } } +/// Insets its child by the given padding. +/// +/// When passing layout constraints to its child, padding shrinks the +/// constraints by the given padding, causing the child to layout at a smaller +/// size. Padding then sizes itself to its child's size, inflated by the +/// padding, effectively creating empty space around the child. class Padding extends OneChildRenderObjectWidget { Padding({ Key key, this.padding, Widget child }) : super(key: key, child: child) { assert(padding != null); } + /// The amount to pad the child in each dimension. final EdgeDims padding; RenderPadding createRenderObject() => new RenderPadding(padding: padding); @@ -248,6 +322,11 @@ class Padding extends OneChildRenderObjectWidget { } } +/// Aligns its child box within itself. +/// +/// For example, to align a box at the bottom right, you would pass this box a +/// tight constraint that is bigger than the child's natural size, +/// with horizontal and vertical set to 1.0. class Align extends OneChildRenderObjectWidget { Align({ Key key, @@ -255,10 +334,31 @@ class Align extends OneChildRenderObjectWidget { this.widthFactor, this.heightFactor, Widget child - }) : super(key: key, child: child); + }) : super(key: key, child: child) { + assert(alignment != null && alignment.x != null && alignment.y != null); + assert(widthFactor == null || widthFactor >= 0.0); + assert(heightFactor == null || heightFactor >= 0.0); + } + /// How to align the child. + /// + /// The x and y values of the alignment control the horizontal and vertical + /// alignment, respectively. An x value of 0.0 means that the left edge of + /// the child is aligned with the left edge of the parent whereas an x value + /// of 1.0 means that the right edge of the child is aligned with the right + /// edge of the parent. Other values interpolate (and extrapolate) linearly. + /// For example, a value of 0.5 means that the center of the child is aligned + /// with the center of the parent. final FractionalOffset alignment; + + /// If non-null, sets its width to the child's width multipled by this factor. + /// + /// Can be both greater and less than 1.0 but must be positive. final double widthFactor; + + /// If non-null, sets its height to the child's height multipled by this factor. + /// + /// Can be both greater and less than 1.0 but must be positive. final double heightFactor; RenderPositionedBox createRenderObject() => new RenderPositionedBox(alignment: alignment, widthFactor: widthFactor, heightFactor: heightFactor); @@ -270,11 +370,18 @@ class Align extends OneChildRenderObjectWidget { } } +/// Centers its child within itself. class Center extends Align { Center({ Key key, widthFactor, heightFactor, Widget child }) : super(key: key, widthFactor: widthFactor, heightFactor: heightFactor, child: child); } +/// Defers the layout of its single child to a delegate. +/// +/// The delegate can determine the layout constraints for the child and can +/// decide where to position the child. The delegate can also determine the size +/// of the parent, but the size of the parent cannot depend on the size of the +/// child. class CustomOneChildLayout extends OneChildRenderObjectWidget { CustomOneChildLayout({ Key key, @@ -304,6 +411,7 @@ class CustomOneChildLayout extends OneChildRenderObjectWidget { } } +/// Metadata for identifying children in a [CustomMultiChildLayout]. class LayoutId extends ParentDataWidget { LayoutId({ Key key, @@ -314,6 +422,7 @@ class LayoutId extends ParentDataWidget { assert(id != null); } + /// An object representing the identity of this child. final Object id; void debugValidateAncestor(Widget ancestor) { @@ -340,6 +449,12 @@ class LayoutId extends ParentDataWidget { } } +/// Defers the layout of multiple children to a delegate. +/// +/// The delegate can determine the layout constraints for each child and can +/// decide where to position each child. The delegate can also determine the +/// size of the parent, but the size of the parent cannot depend on the sizes of +/// the children. class CustomMultiChildLayout extends MultiChildRenderObjectWidget { CustomMultiChildLayout(List children, { Key key, @@ -349,6 +464,7 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget { assert(delegate != null); } + /// The delegate that controls the layout of the children. final MultiChildLayoutDelegate delegate; final Object token; @@ -363,11 +479,18 @@ class CustomMultiChildLayout extends MultiChildRenderObjectWidget { } } +/// A box with a specified size. +/// +/// Forces its child to have a specific width and/or height and sizes itself to +/// match the size of its child. class SizedBox extends OneChildRenderObjectWidget { SizedBox({ Key key, this.width, this.height, Widget child }) : super(key: key, child: child); + /// If non-null, requires the child to have exactly this width. final double width; + + /// If non-null, requires the child to have exactly this height. final double height; RenderConstrainedBox createRenderObject() => new RenderConstrainedBox( @@ -396,12 +519,18 @@ class SizedBox extends OneChildRenderObjectWidget { } } +/// Imposes additional constraints on its child. +/// +/// For example, if you wanted [child] to have a minimum height of 50.0 logical +/// pixels, you could use `const BoxConstraints(minHeight: 50.0)`` as the +/// [additionalConstraints]. class ConstrainedBox extends OneChildRenderObjectWidget { ConstrainedBox({ Key key, this.constraints, Widget child }) : super(key: key, child: child) { assert(constraints != null); } + /// The additional constraints to impose on the child. final BoxConstraints constraints; RenderConstrainedBox createRenderObject() => new RenderConstrainedBox(additionalConstraints: constraints); @@ -479,6 +608,9 @@ class SizedOverflowBox extends OneChildRenderObjectWidget { } } +/// Lays the child out as if it was in the tree, but without painting anything, +/// without making the child available for hit testing, and without taking any +/// room in the parent. class OffStage extends OneChildRenderObjectWidget { OffStage({ Key key, Widget child }) : super(key: key, child: child); @@ -506,11 +638,26 @@ class AspectRatio extends OneChildRenderObjectWidget { } } +/// Sizes its child to the child's intrinsic width. +/// +/// Sizes its child's width to the child's maximum intrinsic width. If +/// [stepWidth] is non-null, the child's width will be snapped to a multiple of +/// the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's height +/// will be snapped to a multiple of the [stepHeight]. +/// +/// This class is useful, for example, when unlimited width is available and +/// you would like a child that would otherwise attempt to expand infinitely to +/// instead size itself to a more reasonable width. +/// +/// This class is relatively expensive. Avoid using it where possible. class IntrinsicWidth extends OneChildRenderObjectWidget { IntrinsicWidth({ Key key, this.stepWidth, this.stepHeight, Widget child }) : super(key: key, child: child); + /// If non-null, force the child's width to be a multiple of this value. final double stepWidth; + + /// If non-null, force the child's height to be a multiple of this value. final double stepHeight; RenderIntrinsicWidth createRenderObject() => new RenderIntrinsicWidth(stepWidth: stepWidth, stepHeight: stepHeight); @@ -521,6 +668,13 @@ class IntrinsicWidth extends OneChildRenderObjectWidget { } } +/// Sizes its child to the child's intrinsic height. +/// +/// This class is useful, for example, when unlimited height is available and +/// you would like a child that would otherwise attempt to expand infinitely to +/// instead size itself to a more reasonable height. +/// +/// This class is relatively expensive. Avoid using it where possible. class IntrinsicHeight extends OneChildRenderObjectWidget { IntrinsicHeight({ Key key, Widget child }) : super(key: key, child: child); RenderIntrinsicHeight createRenderObject() => new RenderIntrinsicHeight(); @@ -544,6 +698,15 @@ class Baseline extends OneChildRenderObjectWidget { } } +/// A widget that's bigger on the inside. +/// +/// The child of a viewport can layout to a larger size than the viewport +/// itself. If that happens, only a portion of the child will be visible through +/// the viewport. The portion of the child that is visible is controlled by the +/// scroll offset. +/// +/// Viewport is the core scrolling primitive in the system, but it can be used +/// in other situations. class Viewport extends OneChildRenderObjectWidget { Viewport({ Key key, @@ -555,7 +718,16 @@ class Viewport extends OneChildRenderObjectWidget { assert(scrollOffset != null); } + /// The direction in which the child is permitted to be larger than the viewport + /// + /// If the viewport is scrollable in a particular direction (e.g., vertically), + /// the child is given layout constraints that are fully unconstrainted in + /// that direction (e.g., the child can be as tall as it wants). final ScrollDirection scrollDirection; + + /// The offset at which to paint the child. + /// + /// The offset can be non-zero only in the [scrollDirection]. final Offset scrollOffset; RenderViewport createRenderObject() => new RenderViewport(scrollDirection: scrollDirection, scrollOffset: scrollOffset); @@ -567,12 +739,17 @@ class Viewport extends OneChildRenderObjectWidget { } } +/// Calls [onSizeChanged] whenever the child's layout size changes +/// +/// Because size observer calls its callback during layout, you cannot modify +/// layout information during the callback. class SizeObserver extends OneChildRenderObjectWidget { SizeObserver({ Key key, this.onSizeChanged, Widget child }) : super(key: key, child: child) { assert(onSizeChanged != null); } + /// The callback to call whenever the child's layout size changes final SizeChangedCallback onSizeChanged; RenderSizeObserver createRenderObject() => new RenderSizeObserver(onSizeChanged: onSizeChanged);