deprecate needsLayout (#7718)

The needsLayout getter is prone to misuse. See discussion on #3083.

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

@@ -1428,7 +1428,7 @@ abstract class RenderBox extends RenderObject {
   /// are only allowed to call this from the parent of this box during
   /// that parent's [performLayout] or [paint] functions.
   double getDistanceToBaseline(TextBaseline baseline, { bool onlyReal: false }) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     assert(!_debugDoingBaseline);
     assert(() {
       final RenderObject parent = this.parent;
@@ -1493,7 +1493,7 @@ abstract class RenderBox extends RenderObject {
     assert(constraints != null);
     assert(() {
       if (!hasSize) {
-        assert(!needsLayout); // this is called in the size= setter during layout, but in that case we have a size
+        assert(!debugNeedsLayout); // this is called in the size= setter during layout, but in that case we have a size
         String contract;
         if (sizedByParent)
           contract = 'Because this RenderBox has sizedByParent set to true, it must set its size in performResize().\n';
@@ -1669,7 +1669,7 @@ abstract class RenderBox extends RenderObject {
   /// even through it does not [paint] its children.
   bool hitTest(HitTestResult result, { @required Point position }) {
     assert(() {
-      if (needsLayout) {
+      if (debugNeedsLayout) {
         throw new FlutterError(
           'Cannot hit test a dirty render box.\n'
           'The hitTest() method was called on this RenderBox:\n'
@@ -1958,7 +1958,7 @@ abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, Pare
   /// Useful when the children are displayed vertically in the same order they
   /// appear in the child list.
   double defaultComputeDistanceToFirstActualBaseline(TextBaseline baseline) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     ChildType child = firstChild;
     while (child != null) {
       final ParentDataType childParentData = child.parentData;
@@ -1975,7 +1975,7 @@ abstract class RenderBoxContainerDefaultsMixin<ChildType extends RenderBox, Pare
   /// Useful when the vertical position of the children isn't determined by the
   /// order in the child list.
   double defaultComputeDistanceToHighestActualBaseline(TextBaseline baseline) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     double result;
     ChildType child = firstChild;
     while (child != null) {

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

@@ -1439,6 +1439,24 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   }
 
   /// Whether this render object's layout information is dirty.
+  ///
+  /// This is only set in debug mode. In general, render objects should not need
+  /// to condition their runtime behavior on whether they are dirty or not,
+  /// since they should only be marked dirty immediately prior to being laid
+  /// out and painted.
+  bool get debugNeedsLayout {
+    bool result;
+    assert(() {
+      result = _needsLayout;
+      return true;
+    });
+    return result;
+  }
+  @Deprecated(
+    'If you are using needsLayout for an assert, switch to debugNeedsLayout. '
+    'If you are using it for actual runtime logic, please contact the Flutter '
+    'team to let us know what your use case is. We intend to remove this getter.'
+  )
   bool get needsLayout => _needsLayout;
   bool _needsLayout = true;
 
@@ -1505,9 +1523,9 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   /// parent; when the parent is laid out, it will call the child's [layout]
   /// method and thus the child will be laid out as well.
   ///
-  /// Once [markNeedsLayout] has been called on a render object, [needsLayout]
-  /// returns true for that render object until just after the pipeline owner
-  /// has called [layout] on the render object.
+  /// Once [markNeedsLayout] has been called on a render object,
+  /// [debugNeedsLayout] returns true for that render object until just after
+  /// the pipeline owner has called [layout] on the render object.
   ///
   /// ## Special cases
   ///
@@ -1685,7 +1703,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
       _debugCanParentUseSize = parentUsesSize;
       return true;
     });
-    if (!needsLayout && constraints == _constraints && relayoutBoundary == _relayoutBoundary) {
+    if (!_needsLayout && constraints == _constraints && relayoutBoundary == _relayoutBoundary) {
       assert(() {
         // in case parentUsesSize changed since the last invocation, set size
         // to itself, so it has the right internal debug values.

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

@@ -162,7 +162,7 @@ class RenderParagraph extends RenderBox {
 
   @override
   double computeDistanceToActualBaseline(TextBaseline baseline) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     assert(constraints != null);
     assert(constraints.debugAssertIsValid());
     _layoutTextWithConstraints(constraints);
@@ -277,7 +277,7 @@ class RenderParagraph extends RenderBox {
   ///
   /// Valid only after [layout].
   Offset getOffsetForCaret(TextPosition position, Rect caretPrototype) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     _layoutTextWithConstraints(constraints);
     return _textPainter.getOffsetForCaret(position, caretPrototype);
   }
@@ -290,7 +290,7 @@ class RenderParagraph extends RenderBox {
   ///
   /// Valid only after [layout].
   List<ui.TextBox> getBoxesForSelection(TextSelection selection) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     _layoutTextWithConstraints(constraints);
     return _textPainter.getBoxesForSelection(selection);
   }
@@ -299,7 +299,7 @@ class RenderParagraph extends RenderBox {
   ///
   /// Valid only after [layout].
   TextPosition getPositionForOffset(Offset offset) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     _layoutTextWithConstraints(constraints);
     return _textPainter.getPositionForOffset(offset);
   }
@@ -314,7 +314,7 @@ class RenderParagraph extends RenderBox {
   ///
   /// Valid only after [layout].
   TextRange getWordBoundary(TextPosition position) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     _layoutTextWithConstraints(constraints);
     return _textPainter.getWordBoundary(position);
   }

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

@@ -1653,7 +1653,7 @@ class RenderFractionalTranslation extends RenderProxyBox {
 
   @override
   bool hitTest(HitTestResult result, { Point position }) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     if (transformHitTests)
       position = new Point(position.x - translation.dx * size.width, position.y - translation.dy * size.height);
     return super.hitTest(result, position: position);
@@ -1661,7 +1661,7 @@ class RenderFractionalTranslation extends RenderProxyBox {
 
   @override
   void paint(PaintingContext context, Offset offset) {
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     if (child != null)
       super.paint(context, offset + translation.alongSize(size));
   }

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

@@ -90,7 +90,7 @@ class RenderRotatedBox extends RenderBox with RenderObjectWithChildMixin<RenderB
 
   @override
   bool hitTestChildren(HitTestResult result, { Point position }) {
-    assert(_paintTransform != null || needsLayout || child == null);
+    assert(_paintTransform != null || debugNeedsLayout || child == null);
     if (child == null || _paintTransform == null)
       return false;
     Matrix4 inverse = new Matrix4.inverted(_paintTransform);

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

@@ -50,7 +50,7 @@ abstract class RenderShiftedBox extends RenderBox with RenderObjectWithChildMixi
   double computeDistanceToActualBaseline(TextBaseline baseline) {
     double result;
     if (child != null) {
-      assert(!needsLayout);
+      assert(!debugNeedsLayout);
       result = child.getDistanceToActualBaseline(baseline);
       final BoxParentData childParentData = child.parentData;
       if (result != null)
@@ -230,7 +230,7 @@ abstract class RenderAligningShiftedBox extends RenderShiftedBox {
   /// this object's own size has been set.
   void alignChild() {
     assert(child != null);
-    assert(!child.needsLayout);
+    assert(!child.debugNeedsLayout);
     assert(child.hasSize);
     assert(hasSize);
     final BoxParentData childParentData = child.parentData;

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

@@ -835,7 +835,7 @@ abstract class RenderSliver extends RenderObject {
   @protected
   Size getAbsoluteSizeRelativeToOrigin() {
     assert(geometry != null);
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     switch (applyGrowthDirectionToAxisDirection(constraints.axisDirection, constraints.growthDirection)) {
       case AxisDirection.up:
         return new Size(constraints.crossAxisExtent, -geometry.paintExtent);

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

@@ -881,7 +881,7 @@ class RenderTable extends RenderBox {
   @override
   double computeDistanceToActualBaseline(TextBaseline baseline) {
     // returns the baseline of the first cell that has a baseline in the first row
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     return _baselineDistance;
   }
 
@@ -1092,7 +1092,7 @@ class RenderTable extends RenderBox {
   Rect getRowBox(int row) {
     assert(row >= 0);
     assert(row < rows);
-    assert(!needsLayout);
+    assert(!debugNeedsLayout);
     return new Rect.fromLTRB(0.0, _rowTops[row], size.width, _rowTops[row + 1]);
   }
 
@@ -1286,10 +1286,8 @@ class RenderTable extends RenderBox {
       description.add('specified column widths: $_columnWidths');
     description.add('default column width: $defaultColumnWidth');
     description.add('table size: $columns\u00D7$rows');
-    if (!needsLayout) {
-      description.add('column offsets: ${ _columnLefts ?? "unknown" }');
-      description.add('row offsets: ${ _rowTops ?? "unknown" }');
-    }
+    description.add('column offsets: ${ _columnLefts ?? "unknown" }');
+    description.add('row offsets: ${ _rowTops ?? "unknown" }');
   }
 
   @override

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

@@ -2458,7 +2458,7 @@ abstract class Element implements BuildContext {
         );
       }
       final RenderBox box = renderObject;
-      if (!box.hasSize || box.needsLayout) {
+      if (!box.hasSize || box.debugNeedsLayout) {
         throw new FlutterError(
           'Cannot get size from a render object that has not been through layout.\n'
           'The size of this render object has not yet been determined because '

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

@@ -179,7 +179,7 @@ class _HeroState extends State<Hero> implements _HeroHandle {
     assert(mounted);
     final RenderBox renderObject = context.findRenderObject();
     assert(renderObject != null);
-    assert(!renderObject.needsLayout);
+    assert(!renderObject.debugNeedsLayout);
     assert(renderObject.hasSize);
     if (_placeholderSize == null) {
       // We are a "from" hero, about to depart on a quest.

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

@@ -138,7 +138,7 @@ abstract class VirtualViewportElement extends RenderObjectElement {
     _widgetProvider.didUpdateWidget(oldWidget, newWidget);
     super.update(newWidget);
     updateRenderObject(oldWidget);
-    if (!renderObject.needsLayout)
+    if (!renderObject.needsLayout) // ignore: DEPRECATED_MEMBER_USE, this code will all be going away once the scrolling refactor is done
       _materializeChildren();
   }
 
@@ -157,7 +157,7 @@ abstract class VirtualViewportElement extends RenderObjectElement {
 
       // If we don't already need layout, we need to request a layout if the
       // viewport has shifted to expose new children.
-      if (!renderObject.needsLayout) {
+      if (!renderObject.needsLayout) { // ignore: DEPRECATED_MEMBER_USE, this code will all be going away once the scrolling refactor is done
         final double startOffset = widget.startOffset;
         bool shouldLayout = false;
         if (startOffsetBase != null) {

packages/flutter/test/rendering/grid_test.dart

@@ -30,9 +30,9 @@ void main() {
     expect(grid.size.width, equals(200.0), reason: "grid width");
     expect(grid.size.height, equals(200.0), reason: "grid height");
 
-    expect(grid.needsLayout, equals(false));
+    expect(grid.debugNeedsLayout, false);
     grid.delegate = new MaxTileWidthGridDelegate(maxTileWidth: 60.0);
-    expect(grid.needsLayout, equals(true));
+    expect(grid.debugNeedsLayout, true);
 
     pumpFrame();