Complete dartdocs for rendering.dart (#4316)

All of the public APIs in rendering.dart now have dartdocs.

packages/flutter/lib/src/rendering/layer.dart

@@ -118,6 +118,9 @@ class PictureLayer extends Layer {
 
 /// (mojo-only) A layer that represents content from another process.
 class ChildSceneLayer extends Layer {
+  /// Creates a layer that displays content rendered by another process.
+  ///
+  /// All of the arguments must not be null.
   ChildSceneLayer({
     this.offset,
     this.devicePixelRatio,
@@ -126,10 +129,19 @@ class ChildSceneLayer extends Layer {
     this.sceneToken
   });
 
+  /// Offset from parent in the parent's coordinate system.
   Offset offset;
+
+  /// The number of physical pixels the child should produce for each logical pixel.
   double devicePixelRatio;
+
+  /// The horizontal extent of the child, in physical pixels.
   int physicalWidth;
+
+  /// The vertical extent of the child, in physical pixels.
   int physicalHeight;
+
+  /// The composited scene that will contain the content rendered by the child.
   mojom.SceneToken sceneToken;
 
   @override

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -1988,6 +1988,9 @@ class RenderMetaData extends RenderProxyBoxWithHitTestBehavior {
 /// Listens for the specified gestures from the semantics server (e.g.
 /// an accessibility tool).
 class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticActionHandler {
+  /// Creates a render object that listens for specific semantic gestures.
+  ///
+  /// The [scrollFactor] argument must not be null.
   RenderSemanticsGestureHandler({
     RenderBox child,
     GestureTapCallback onTap,
@@ -2001,6 +2004,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
        _onVerticalDragUpdate = onVerticalDragUpdate,
        super(child);
 
+   /// Called when the user taps on the render object.
   GestureTapCallback get onTap => _onTap;
   GestureTapCallback _onTap;
   set onTap(GestureTapCallback value) {
@@ -2013,6 +2017,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user presses on the render object for a long period of time.
   GestureLongPressCallback get onLongPress => _onLongPress;
   GestureLongPressCallback _onLongPress;
   set onLongPress(GestureLongPressCallback value) {
@@ -2025,6 +2030,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user scrolls to the left or to the right.
   GestureDragUpdateCallback get onHorizontalDragUpdate => _onHorizontalDragUpdate;
   GestureDragUpdateCallback _onHorizontalDragUpdate;
   set onHorizontalDragUpdate(GestureDragUpdateCallback value) {
@@ -2037,6 +2043,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
       markNeedsSemanticsUpdate(onlyChanges: hasSemantics == didHaveSemantics);
   }
 
+  /// Called when the user scrolls up or down.
   GestureDragUpdateCallback get onVerticalDragUpdate => _onVerticalDragUpdate;
   GestureDragUpdateCallback _onVerticalDragUpdate;
   set onVerticalDragUpdate(GestureDragUpdateCallback value) {
@@ -2113,8 +2120,11 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
   }
 }
 
-/// Add annotations to the SemanticsNode for this subtree.
+/// Add annotations to the [SemanticsNode] for this subtree.
 class RenderSemanticAnnotations extends RenderProxyBox {
+  /// Creates a render object that attaches a semantic annotation.
+  ///
+  /// The [container] argument must not be null.
   RenderSemanticAnnotations({
     RenderBox child,
     bool container: false,
@@ -2197,6 +2207,7 @@ class RenderSemanticAnnotations extends RenderProxyBox {
 /// form part of a single conceptual widget, e.g. a checkbox, a label,
 /// and the gesture detector that goes with them.
 class RenderMergeSemantics extends RenderProxyBox {
+  /// Creates a render object that merges the semantics from its descendants.
   RenderMergeSemantics({ RenderBox child }) : super(child);
 
   @override
@@ -2210,6 +2221,7 @@ class RenderMergeSemantics extends RenderProxyBox {
 /// Useful e.g. for hiding text that is redundant with other text next
 /// to it (e.g. text included only for the visual effect).
 class RenderExcludeSemantics extends RenderProxyBox {
+  /// Creates a render object that ignores the semantics of its subtree.
   RenderExcludeSemantics({ RenderBox child }) : super(child);
 
   @override

packages/flutter/lib/src/rendering/stack.dart

@@ -5,6 +5,8 @@
 import 'dart:math' as math;
 import 'dart:ui' show lerpDouble, hashValues;
 
+import 'package:meta/meta.dart';
+
 import 'box.dart';
 import 'object.dart';
 
@@ -197,10 +199,50 @@ class StackParentData extends ContainerBoxParentDataMixin<RenderBox> {
   }
 }
 
-abstract class RenderStackBase extends RenderBox
+/// Implements the stack layout algorithm
+///
+/// In a stack layout, the children are positioned on top of each other in the
+/// order in which they appear in the child list. First, the non-positioned
+/// children (those with null values for top, right, bottom, and left) are
+/// laid out and initially placed in the upper-left corner of the stack. The
+/// stack is then sized to enclose all of the non-positioned children. If there
+/// are no non-positioned children, the stack becomes as large as possible.
+///
+/// The final location of non-positioned children is determined by the alignment
+/// parameter. The left of each non-positioned child becomes the
+/// difference between the child's width and the stack's width scaled by
+/// alignment.x. The top of each non-positioned child is computed
+/// similarly and scaled by alignment.y. So if the alignment x and y properties
+/// are 0.0 (the default) then the non-positioned children remain in the
+/// upper-left corner. If the alignment x and y properties are 0.5 then the
+/// non-positioned children are centered within the stack.
+///
+/// Next, the positioned children are laid out. If a child has top and bottom
+/// values that are both non-null, the child is given a fixed height determined
+/// by subtracting the sum of the top and bottom values from the height of the stack.
+/// Similarly, if the child has right and left values that are both non-null,
+/// the child is given a fixed width derived from the stack's width.
+/// Otherwise, the child is given unbounded constraints in the non-fixed dimensions.
+///
+/// Once the child is laid out, the stack positions the child
+/// according to the top, right, bottom, and left properties of their
+/// [StackParentData]. For example, if the bottom value is 10.0, the
+/// bottom edge of the child will be inset 10.0 pixels from the bottom
+/// edge of the stack. If the child extends beyond the bounds of the
+/// stack, the stack will clip the child's painting to the bounds of
+/// the stack.
+///
+/// See also:
+///
+///  * [RenderFlow]
+class RenderStack extends RenderBox
     with ContainerRenderObjectMixin<RenderBox, StackParentData>,
          RenderBoxContainerDefaultsMixin<RenderBox, StackParentData> {
-  RenderStackBase({
+  /// Creates a stack render object.
+  ///
+  /// By default, the non-positioned children of the stack are aligned by their
+  /// top left corners.
+  RenderStack({
     List<RenderBox> children,
     FractionalOffset alignment: FractionalOffset.topLeft
   }) : _alignment = alignment {
@@ -215,6 +257,12 @@ abstract class RenderStackBase extends RenderBox
       child.parentData = new StackParentData();
   }
 
+  /// How to align the non-positioned children in the stack.
+  ///
+  /// The non-positioned children are placed relative to each other such that
+  /// the points determined by [alignment] are co-located. For example, if the
+  /// [alignment] is [FractionalOffset.topLeft], then the top left corner of
+  /// each non-positioned child will be located at the same global coordinate.
   FractionalOffset get alignment => _alignment;
   FractionalOffset _alignment;
   set alignment (FractionalOffset value) {
@@ -350,7 +398,14 @@ abstract class RenderStackBase extends RenderBox
     return defaultHitTestChildren(result, position: position);
   }
 
-  void paintStack(PaintingContext context, Offset offset);
+  /// Override in subclasses to customize how the stack paints.
+  ///
+  /// By default, the stack uses [defaultPaint]. This function is called by
+  /// [paint] after potentially applying a clip to contain visual overflow.
+  @protected
+  void paintStack(PaintingContext context, Offset offset) {
+    defaultPaint(context, offset);
+  }
 
   @override
   void paint(PaintingContext context, Offset offset) {
@@ -365,63 +420,15 @@ abstract class RenderStackBase extends RenderBox
   Rect describeApproximatePaintClip(RenderObject child) => _hasVisualOverflow ? Point.origin & size : null;
 }
 
-/// Implements the stack layout algorithm
-///
-/// In a stack layout, the children are positioned on top of each other in the
-/// order in which they appear in the child list. First, the non-positioned
-/// children (those with null values for top, right, bottom, and left) are
-/// laid out and initially placed in the upper-left corner of the stack. The
-/// stack is then sized to enclose all of the non-positioned children. If there
-/// are no non-positioned children, the stack becomes as large as possible.
-///
-/// The final location of non-positioned children is determined by the alignment
-/// parameter. The left of each non-positioned child becomes the
-/// difference between the child's width and the stack's width scaled by
-/// alignment.x. The top of each non-positioned child is computed
-/// similarly and scaled by alignment.y. So if the alignment x and y properties
-/// are 0.0 (the default) then the non-positioned children remain in the
-/// upper-left corner. If the alignment x and y properties are 0.5 then the
-/// non-positioned children are centered within the stack.
-///
-/// Next, the positioned children are laid out. If a child has top and bottom
-/// values that are both non-null, the child is given a fixed height determined
-/// by subtracting the sum of the top and bottom values from the height of the stack.
-/// Similarly, if the child has right and left values that are both non-null,
-/// the child is given a fixed width derived from the stack's width.
-/// Otherwise, the child is given unbounded constraints in the non-fixed dimensions.
-///
-/// Once the child is laid out, the stack positions the child
-/// according to the top, right, bottom, and left properties of their
-/// [StackParentData]. For example, if the bottom value is 10.0, the
-/// bottom edge of the child will be inset 10.0 pixels from the bottom
-/// edge of the stack. If the child extends beyond the bounds of the
-/// stack, the stack will clip the child's painting to the bounds of
-/// the stack.
-///
-/// See also:
-///
-///  * [RenderFlow]
-class RenderStack extends RenderStackBase {
-  RenderStack({
-    List<RenderBox> children,
-    FractionalOffset alignment: FractionalOffset.topLeft
-  }) : super(
-   children: children,
-   alignment: alignment
- );
-
-  @override
-  void paintStack(PaintingContext context, Offset offset) {
-    defaultPaint(context, offset);
-  }
-}
-
 /// Implements the same layout algorithm as RenderStack but only paints the child
 /// specified by index.
 ///
 /// Although only one child is displayed, the cost of the layout algorithm is
 /// still O(N), like an ordinary stack.
-class RenderIndexedStack extends RenderStackBase {
+class RenderIndexedStack extends RenderStack {
+  /// Creates a stack render object that paints a single child.
+  ///
+  /// The [index] argument must not be null.
   RenderIndexedStack({
     List<RenderBox> children,
     FractionalOffset alignment: FractionalOffset.topLeft,
@@ -433,6 +440,7 @@ class RenderIndexedStack extends RenderStackBase {
     assert(index != null);
   }
 
+  /// The index of the child to show.
   int get index => _index;
   int _index;
   set index (int value) {

packages/flutter/lib/src/rendering/viewport.dart

@@ -83,6 +83,12 @@ class ViewportDimensions {
 /// have a child model. See [RenderViewport] for a viewport with a single child
 /// and [RenderVirtualViewport] for a viewport with multiple children.
 class RenderViewportBase extends RenderBox {
+  /// Initializes fields for subclasses.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
+  ///
+  /// This constructor uses positional arguments rather than named arguments to
+  /// work around limitations of mixins.
   RenderViewportBase(
     Offset paintOffset,
     Axis mainAxis,
@@ -149,6 +155,7 @@ class RenderViewportBase extends RenderBox {
     markNeedsSemanticsUpdate();
   }
 
+  /// The interior and exterior extent of the viewport.
   ViewportDimensions get dimensions => _dimensions;
   ViewportDimensions _dimensions = ViewportDimensions.zero;
   set dimensions(ViewportDimensions value) {
@@ -181,16 +188,23 @@ class RenderViewportBase extends RenderBox {
   }
 }
 
+/// Signature for notifications about [RenderViewport] dimensions changing.
 typedef Offset ViewportDimensionsChangeCallback(ViewportDimensions dimensions);
 
 /// A render object 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
-/// paint offset.
+/// the viewport. The portion of the child that is visible can be controlled
+/// with the [paintOffset].
+///
+/// See also:
+///
+///  * [RenderVirtualViewport] (which works with more than one child)
 class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<RenderBox> {
-
+  /// Creates a render object that's bigger on the inside.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
   RenderViewport({
     RenderBox child,
     Offset paintOffset: Offset.zero,
@@ -203,6 +217,9 @@ class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<
 
   /// Called during [layout] to report the dimensions of the viewport
   /// and its child.
+  ///
+  /// The return value of this function is used as the new [paintOffset] and
+  /// must not be null.
   ViewportDimensionsChangeCallback onPaintOffsetUpdateNeeded;
 
   BoxConstraints _getInnerConstraints(BoxConstraints constraints) {
@@ -315,9 +332,24 @@ class RenderViewport extends RenderViewportBase with RenderObjectWithChildMixin<
   }
 }
 
+/// A render object that shows a subset of its children.
+///
+/// The children of a viewport can layout to a larger size than the viewport
+/// itself. If that happens, only a subset of the children will be visible
+/// through the viewport. The subset of children that are visible can be
+/// controlled with the [paintOffset].
+///
+/// See also:
+///
+///  * [RenderList] (which arranges its children linearly)
+///  * [RenderGrid] (which arranges its children into tiles)
+///  * [RenderViewport] (which is easier to use with a single child)
 abstract class RenderVirtualViewport<T extends ContainerBoxParentDataMixin<RenderBox>>
     extends RenderViewportBase with ContainerRenderObjectMixin<RenderBox, T>,
                                     RenderBoxContainerDefaultsMixin<RenderBox, T> {
+  /// Initializes fields for subclasses.
+  ///
+  /// The [paintOffset] and [mainAxis] arguments must not be null.
   RenderVirtualViewport({
     int virtualChildCount,
     LayoutCallback callback,
@@ -328,6 +360,9 @@ abstract class RenderVirtualViewport<T extends ContainerBoxParentDataMixin<Rende
        _callback = callback,
        super(paintOffset, mainAxis, anchor);
 
+  /// The overall number of children this viewport could potentially display.
+  ///
+  /// If null, the viewport might display an unbounded number of children.
   int get virtualChildCount => _virtualChildCount;
   int _virtualChildCount;
   set virtualChildCount(int value) {

packages/flutter/lib/src/scheduler/binding.dart

@@ -343,19 +343,24 @@ abstract class SchedulerBinding extends BindingBase {
   bool get isProducingFrame => _isProducingFrame;
   bool _isProducingFrame = false;
 
-  /// If necessary, schedules a new frame by calling
-  /// [ui.window.scheduleFrame].
+  /// Schedules a new frame using [scheduleFrame] if this object is not
+  /// currently producing a frame.
   ///
-  /// After this is called, the engine will (eventually) call
-  /// [handleBeginFrame]. (This call might be delayed, e.g. if the
-  /// device's screen is turned off it will typically be delayed until
-  /// the screen is on and the application is visible.)
+  /// After this is called, the framework ensures that the end of the
+  /// [handleBeginFrame] function will (eventually) be reached.
   void ensureVisualUpdate() {
     if (_isProducingFrame)
       return;
     scheduleFrame();
   }
 
+  /// If necessary, schedules a new frame by calling
+  /// [ui.window.scheduleFrame].
+  ///
+  /// After this is called, the engine will (eventually) call
+  /// [handleBeginFrame]. (This call might be delayed, e.g. if the
+  /// device's screen is turned off it will typically be delayed until
+  /// the screen is on and the application is visible.)
   void scheduleFrame() {
     if (_hasScheduledFrame)
       return;

packages/flutter/lib/src/widgets/basic.dart

@@ -1415,14 +1415,6 @@ class BlockBody extends MultiChildRenderObjectWidget {
   }
 }
 
-/// A base class for widgets that accept [Positioned] children.
-abstract class StackRenderObjectWidgetBase extends MultiChildRenderObjectWidget {
-  StackRenderObjectWidgetBase({
-    List<Widget> children: _emptyWidgetList,
-    Key key
-  }) : super(key: key, children: children);
-}
-
 /// Uses the stack layout algorithm for its children.
 ///
 /// This class is useful if you want to overlap several children in a
@@ -1446,7 +1438,11 @@ abstract class StackRenderObjectWidgetBase extends MultiChildRenderObjectWidget
 ///    the child according to a [FractionalOffset] value)
 ///  * [CustomSingleChildLayout]
 ///  * [CustomMultiChildLayout]
-class Stack extends StackRenderObjectWidgetBase {
+class Stack extends MultiChildRenderObjectWidget {
+  /// Creates a stack widget.
+  ///
+  /// By default, the non-positioned children of the stack are aligned by their
+  /// top left corners.
   Stack({
     Key key,
     List<Widget> children: _emptyWidgetList,
@@ -1454,6 +1450,11 @@ class Stack extends StackRenderObjectWidgetBase {
   }) : super(key: key, children: children);
 
   /// How to align the non-positioned children in the stack.
+  ///
+  /// The non-positioned children are placed relative to each other such that
+  /// the points determined by [alignment] are co-located. For example, if the
+  /// [alignment] is [FractionalOffset.topLeft], then the top left corner of
+  /// each non-positioned child will be located at the same global coordinate.
   final FractionalOffset alignment;
 
   @override
@@ -1466,22 +1467,22 @@ class Stack extends StackRenderObjectWidgetBase {
 }
 
 /// A [Stack] that shows a single child from a list of children.
-class IndexedStack extends StackRenderObjectWidgetBase {
+class IndexedStack extends Stack {
+  /// Creates a stack widget that paints a single child.
+  ///
+  /// The [index] argument must not be null.
   IndexedStack({
     Key key,
     List<Widget> children: _emptyWidgetList,
-    this.alignment: FractionalOffset.topLeft,
+    FractionalOffset alignment: FractionalOffset.topLeft,
     this.index: 0
-  }) : super(key: key, children: children) {
+  }) : super(key: key, alignment: alignment, children: children) {
     assert(index != null);
   }
 
   /// The index of the child to show.
   final int index;
 
-  /// How to align the non-positioned children in the stack.
-  final FractionalOffset alignment;
-
   @override
   RenderIndexedStack createRenderObject(BuildContext context) => new RenderIndexedStack(index: index, alignment: alignment);
 
@@ -1498,7 +1499,7 @@ class IndexedStack extends StackRenderObjectWidgetBase {
 /// This widget must be a descendant of a [Stack], and the path from this widget
 /// to its enclosing [Stack] must contain only [StatelessWidget]s or
 /// [StatefulWidget]s (not other kinds of widgets, like [RenderObjectWidget]s).
-class Positioned extends ParentDataWidget<StackRenderObjectWidgetBase> {
+class Positioned extends ParentDataWidget<Stack> {
   /// Creates a Positioned object with the given values.
   ///
   /// Only two out of the three horizontal values ([left], [right],