overlay.dart 24.3 KB
Newer Older
1 2 3 4
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:async';
6 7
import 'dart:collection';

8
import 'package:flutter/foundation.dart';
9
import 'package:flutter/rendering.dart';
10
import 'package:flutter/scheduler.dart';
11

12
import 'basic.dart';
13
import 'debug.dart';
14
import 'framework.dart';
15
import 'ticker_provider.dart';
16

17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
/// A place in an [Overlay] that can contain a widget.
///
/// Overlay entries are inserted into an [Overlay] using the
/// [OverlayState.insert] or [OverlayState.insertAll] functions. To find the
/// closest enclosing overlay for a given [BuildContext], use the [Overlay.of]
/// function.
///
/// An overlay entry can be in at most one overlay at a time. To remove an entry
/// from its overlay, call the [remove] function on the overlay entry.
///
/// Because an [Overlay] uses a [Stack] layout, overlay entries can use
/// [Positioned] and [AnimatedPositioned] to position themselves within the
/// overlay.
///
/// For example, [Draggable] uses an [OverlayEntry] to show the drag avatar that
/// follows the user's finger across the screen after the drag begins. Using the
/// overlay to display the drag avatar lets the avatar float over the other
/// widgets in the app. As the user's finger moves, draggable calls
/// [markNeedsBuild] on the overlay entry to cause it to rebuild. It its build,
/// the entry includes a [Positioned] with its top and left property set to
/// position the drag avatar near the user's finger. When the drag is over,
/// [Draggable] removes the entry from the overlay to remove the drag avatar
/// from view.
///
41 42 43 44 45 46
/// By default, if there is an entirely [opaque] entry over this one, then this
/// one will not be included in the widget tree (in particular, stateful widgets
/// within the overlay entry will not be instantiated). To ensure that your
/// overlay entry is still built even if it is not visible, set [maintainState]
/// to true. This is more expensive, so should be done with care. In particular,
/// if widgets in an overlay entry with [maintainState] set to true repeatedly
47
/// call [State.setState], the user's battery will be drained unnecessarily.
48
///
49 50
/// See also:
///
51 52 53 54
///  * [Overlay]
///  * [OverlayState]
///  * [WidgetsApp]
///  * [MaterialApp]
55
class OverlayEntry {
56 57 58 59 60
  /// Creates an overlay entry.
  ///
  /// To insert the entry into an [Overlay], first find the overlay using
  /// [Overlay.of] and then call [OverlayState.insert]. To remove the entry,
  /// call [remove] on the overlay entry itself.
61
  OverlayEntry({
62
    @required this.builder,
63 64
    bool opaque = false,
    bool maintainState = false,
65 66 67 68 69
  }) : assert(builder != null),
       assert(opaque != null),
       assert(maintainState != null),
       _opaque = opaque,
       _maintainState = maintainState;
70

71 72
  /// This entry will include the widget built by this builder in the overlay at
  /// the entry's position.
73
  ///
74
  /// To cause this builder to be called again, call [markNeedsBuild] on this
75
  /// overlay entry.
76
  final WidgetBuilder builder;
77

78 79
  /// Whether this entry occludes the entire overlay.
  ///
80 81 82
  /// If an entry claims to be opaque, then, for efficiency, the overlay will
  /// skip building entries below that entry unless they have [maintainState]
  /// set.
83 84
  bool get opaque => _opaque;
  bool _opaque;
85
  set opaque(bool value) {
Adam Barth's avatar
Adam Barth committed
86
    if (_opaque == value)
87
      return;
88
    _opaque = value;
89
    assert(_overlay != null);
90
    _overlay._didChangeEntryOpacity();
91 92
  }

93 94 95 96 97 98 99 100 101
  /// Whether this entry must be included in the tree even if there is a fully
  /// [opaque] entry above it.
  ///
  /// By default, if there is an entirely [opaque] entry over this one, then this
  /// one will not be included in the widget tree (in particular, stateful widgets
  /// within the overlay entry will not be instantiated). To ensure that your
  /// overlay entry is still built even if it is not visible, set [maintainState]
  /// to true. This is more expensive, so should be done with care. In particular,
  /// if widgets in an overlay entry with [maintainState] set to true repeatedly
102
  /// call [State.setState], the user's battery will be drained unnecessarily.
103 104 105 106 107 108
  ///
  /// This is used by the [Navigator] and [Route] objects to ensure that routes
  /// are kept around even when in the background, so that [Future]s promised
  /// from subsequent routes will be handled properly when they complete.
  bool get maintainState => _maintainState;
  bool _maintainState;
109
  set maintainState(bool value) {
110 111 112 113 114 115 116 117
    assert(_maintainState != null);
    if (_maintainState == value)
      return;
    _maintainState = value;
    assert(_overlay != null);
    _overlay._didChangeEntryOpacity();
  }

118
  OverlayState _overlay;
119
  final GlobalKey<_OverlayEntryState> _key = GlobalKey<_OverlayEntryState>();
120

121
  /// Remove this entry from the overlay.
122 123 124 125
  ///
  /// This should only be called once.
  ///
  /// If this method is called while the [SchedulerBinding.schedulerPhase] is
126 127
  /// [SchedulerPhase.persistentCallbacks], i.e. during the build, layout, or
  /// paint phases (see [WidgetsBinding.drawFrame]), then the removal is
128 129 130 131
  /// delayed until the post-frame callbacks phase. Otherwise the removal is
  /// done synchronously. This means that it is safe to call during builds, but
  /// also that if you do call this during a build, the UI will not update until
  /// the next frame (i.e. many milliseconds later).
132
  void remove() {
133
    assert(_overlay != null);
134
    final OverlayState overlay = _overlay;
135
    _overlay = null;
136 137 138 139 140 141 142
    if (SchedulerBinding.instance.schedulerPhase == SchedulerPhase.persistentCallbacks) {
      SchedulerBinding.instance.addPostFrameCallback((Duration duration) {
        overlay._remove(this);
      });
    } else {
      overlay._remove(this);
    }
143
  }
144

145 146 147
  /// Cause this entry to rebuild during the next pipeline flush.
  ///
  /// You need to call this function if the output of [builder] has changed.
148
  void markNeedsBuild() {
149
    _key.currentState?._markNeedsBuild();
150
  }
151

152
  @override
153
  String toString() => '${describeIdentity(this)}(opaque: $opaque; maintainState: $maintainState)';
154 155
}

