Skip to content

F
Front-End
Commit 73e62d38 authored by Adam Barth's avatar Adam Barth
Browse files
Options

Merge pull request #779 from abarth/basic_docs 

Add some dartdoc to basic widgets
parents 429e17c5 069fc6dd
Hide whitespace changes
Inline Side-by-side
Showing with 298 additions and 75 deletions
packages/flutter/lib/src/rendering/custom_layout.dart
View file @ 73e62d38
......@@ -6,6 +6,7 @@ import 'box.dart';
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 @@ class MultiChildLayoutParentData extends ContainerBoxParentDataMixin<RenderBox>
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 @@ 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<RenderBox, MultiChildLayoutParentData>,
RenderBoxContainerDefaultsMixin<RenderBox, MultiChildLayoutParentData> {
......@@ -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) {
......
packages/flutter/lib/src/rendering/proxy_box.dart
View file @ 73e62d38
......@@ -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<RenderBox
}
}
/// 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 @@ class RenderFractionallySizedBox extends RenderProxyBox {
}
}
/// 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 @@ class RenderAspectRatio extends RenderProxyBox {
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 @@ class RenderAspectRatio extends RenderProxyBox {
}
}
/// 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 @@ class RenderIntrinsicWidth extends RenderProxyBox {
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 @@ 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<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 @@ abstract class _RenderCustomClip<T> extends RenderProxyBox {
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 @@ abstract class _RenderCustomClip<T> 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<Rect> {
......@@ -624,7 +626,7 @@ class RenderClipRect extends _RenderCustomClip<Rect> {
}
}
/// 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<Rect> {
}
}
/// 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,
......
packages/flutter/lib/src/rendering/shifted_box.dart
View file @ 73e62d38
......@@ -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) {
......
packages/flutter/lib/src/rendering/viewport.dart
View file @ 73e62d38
......@@ -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<RenderBox> {
RenderViewport({
......@@ -51,7 +53,7 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
}
}
/// 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 @@ class RenderViewport extends RenderBox with RenderObjectWithChildMixin<RenderBox
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
......
packages/flutter/lib/src/widgets/basic.dart
View file @ 73e62d38
......@@ -72,12 +72,23 @@ export 'package:flutter/rendering.dart' show
// 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 @@ 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<Rect> 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<Rect> 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<Widget> 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);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

HIAST - GitLab