diff --git a/packages/flutter/lib/src/rendering/custom_layout.dart b/packages/flutter/lib/src/rendering/custom_layout.dart index 38c86d5b29..6c192e264c 100644 --- a/packages/flutter/lib/src/rendering/custom_layout.dart +++ b/packages/flutter/lib/src/rendering/custom_layout.dart @@ -23,7 +23,7 @@ abstract class MultiChildLayoutDelegate { Map _idToChild; Set _debugChildrenNeedingLayout; - /// Returns the size of this object given the incomming constraints. + /// Returns the size of this object given the incoming constraints. /// The size cannot reflect the instrinsic sizes of the children. /// If this layout has a fixed width or height the returned size /// can reflect that. diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 506778c2fc..bbb60e033f 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -164,13 +164,15 @@ class RenderConstrainedBox extends RenderProxyBox { } } -/// A render object that, for both width and height, imposes a tight constraint -/// on its child that is a multiple (typically less than 1.0) of the maximum -/// constraint it received from its parent on that axis. If the factor for a -/// given axis is null, then the constraints from the parent are just passed -/// through instead. +/// Sizes itself to a fraction of the total available space. /// -/// It then tries to size itself the size of its child. +/// For both its width and width height, this render object imposes a tight +/// constraint on its child that is a multiple (typically less than 1.0) of the +/// maximum constraint it received from its parent on that axis. If the factor +/// for a given axis is null, then the constraints from the parent are just +/// passed through instead. +/// +/// It then tries to size itself t the size of its child. class RenderFractionallySizedBox extends RenderProxyBox { RenderFractionallySizedBox({ RenderBox child, @@ -181,9 +183,11 @@ class RenderFractionallySizedBox extends RenderProxyBox { assert(_heightFactor == null || _heightFactor >= 0.0); } - /// The multiple to apply to the incoming maximum width constraint to use as - /// the tight width constraint for the child, or null to pass through the - /// constraints given by the parent. + /// If non-null, the factor of the incoming width to use. + /// + /// If non-null, the child is given a tight width constraint that is the max + /// incoming width constraint multipled by this factor. If null, the child is + /// given the incoming width constraings. double get widthFactor => _widthFactor; double _widthFactor; void set widthFactor (double value) { @@ -194,9 +198,11 @@ class RenderFractionallySizedBox extends RenderProxyBox { markNeedsLayout(); } - /// The multiple to apply to the incoming maximum height constraint to use as - /// the tight height constraint for the child, or null to pass through the - /// constraints given by the parent. + /// If non-null, the factor of the incoming height to use. + /// + /// If non-null, the child is given a tight height constraint that is the max + /// incoming width constraint multipled by this factor. If null, the child is + /// given the incoming width constraings. double get heightFactor => _heightFactor; double _heightFactor; void set heightFactor (double value) { diff --git a/packages/flutter/lib/src/rendering/shifted_box.dart b/packages/flutter/lib/src/rendering/shifted_box.dart index 624f4dbc87..66d56c6eeb 100644 --- a/packages/flutter/lib/src/rendering/shifted_box.dart +++ b/packages/flutter/lib/src/rendering/shifted_box.dart @@ -249,10 +249,10 @@ class RenderPositionedBox extends RenderShiftedBox { /// A delegate for computing the layout of a render object with a single child. class OneChildLayoutDelegate { - /// Returns the size of this object given the incomming constraints. + /// Returns the size of this object given the incoming constraints. Size getSize(BoxConstraints constraints) => constraints.biggest; - /// Returns the box constraints for the child given the incomming constraints. + /// Returns the box constraints for the child given the incoming constraints. BoxConstraints getConstraintsForChild(BoxConstraints constraints) => constraints; /// Returns the position where the child should be placed given the size of this object and the size of the child. @@ -325,6 +325,7 @@ class RenderCustomOneChildLayoutBox extends RenderShiftedBox { } } +/// Positions its child vertically according to the child's baseline. class RenderBaseline extends RenderShiftedBox { RenderBaseline({ @@ -338,8 +339,10 @@ class RenderBaseline extends RenderShiftedBox { assert(baselineType != null); } - double _baseline; + /// The number of logical pixels from the top of this box at which to position + /// the child's baseline. double get baseline => _baseline; + double _baseline; void set baseline (double value) { assert(value != null); if (_baseline == value) @@ -348,8 +351,9 @@ class RenderBaseline extends RenderShiftedBox { markNeedsLayout(); } - TextBaseline _baselineType; + /// The type of baseline to use for positioning the child. TextBaseline get baselineType => _baselineType; + TextBaseline _baselineType; void set baselineType (TextBaseline value) { assert(value != null); if (_baselineType == value) diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 3cdbf59ffe..6ba428a8b1 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -126,7 +126,9 @@ class ShaderMask extends OneChildRenderObjectWidget { } } -/// Paints a [BoxDecoration] either before or after its child paints. +/// Paints a [Decoration] either before or after its child paints. +/// +/// Commonly used with [BoxDecoration]. class DecoratedBox extends OneChildRenderObjectWidget { DecoratedBox({ Key key, @@ -139,6 +141,8 @@ class DecoratedBox extends OneChildRenderObjectWidget { } /// What decoration to paint. + /// + /// Commonly a [BoxDecoration]. final Decoration decoration; /// Where to paint the box decoration. @@ -541,11 +545,23 @@ class ConstrainedBox extends OneChildRenderObjectWidget { } } +/// Sizes itself to a fraction of the total available space. +/// +/// See [RenderFractionallySizedBox] for details. class FractionallySizedBox extends OneChildRenderObjectWidget { FractionallySizedBox({ Key key, this.width, this.height, Widget child }) : super(key: key, child: child); + /// If non-null, the factor of the incoming width to use. + /// + /// If non-null, the child is given a tight width constraint that is the max + /// incoming width constraint multipled by this factor. final double width; + + /// If non-null, the factor of the incoming height to use. + /// + /// If non-null, the child is given a tight height constraint that is the max + /// incoming height constraint multipled by this factor. final double height; RenderFractionallySizedBox createRenderObject() => new RenderFractionallySizedBox( @@ -567,13 +583,28 @@ class FractionallySizedBox extends OneChildRenderObjectWidget { } } +/// A render object that imposes different constraints on its child than it gets +/// from its parent, possibly allowing the child to overflow the parent. +/// +/// See [RenderOverflowBox] for details. class OverflowBox extends OneChildRenderObjectWidget { OverflowBox({ Key key, this.minWidth, this.maxWidth, this.minHeight, this.maxHeight, Widget child }) : super(key: key, child: child); + /// The minimum width constraint to give the child. Set this to null (the + /// default) to use the constraint from the parent instead. final double minWidth; + + /// The maximum width constraint to give the child. Set this to null (the + /// default) to use the constraint from the parent instead. final double maxWidth; + + /// The minimum height constraint to give the child. Set this to null (the + /// default) to use the constraint from the parent instead. final double minHeight; + + /// The maximum height constraint to give the child. Set this to null (the + /// default) to use the constraint from the parent instead. final double maxHeight; RenderOverflowBox createRenderObject() => new RenderOverflowBox( @@ -614,12 +645,19 @@ class OffStage extends OneChildRenderObjectWidget { RenderOffStage createRenderObject() => new RenderOffStage(); } +/// Forces child to layout at a specific aspect ratio. +/// +/// See [RenderAspectRatio] for details. class AspectRatio extends OneChildRenderObjectWidget { AspectRatio({ Key key, this.aspectRatio, Widget child }) : super(key: key, child: child) { assert(aspectRatio != null); } + /// 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. final double aspectRatio; RenderAspectRatio createRenderObject() => new RenderAspectRatio(aspectRatio: aspectRatio); @@ -676,6 +714,7 @@ class IntrinsicHeight extends OneChildRenderObjectWidget { RenderIntrinsicHeight createRenderObject() => new RenderIntrinsicHeight(); } +/// Positions its child vertically according to the child's baseline. class Baseline extends OneChildRenderObjectWidget { Baseline({ Key key, this.baseline, this.baselineType: TextBaseline.alphabetic, Widget child }) : super(key: key, child: child) { @@ -683,7 +722,11 @@ class Baseline extends OneChildRenderObjectWidget { assert(baselineType != null); } - final double baseline; // in pixels + /// The number of logical pixels from the top of this box at which to position + /// the child's baseline. + final double baseline; + + /// The type of baseline to use for positioning the child. final TextBaseline baselineType; RenderBaseline createRenderObject() => new RenderBaseline(baseline: baseline, baselineType: baselineType); @@ -760,10 +803,10 @@ class SizeObserver extends OneChildRenderObjectWidget { } -// CONVENIENCE CLASS TO COMBINE COMMON PAINTING, POSITIONING, AND SIZING NODES +// CONTAINER +/// A convenience widget that combines common painting, positioning, and sizing widgets. class Container extends StatelessComponent { - Container({ Key key, this.child, @@ -879,12 +922,17 @@ class Container extends StatelessComponent { if (height != null) description.add('height: $height'); } - } // LAYOUT NODES +/// Uses the block layout algorithm for its children. +/// +/// This widget is rarely used directly. Instead, consider using [Block], which +/// combines the block layout algorithm with scrolling behavior. +/// +/// For details about the block layout algorithm, see [RenderBlockBase]. class BlockBody extends MultiChildRenderObjectWidget { BlockBody(List children, { Key key, @@ -893,6 +941,7 @@ class BlockBody extends MultiChildRenderObjectWidget { assert(direction != null); } + /// The direction to use as the main axis. final BlockDirection direction; RenderBlock createRenderObject() => new RenderBlock(direction: direction); @@ -1183,8 +1232,12 @@ class Flexible extends ParentDataWidget { } } -class Paragraph extends LeafRenderObjectWidget { - Paragraph({ Key key, this.text }) : super(key: key) { +/// A raw paragraph of text. +/// +/// This class is rarely used directly. Instead, consider using [Text], which +/// integrates with [DefaultTextStyle]. +class RawText extends LeafRenderObjectWidget { + RawText({ Key key, this.text }) : super(key: key) { assert(text != null); } @@ -1192,19 +1245,26 @@ class Paragraph extends LeafRenderObjectWidget { RenderParagraph createRenderObject() => new RenderParagraph(text); - void updateRenderObject(RenderParagraph renderObject, Paragraph oldWidget) { + void updateRenderObject(RenderParagraph renderObject, RawText oldWidget) { renderObject.text = text; } } +/// A convience widget for paragraphs of text with heterogeneous style. +/// +/// The elements paramter is a recusrive list of lists that matches the +/// following grammar: +/// +/// `elements ::= "string" | [ *]`` +/// +/// Where "string" is text to display and text-style is an instance of +/// TextStyle. The text-style applies to all of the elements that follow. class StyledText extends StatelessComponent { - // elements ::= "string" | [ *] - // Where "string" is text to display and text-style is an instance of - // TextStyle. The text-style applies to all of the elements that follow. StyledText({ this.elements, Key key }) : super(key: key) { assert(_toSpan(elements) != null); } + /// The recursive list of lists that describes the text and style to paint. final dynamic elements; TextSpan _toSpan(dynamic element) { @@ -1220,10 +1280,11 @@ class StyledText extends StatelessComponent { } Widget build(BuildContext context) { - return new Paragraph(text: _toSpan(elements)); + return new RawText(text: _toSpan(elements)); } } +/// The text style to apply to descendant [Text] widgets without explicit style. class DefaultTextStyle extends InheritedWidget { DefaultTextStyle({ Key key, @@ -1234,8 +1295,10 @@ class DefaultTextStyle extends InheritedWidget { assert(child != null); } + /// The text style to apply. final TextStyle style; + /// The closest instance of this class that encloses the given context. static TextStyle of(BuildContext context) { DefaultTextStyle result = context.inheritFromWidgetOfType(DefaultTextStyle); return result?.style; @@ -1249,12 +1312,23 @@ class DefaultTextStyle extends InheritedWidget { } } +/// A run of text. +/// +/// By default, the text will be styled using the closest enclosing +/// [DefaultTextStyle]. class Text extends StatelessComponent { Text(this.data, { Key key, this.style }) : super(key: key) { assert(data != null); } + /// The text to display. final String data; + + /// If non-null, the style to use for this text. + /// + /// If the style's "inherit" property is true, the style will be merged with + /// the closest enclosing [DefaultTextStyle]. Otherwise, the style will + /// replace the closest enclosing [DefaultTextStyle]. final TextStyle style; Widget build(BuildContext context) { @@ -1267,7 +1341,7 @@ class Text extends StatelessComponent { } if (combinedStyle != null) text = new StyledTextSpan(combinedStyle, [text]); - return new Paragraph(text: text); + return new RawText(text: text); } void debugFillDescription(List description) { diff --git a/packages/flutter/lib/src/widgets/pageable_list.dart b/packages/flutter/lib/src/widgets/pageable_list.dart index 59a52c6693..0b9ed3da13 100644 --- a/packages/flutter/lib/src/widgets/pageable_list.dart +++ b/packages/flutter/lib/src/widgets/pageable_list.dart @@ -14,7 +14,11 @@ import 'framework.dart'; import 'homogeneous_viewport.dart'; import 'scrollable.dart'; -enum ItemsSnapAlignment { item, adjacentItem } +/// Controls what alignment items use when settling. +enum ItemsSnapAlignment { + item, + adjacentItem +} typedef void PageChangedCallback(int newPage);