156
class _OverlayEntry extends StatefulWidget {
157 158 159
  _OverlayEntry(this.entry)
    : assert(entry != null),
      super(key: entry._key);
160

161
  final OverlayEntry entry;
162 163

  @override
164
  _OverlayEntryState createState() => _OverlayEntryState();
165
}
166

167
class _OverlayEntryState extends State<_OverlayEntry> {
168
  @override
169
  Widget build(BuildContext context) {
170
    return widget.entry.builder(context);
171
  }
172 173 174 175

  void _markNeedsBuild() {
    setState(() { /* the state that changed is in the builder */ });
  }
176 177
}

178
/// A [Stack] of entries that can be managed independently.
179 180 181 182 183 184 185 186 187 188 189 190
///
/// Overlays let independent child widgets "float" visual elements on top of
/// other widgets by inserting them into the overlay's [Stack]. The overlay lets
/// each of these widgets manage their participation in the overlay using
/// [OverlayEntry] objects.
///
/// Although you can create an [Overlay] directly, it's most common to use the
/// overlay created by the [Navigator] in a [WidgetsApp] or a [MaterialApp]. The
/// navigator uses its overlay to manage the visual appearance of its routes.
///
/// See also:
///
191 192 193 194
///  * [OverlayEntry].
///  * [OverlayState].
///  * [WidgetsApp].
///  * [MaterialApp].
195
class Overlay extends StatefulWidget {
196 197 198 199 200
  /// Creates an overlay.
  ///
  /// The initial entries will be inserted into the overlay when its associated
  /// [OverlayState] is initialized.
  ///
201 202
  /// Rather than creating an overlay, consider using the overlay that is
  /// created by the [WidgetsApp] or the [MaterialApp] for the application.
203
  const Overlay({
204
    Key key,
205
    this.initialEntries = const <OverlayEntry>[],
206 207
  }) : assert(initialEntries != null),
       super(key: key);
208

209
  /// The entries to include in the overlay initially.
210 211 212 213 214 215 216 217
  ///
  /// These entries are only used when the [OverlayState] is initialized. If you
  /// are providing a new [Overlay] description for an overlay that's already in
  /// the tree, then the new entries are ignored.
  ///
  /// To add entries to an [Overlay] that is already in the tree, use
  /// [Overlay.of] to obtain the [OverlayState] (or assign a [GlobalKey] to the
  /// [Overlay] widget and obtain the [OverlayState] via
218 219
  /// [GlobalKey.currentState]), and then use [OverlayState.insert] or
  /// [OverlayState.insertAll].
220 221
  ///
  /// To remove an entry from an [Overlay], use [OverlayEntry.remove].
222 223
  final List<OverlayEntry> initialEntries;

224
  /// The state from the closest instance of this class that encloses the given context.
225
  ///
226
  /// In debug mode, if the `debugRequiredFor` argument is provided then this
227 228
  /// function will assert that an overlay was found and will throw an exception
  /// if not. The exception attempts to explain that the calling [Widget] (the
229
  /// one given by the `debugRequiredFor` argument) needs an [Overlay] to be
230
  /// present to function.
231 232 233 234 235 236
  ///
  /// Typical usage is as follows:
  ///
  /// ```dart
  /// OverlayState overlay = Overlay.of(context);
  /// ```
237
  static OverlayState of(BuildContext context, { Widget debugRequiredFor }) {
238
    final OverlayState result = context.ancestorStateOfType(const TypeMatcher<OverlayState>());
239 240
    assert(() {
      if (debugRequiredFor != null && result == null) {
241
        final String additional = context.widget != debugRequiredFor
242 243
          ? '\nThe context from which that widget was searching for an overlay was:\n  $context'
          : '';
244
        throw FlutterError(
245 246 247 248 249 250 251 252 253
          'No Overlay widget found.\n'
          '${debugRequiredFor.runtimeType} widgets require an Overlay widget ancestor for correct operation.\n'
          'The most common way to add an Overlay to an application is to include a MaterialApp or Navigator widget in the runApp() call.\n'
          'The specific widget that failed to find an overlay was:\n'
          '  $debugRequiredFor'
          '$additional'
        );
      }
      return true;
254
    }());
255 256
    return result;
  }
Hixie's avatar
Hixie committed
257

258
  @override
259
  OverlayState createState() => OverlayState();
260 261
}

