node.dart 5.32 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:meta/meta.dart';
6

7 8 9 10
// This file gets mutated by //dev/devicelab/bin/tasks/flutter_test_performance.dart
// during device lab performance tests. When editing this file, check to make sure
// that it didn't break that test.

11
/// An abstract node in a tree.
Adam Barth's avatar
Adam Barth committed
12 13 14
///
/// AbstractNode has as notion of depth, attachment, and parent, but does not
/// have a model for children.
Adam Barth's avatar
Adam Barth committed
15
///
16 17 18 19
/// When a subclass is changing the parent of a child, it should call either
/// `parent.adoptChild(child)` or `parent.dropChild(child)` as appropriate.
/// Subclasses can expose an API for manipulating the tree if desired (e.g. a
/// setter for a `child` property, or an `add()` method to manipulate a list).
Adam Barth's avatar
Adam Barth committed
20
///
21
/// The current parent node is exposed by the [parent] property.
Adam Barth's avatar
Adam Barth committed
22
///
23 24 25 26 27
/// The current attachment state is exposed by [attached]. The root of any tree
/// that is to be considered attached should be manually attached by calling
/// [attach]. Other than that, the [attach] and [detach] methods should not be
/// called directly; attachment is managed automatically by the aforementioned
/// [adoptChild] and [dropChild] methods.
Adam Barth's avatar
Adam Barth committed
28
///
29 30
/// Subclasses that have children must override [attach] and [detach] as
/// described in the documentation for those methods.
Adam Barth's avatar
Adam Barth committed
31
///
32 33 34 35 36 37 38 39 40 41
/// Nodes always have a [depth] greater than their ancestors'. There's no
/// guarantee regarding depth between siblings. The depth of a node is used to
/// ensure that nodes are processed in depth order. The [depth] of a child can
/// be more than one greater than the [depth] of the parent, because the [depth]
/// values are never decreased: all that matters is that it's greater than the
/// parent. Consider a tree with a root node A, a child B, and a grandchild C.
/// Initially, A will have [depth] 0, B [depth] 1, and C [depth] 2. If C is
/// moved to be a child of A, sibling of B, then the numbers won't change. C's
/// [depth] will still be 2. The [depth] is automatically maintained by the
/// [adoptChild] and [dropChild] methods.
42
class AbstractNode {
Adam Barth's avatar
Adam Barth committed
43 44 45
  /// The depth of this node in the tree.
  ///
  /// The depth of nodes in a tree monotonically increases as you traverse down
46
  /// the tree.
47
  int get depth => _depth;
48
  int _depth = 0;
Adam Barth's avatar
Adam Barth committed
49

50
  /// Adjust the [depth] of the given [child] to be greater than this node's own
51 52 53
  /// [depth].
  ///
  /// Only call this method from overrides of [redepthChildren].
54
  @protected
Adam Barth's avatar
Adam Barth committed
55
  void redepthChild(AbstractNode child) {
56
    assert(child.owner == owner);
57 58 59 60 61
    if (child._depth <= _depth) {
      child._depth = _depth + 1;
      child.redepthChildren();
    }
  }
Adam Barth's avatar
Adam Barth committed
62

63 64 65 66
  /// Adjust the [depth] of this node's children, if any.
  ///
  /// Override this method in subclasses with child nodes to call [redepthChild]
  /// for each child. Do not call this method directly.
Adam Barth's avatar
Adam Barth committed
67
  void redepthChildren() { }
68

69
  /// The owner for this node (null if unattached).
70 71
  ///
  /// The entire subtree that this node belongs to will have the same owner.
72 73
  Object? get owner => _owner;
  Object? _owner;
74

Adam Barth's avatar
Adam Barth committed
75
  /// Whether this node is in a tree whose root is attached to something.
76 77 78 79
  ///
  /// This becomes true during the call to [attach].
  ///
  /// This becomes false during the call to [detach].
80
  bool get attached => _owner != null;
Adam Barth's avatar
Adam Barth committed
81

82
  /// Mark this node as attached to the given owner.
Adam Barth's avatar
Adam Barth committed
83
  ///
84 85
  /// Typically called only from the [parent]'s [attach] method, and by the
  /// [owner] to mark the root of a tree as attached.
86
  ///
87 88 89
  /// Subclasses with children should override this method to first call their
  /// inherited [attach] method, and then [attach] all their children to the
  /// same [owner].
90
  @mustCallSuper
91
  void attach(covariant Object owner) {
92 93 94
    assert(owner != null);
    assert(_owner == null);
    _owner = owner;
95
  }
Adam Barth's avatar
Adam Barth committed
96 97 98

  /// Mark this node as detached.
  ///
99 100
  /// Typically called only from the [parent]'s [detach], and by the [owner] to
  /// mark the root of a tree as detached.
101
  ///
102 103
  /// Subclasses with children should override this method to first call their
  /// inherited [detach] method, and then [detach] all their children.
104
  @mustCallSuper
105
  void detach() {
106 107
    assert(_owner != null);
    _owner = null;
108
    assert(parent == null || attached == parent!.attached);
109
  }
Adam Barth's avatar
Adam Barth committed
110 111

  /// The parent of this node in the tree.
112 113
  AbstractNode? get parent => _parent;
  AbstractNode? _parent;
Adam Barth's avatar
Adam Barth committed
114

115 116
  /// Mark the given node as being a child of this node.
  ///
Adam Barth's avatar
Adam Barth committed
117
  /// Subclasses should call this function when they acquire a new child.
118
  @protected
119
  @mustCallSuper
120
  void adoptChild(covariant AbstractNode child) {
121 122
    assert(child != null);
    assert(child._parent == null);
123 124 125
    assert(() {
      AbstractNode node = this;
      while (node.parent != null)
126
        node = node.parent!;
127 128
      assert(node != child); // indicates we are about to create a cycle
      return true;
129
    }());
130 131
    child._parent = this;
    if (attached)
132
      child.attach(_owner!);
133 134
    redepthChild(child);
  }
Adam Barth's avatar
Adam Barth committed
135

136 137
  /// Disconnect the given node from this node.
  ///
Adam Barth's avatar
Adam Barth committed
138
  /// Subclasses should call this function when they lose a child.
139
  @protected
140
  @mustCallSuper
141
  void dropChild(covariant AbstractNode child) {
142 143 144 145 146 147 148 149
    assert(child != null);
    assert(child._parent == this);
    assert(child.attached == attached);
    child._parent = null;
    if (attached)
      child.detach();
  }
}