Merge pull request #779 from abarth/basic_docs
Add some dartdoc to basic widgets
diff --git a/packages/flutter/lib/src/rendering/custom_layout.dart b/packages/flutter/lib/src/rendering/custom_layout.dart
index b8ea63f..5c04b61 100644
--- a/packages/flutter/lib/src/rendering/custom_layout.dart
+++ b/packages/flutter/lib/src/rendering/custom_layout.dart
@@ -6,6 +6,7 @@
import 'object.dart';
class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox> {
+ /// An object representing the identity of this child.
Object id;
void merge(MultiChildLayoutParentData other) {
@@ -17,6 +18,7 @@
String toString() => '${super.toString()}; id=$id';
}
+/// A delegate that controls the layout of multiple children.
abstract class MultiChildLayoutDelegate {
Map<Object, RenderBox> _idToChild;
Set<RenderBox> _debugChildrenNeedingLayout;
@@ -94,6 +96,12 @@
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<RenderBox, MultiChildLayoutParentData>,
RenderBoxContainerDefaultsMixin<RenderBox, MultiChildLayoutParentData> {
@@ -110,6 +118,7 @@
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 ccb2d28..031a1e8 100644
--- a/packages/flutter/lib/src/rendering/proxy_box.dart
+++ b/packages/flutter/lib/src/rendering/proxy_box.dart
@@ -21,7 +21,7 @@
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 @@
}
}
-/// A render object that imposes additional constraints on its child
+/// Imposes additional constraints on its child.
///
/// A render constrained box proxies most functions in the render box protocol
/// to its child, except that when laying out its child, it tightens the
/// constraints provided by its parent by enforcing the [additionalConstraints]
/// as well.
///
-/// For example, if you wanted [child] to have a minimum height, you could use
-/// `const BoxConstraints(minHeight: 50.0)`` as the [additionalConstraints].
+/// 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 RenderConstrainedBox extends RenderProxyBox {
RenderConstrainedBox({
RenderBox child,
@@ -260,7 +261,7 @@
}
}
-/// Forces child to layout at a specific aspect ratio
+/// Forces child to layout at a specific aspect ratio.
///
/// The width of this render object is the largest width permited by the layout
/// constraints. The height of the render object is determined by applying the
@@ -284,7 +285,7 @@
assert(_aspectRatio != null);
}
- /// The aspect ratio to use when computing the height from the width
+ /// The aspect ratio to use when computing the height from the width.
///
/// The aspect ratio is expressed as a ratio of width to height. For example,
/// a 16:9 width:height aspect ratio would have a value of 16.0/9.0.
@@ -329,18 +330,18 @@
}
}
-/// Sizes its child to the child's intrinsic width
+/// Sizes its child to the child's intrinsic width.
///
-/// This class will size 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].
+/// 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.
///
-/// Note: This class is relatively expensive. Avoid using it where possible.
+/// This class is relatively expensive. Avoid using it where possible.
class RenderIntrinsicWidth extends RenderProxyBox {
RenderIntrinsicWidth({
@@ -349,7 +350,7 @@
RenderBox child
}) : _stepWidth = stepWidth, _stepHeight = stepHeight, super(child);
- /// If non-null, force the child's width to be a multiple of this value
+ /// If non-null, force the child's width to be a multiple of this value.
double get stepWidth => _stepWidth;
double _stepWidth;
void set stepWidth(double newStepWidth) {
@@ -359,7 +360,7 @@
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 @@
}
}
-/// 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 @@
}
-/// 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 @@
}
}
+/// A class that provides custom clips.
abstract class CustomClipper<T> {
+ /// 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 @@
CustomClipper<T> clipper
}) : _clipper = clipper, super(child);
+ /// If non-null, determines which clip to use on the child.
CustomClipper<T> get clipper => _clipper;
CustomClipper<T> _clipper;
void set clipper (CustomClipper<T> newClipper) {
@@ -598,7 +600,7 @@
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<Rect> {
@@ -624,7 +626,7 @@
}
}
-/// 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 @@
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 @@
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 @@
}
}
-/// 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 @@
}
}
-/// 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 @@
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 @@
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 @@
}
}
-/// 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 @@
}
/// 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 @@
// 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 @@
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 @@
}
}
-/// 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 @@
/// 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 15e6021..ba87eab 100644
--- a/packages/flutter/lib/src/rendering/shifted_box.dart
+++ b/packages/flutter/lib/src/rendering/shifted_box.dart
@@ -72,15 +72,24 @@
}
+/// 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 @@
}
}
+/// 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 @@
_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 @@
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 @@
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 @@
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 a0e3f12..18157c6 100644
--- a/packages/flutter/lib/src/rendering/viewport.dart
+++ b/packages/flutter/lib/src/rendering/viewport.dart
@@ -21,13 +21,15 @@
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<RenderBox> {
RenderViewport({
@@ -51,7 +53,7 @@
}
}
- /// The offset at which to paint the child
+ /// The offset at which to paint the child.
///
/// The offset can be non-zero only in the [scrollDirection].
Offset get scrollOffset => _scrollOffset;
@@ -64,7 +66,7 @@
markNeedsPaint();
}
- /// In which direction the child is permitted to be larger than the viewport
+ /// 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
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index d399fda..697c4a8 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -72,12 +72,23 @@
// PAINTING NODES
+/// 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.
+///
+/// This class is relatively expensive because it requires painting the child
+/// into an intermediate buffer.
class Opacity extends OneChildRenderObjectWidget {
Opacity({ Key key, this.opacity, Widget child })
: super(key: key, child: child) {
assert(opacity >= 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 @@
}
}
+/// Paints a [BoxDecoration] either before or after its child paints.
class DecoratedBox extends OneChildRenderObjectWidget {
DecoratedBox({
Key key,
@@ -130,10 +142,13 @@
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 @@
}
}
+/// 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 @@
}
}
+/// 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<Rect> clipper;
RenderClipRect createRenderObject() => new RenderClipRect(clipper: clipper);
@@ -180,11 +215,25 @@
}
}
+/// 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 @@
}
}
+/// 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<Rect> clipper;
RenderClipOval createRenderObject() => new RenderClipOval(clipper: clipper);
@@ -214,14 +268,27 @@
// 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 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
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 @@
}
}
+/// 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 @@
}
}
+/// Metadata for identifying children in a [CustomMultiChildLayout].
class LayoutId extends ParentDataWidget {
LayoutId({
Key key,
@@ -314,6 +422,7 @@
assert(id != null);
}
+ /// An object representing the identity of this child.
final Object id;
void debugValidateAncestor(Widget ancestor) {
@@ -340,6 +449,12 @@
}
}
+/// 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<Widget> children, {
Key key,
@@ -349,6 +464,7 @@
assert(delegate != null);
}
+ /// The delegate that controls the layout of the children.
final MultiChildLayoutDelegate delegate;
final Object token;
@@ -363,11 +479,18 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
}
}
+/// 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 @@
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 @@
}
}
+/// 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);