262
/// The current state of an [Overlay].
263 264 265
///
/// Used to insert [OverlayEntry]s into the overlay using the [insert] and
/// [insertAll] functions.
266
class OverlayState extends State<Overlay> with TickerProviderStateMixin {
267
  final List<OverlayEntry> _entries = <OverlayEntry>[];
268

269
  @override
270 271
  void initState() {
    super.initState();
272
    insertAll(widget.initialEntries);
273 274
  }

275 276 277 278 279 280 281 282 283
  int _insertionIndex(OverlayEntry below, OverlayEntry above) {
    assert(above == null || below == null);
    if (below != null)
      return _entries.indexOf(below);
    if (above != null)
      return _entries.indexOf(above) + 1;
    return _entries.length;
  }

284 285
  /// Insert the given entry into the overlay.
  ///
286
  /// If `below` is non-null, the entry is inserted just below `below`.
287
  /// If `above` is non-null, the entry is inserted just above `above`.
288
  /// Otherwise, the entry is inserted on top.
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305
  ///
  /// It is an error to specify both `above` and `below`.
  void insert(OverlayEntry entry, { OverlayEntry below, OverlayEntry above }) {
    assert(
      above == null || below == null,
      'Only one of `above` and `below` may be specified.',
    );
    assert(
      above == null || (above._overlay == this && _entries.contains(above)),
      'The provided entry for `above` is not present in the Overlay.',
    );
    assert(
      below == null || (below._overlay == this && _entries.contains(below)),
      'The provided entry for `below` is not present in the Overlay.',
    );
    assert(!_entries.contains(entry), 'The specified entry is already present in the Overlay.');
    assert(entry._overlay == null, 'The specified entry is already present in another Overlay.');
306
    entry._overlay = this;
307
    setState(() {
308
      _entries.insert(_insertionIndex(below, above), entry);
309 310 311
    });
  }

312 313
  /// Insert all the entries in the given iterable.
  ///
314
  /// If `below` is non-null, the entries are inserted just below `below`.
315
  /// If `above` is non-null, the entries are inserted just above `above`.
316
  /// Otherwise, the entries are inserted on top.
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
  ///
  /// It is an error to specify both `above` and `below`.
  void insertAll(Iterable<OverlayEntry> entries, { OverlayEntry below, OverlayEntry above }) {
    assert(
      above == null || below == null,
      'Only one of `above` and `below` may be specified.',
    );
    assert(
      above == null || (above._overlay == this && _entries.contains(above)),
      'The provided entry for `above` is not present in the Overlay.',
    );
    assert(
      below == null || (below._overlay == this && _entries.contains(below)),
      'The provided entry for `below` is not present in the Overlay.',
    );
    assert(
      entries.every((OverlayEntry entry) => !_entries.contains(entry)),
      'One or more of the specified entries are already present in the Overlay.'
    );
    assert(
      entries.every((OverlayEntry entry) => entry._overlay == null),
      'One or more of the specified entries are already present in another Overlay.'
    );
Adam Barth's avatar
Adam Barth committed
340 341
    if (entries.isEmpty)
      return;
342
    for (OverlayEntry entry in entries) {
343 344
      assert(entry._overlay == null);
      entry._overlay = this;
345 346
    }
    setState(() {
347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402
      _entries.insertAll(_insertionIndex(below, above), entries);
    });
  }

  /// Remove all the entries listed in the given iterable, then reinsert them
  /// into the overlay in the given order.
  ///
  /// Entries mention in `newEntries` but absent from the overlay are inserted
  /// as if with [insertAll].
  ///
  /// Entries not mentioned in `newEntries` but present in the overlay are
  /// positioned as a group in the resulting list relative to the entries that
  /// were moved, as specified by one of `below` or `above`, which, if
  /// specified, must be one of the entries in `newEntries`:
  ///
  /// If `below` is non-null, the group is positioned just below `below`.
  /// If `above` is non-null, the group is positioned just above `above`.
  /// Otherwise, the group is left on top, with all the rearranged entries
  /// below.
  ///
  /// It is an error to specify both `above` and `below`.
  void rearrange(Iterable<OverlayEntry> newEntries, { OverlayEntry below, OverlayEntry above }) {
    final List<OverlayEntry> newEntriesList = newEntries is List<OverlayEntry> ? newEntries : newEntries.toList(growable: false);
    assert(
      above == null || below == null,
      'Only one of `above` and `below` may be specified.',
    );
    assert(
      above == null || (above._overlay == this && _entries.contains(above) && newEntriesList.contains(above)),
      'The entry used for `above` must be in the Overlay and in the `newEntriesList`.'
    );
    assert(
      below == null || (below._overlay == this && _entries.contains(below) && newEntriesList.contains(below)),
      'The entry used for `below` must be in the Overlay and in the `newEntriesList`.'
    );
    assert(
      newEntriesList.every((OverlayEntry entry) => entry._overlay == null || entry._overlay == this),
      'One or more of the specified entries are already present in another Overlay.'
    );
    assert(
      newEntriesList.every((OverlayEntry entry) => _entries.indexOf(entry) == _entries.lastIndexOf(entry)),
      'One or more of the specified entries are specified multiple times.'
    );
    if (newEntriesList.isEmpty)
      return;
    if (listEquals(_entries, newEntriesList))
      return;
    final LinkedHashSet<OverlayEntry> old = LinkedHashSet<OverlayEntry>.from(_entries);
    for (OverlayEntry entry in newEntriesList) {
      entry._overlay ??= this;
    }
    setState(() {
      _entries.clear();
      _entries.addAll(newEntriesList);
      old.removeAll(newEntriesList);
      _entries.insertAll(_insertionIndex(below, above), old);
403 404 405
    });
  }

406
  void _remove(OverlayEntry entry) {
407
    if (mounted) {
408 409 410
      setState(() {
        _entries.remove(entry);
      });
411
    }
412 413
  }

414 415
  /// (DEBUG ONLY) Check whether a given entry is visible (i.e., not behind an
  /// opaque entry).
416
  ///
417 418
  /// This is an O(N) algorithm, and should not be necessary except for debug
  /// asserts. To avoid people depending on it, this function is implemented
419
  /// only in debug mode, and always returns false in release mode.
420 421 422 423 424
  bool debugIsVisible(OverlayEntry entry) {
    bool result = false;
    assert(_entries.contains(entry));
    assert(() {
      for (int i = _entries.length - 1; i > 0; i -= 1) {
425
        final OverlayEntry candidate = _entries[i];
426 427 428 429
        if (candidate == entry) {
          result = true;
          break;
        }
Hixie's avatar
Hixie committed
430
        if (candidate.opaque)
431 432 433
          break;
      }
      return true;
434
    }());
435 436 437
    return result;
  }

438 439 440 441 442 443 444
  void _didChangeEntryOpacity() {
    setState(() {
      // We use the opacity of the entry in our build function, which means we
      // our state has changed.
    });
  }

445
  @override
446
  Widget build(BuildContext context) {
447 448 449 450 451 452 453
    // These lists are filled backwards. For the offstage children that
    // does not matter since they aren't rendered, but for the onstage
    // children we reverse the list below before adding it to the tree.
    final List<Widget> onstageChildren = <Widget>[];
    final List<Widget> offstageChildren = <Widget>[];
    bool onstage = true;
    for (int i = _entries.length - 1; i >= 0; i -= 1) {
454
      final OverlayEntry entry = _entries[i];
455
      if (onstage) {
456
        onstageChildren.add(_OverlayEntry(entry));
457 458 459
        if (entry.opaque)
          onstage = false;
      } else if (entry.maintainState) {
460
        offstageChildren.add(TickerMode(enabled: false, child: _OverlayEntry(entry)));
461
      }
462
    }
463 464
    return _Theatre(
      onstage: Stack(
465
        fit: StackFit.expand,
466 467
        children: onstageChildren.reversed.toList(growable: false),
      ),
468 469
      offstage: offstageChildren,
    );
470
  }
471

472
  @override
473 474
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
475 476
    // TODO(jacobr): use IterableProperty instead as that would
    // provide a slightly more consistent string summary of the List.
477
    properties.add(DiagnosticsProperty<List<OverlayEntry>>('entries', _entries));
478
  }
479
}
480 481 482 483 484

/// A widget that has one [onstage] child which is visible, and one or more
/// [offstage] widgets which are kept alive, and are built, but are not laid out
/// or painted.
///
485
/// The onstage widget must be a [Stack].
486 487 488 489 490 491
///
/// For convenience, it is legal to use [Positioned] widgets around the offstage
/// widgets.
class _Theatre extends RenderObjectWidget {
  _Theatre({
    this.onstage,
492
    @required this.offstage,
493 494
  }) : assert(offstage != null),
       assert(!offstage.any((Widget child) => child == null));
495 496 497 498 499 500

  final Stack onstage;

  final List<Widget> offstage;

  @override
501
  _TheatreElement createElement() => _TheatreElement(this);
502 503

  @override
504
  _RenderTheatre createRenderObject(BuildContext context) => _RenderTheatre();
505 506 507
}

class _TheatreElement extends RenderObjectElement {
508 509 510
  _TheatreElement(_Theatre widget)
    : assert(!debugChildrenHaveDuplicateKeys(widget, widget.offstage)),
      super(widget);
511 512 513 514 515 516 517 518

  @override
  _Theatre get widget => super.widget;

  @override
  _RenderTheatre get renderObject => super.renderObject;

  Element _onstage;
519
  static final Object _onstageSlot = Object();
520 521

  List<Element> _offstage;
522
  final Set<Element> _forgottenOffstageChildren = HashSet<Element>();
523 524 525

  @override
  void insertChildRenderObject(RenderBox child, dynamic slot) {
526
    assert(renderObject.debugValidateChild(child));
527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
    if (slot == _onstageSlot) {
      assert(child is RenderStack);
      renderObject.child = child;
    } else {
      assert(slot == null || slot is Element);
      renderObject.insert(child, after: slot?.renderObject);
    }
  }

  @override
  void moveChildRenderObject(RenderBox child, dynamic slot) {
    if (slot == _onstageSlot) {
      renderObject.remove(child);
      assert(child is RenderStack);
      renderObject.child = child;
    } else {
      assert(slot == null || slot is Element);
      if (renderObject.child == child) {
        renderObject.child = null;
        renderObject.insert(child, after: slot?.renderObject);
      } else {
        renderObject.move(child, after: slot?.renderObject);
      }
    }
  }

  @override
  void removeChildRenderObject(RenderBox child) {
    if (renderObject.child == child) {
      renderObject.child = null;
    } else {
      renderObject.remove(child);
    }
  }

  @override
  void visitChildren(ElementVisitor visitor) {
    if (_onstage != null)
      visitor(_onstage);
    for (Element child in _offstage) {
567
      if (!_forgottenOffstageChildren.contains(child))
568 569 570 571 572
        visitor(child);
    }
  }

  @override
573
  void debugVisitOnstageChildren(ElementVisitor visitor) {
574 575
    if (_onstage != null)
      visitor(_onstage);
576 577 578
  }

  @override
579
  bool forgetChild(Element child) {
580 581 582
    if (child == _onstage) {
      _onstage = null;
    } else {
583
      assert(_offstage.contains(child));
584 585
      assert(!_forgottenOffstageChildren.contains(child));
      _forgottenOffstageChildren.add(child);
586 587 588 589 590 591 592 593
    }
    return true;
  }

  @override
  void mount(Element parent, dynamic newSlot) {
    super.mount(parent, newSlot);
    _onstage = updateChild(_onstage, widget.onstage, _onstageSlot);
594
    _offstage = List<Element>(widget.offstage.length);
595 596 597 598 599 600 601 602 603 604 605 606 607
    Element previousChild;
    for (int i = 0; i < _offstage.length; i += 1) {
      final Element newChild = inflateWidget(widget.offstage[i], previousChild);
      _offstage[i] = newChild;
      previousChild = newChild;
    }
  }

  @override
  void update(_Theatre newWidget) {
    super.update(newWidget);
    assert(widget == newWidget);
    _onstage = updateChild(_onstage, widget.onstage, _onstageSlot);
608 609
    _offstage = updateChildren(_offstage, widget.offstage, forgottenChildren: _forgottenOffstageChildren);
    _forgottenOffstageChildren.clear();
610 611 612 613 614 615 616 617 618 619 620 621
  }
}

// A render object which lays out and paints one subtree while keeping a list
// of other subtrees alive but not laid out or painted (the "zombie" children).
//
// The subtree that is laid out and painted must be a [RenderStack].
//
// This class uses [StackParentData] objects for its parent data so that the
// children of its primary subtree's stack can be moved to this object's list
// of zombie children without changing their parent data objects.
class _RenderTheatre extends RenderBox
622
  with RenderObjectWithChildMixin<RenderStack>, RenderProxyBoxMixin<RenderStack>,
623 624 625 626 627
       ContainerRenderObjectMixin<RenderBox, StackParentData> {

  @override
  void setupParentData(RenderObject child) {
    if (child.parentData is! StackParentData)
628
      child.parentData = StackParentData();
629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661
  }

  // Because both RenderObjectWithChildMixin and ContainerRenderObjectMixin
  // define redepthChildren, visitChildren and debugDescribeChildren and don't
  // call super, we have to define them again here to make sure the work of both
  // is done.
  //
  // We chose to put ContainerRenderObjectMixin last in the inheritance chain so
  // that we can call super to hit its more complex definitions of
  // redepthChildren and visitChildren, and then duplicate the more trivial
  // definition from RenderObjectWithChildMixin inline in our version here.
  //
  // This code duplication is suboptimal.
  // TODO(ianh): Replace this with a better solution once https://github.com/dart-lang/sdk/issues/27100 is fixed
  //
  // For debugDescribeChildren we just roll our own because otherwise the line
  // drawings won't really work as well.

  @override
  void redepthChildren() {
    if (child != null)
      redepthChild(child);
    super.redepthChildren();
  }

  @override
  void visitChildren(RenderObjectVisitor visitor) {
    if (child != null)
      visitor(child);
    super.visitChildren(visitor);
  }

  @override
662 663 664
  List<DiagnosticsNode> debugDescribeChildren() {
    final List<DiagnosticsNode> children = <DiagnosticsNode>[];

665
    if (child != null)
666 667
      children.add(child.toDiagnosticsNode(name: 'onstage'));

668
    if (firstChild != null) {
669
      RenderBox child = firstChild;
670

671
      int count = 1;
672 673 674 675 676 677 678 679 680
      while (true) {
        children.add(
          child.toDiagnosticsNode(
            name: 'offstage $count',
            style: DiagnosticsTreeStyle.offstage,
          ),
        );
        if (child == lastChild)
          break;
681 682
        final StackParentData childParentData = child.parentData;
        child = childParentData.nextSibling;
683
        count += 1;
684 685
      }
    } else {
686
      children.add(
687
        DiagnosticsNode.message(
688 689 690 691
          'no offstage children',
          style: DiagnosticsTreeStyle.offstage,
        ),
      );
692
    }
693
    return children;
694
  }
695 696 697 698 699 700

  @override
  void visitChildrenForSemantics(RenderObjectVisitor visitor) {
    if (child != null)
      visitor(child);
  }
701
}