blob: b557104d8b0ebee3fb70b570d48ce94c0818d366 [file] [log] [blame]
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'package:meta/meta.dart';
// 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.
/// An abstract node in a tree.
///
/// AbstractNode has as notion of depth, attachment, and parent, but does not
/// have a model for children.
///
/// 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).
///
/// The current parent node is exposed by the [parent] property.
///
/// 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.
///
/// Subclasses that have children must override [attach] and [detach] as
/// described in the documentation for those methods.
///
/// 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.
class AbstractNode {
/// The depth of this node in the tree.
///
/// The depth of nodes in a tree monotonically increases as you traverse down
/// the tree.
int get depth => _depth;
int _depth = 0;
/// Adjust the [depth] of the given [child] to be greater than this node's own
/// [depth].
///
/// Only call this method from overrides of [redepthChildren].
@protected
void redepthChild(AbstractNode child) {
assert(child.owner == owner);
if (child._depth <= _depth) {
child._depth = _depth + 1;
child.redepthChildren();
}
}
/// 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.
void redepthChildren() { }
/// The owner for this node (null if unattached).
///
/// The entire subtree that this node belongs to will have the same owner.
Object get owner => _owner;
Object _owner;
/// Whether this node is in a tree whose root is attached to something.
///
/// This becomes true during the call to [attach].
///
/// This becomes false during the call to [detach].
bool get attached => _owner != null;
/// Mark this node as attached to the given owner.
///
/// Typically called only from the [parent]'s [attach] method, and by the
/// [owner] to mark the root of a tree as attached.
///
/// Subclasses with children should override this method to first call their
/// inherited [attach] method, and then [attach] all their children to the
/// same [owner].
@mustCallSuper
void attach(covariant Object owner) {
assert(owner != null);
assert(_owner == null);
_owner = owner;
}
/// Mark this node as detached.
///
/// Typically called only from the [parent]'s [detach], and by the [owner] to
/// mark the root of a tree as detached.
///
/// Subclasses with children should override this method to first call their
/// inherited [detach] method, and then [detach] all their children.
@mustCallSuper
void detach() {
assert(_owner != null);
_owner = null;
assert(parent == null || attached == parent.attached);
}
/// The parent of this node in the tree.
AbstractNode get parent => _parent;
AbstractNode _parent;
/// Mark the given node as being a child of this node.
///
/// Subclasses should call this function when they acquire a new child.
@protected
@mustCallSuper
void adoptChild(covariant AbstractNode child) {
assert(child != null);
assert(child._parent == null);
assert(() {
AbstractNode node = this;
while (node.parent != null)
node = node.parent;
assert(node != child); // indicates we are about to create a cycle
return true;
}());
child._parent = this;
if (attached)
child.attach(_owner);
redepthChild(child);
}
/// Disconnect the given node from this node.
///
/// Subclasses should call this function when they lose a child.
@protected
@mustCallSuper
void dropChild(covariant AbstractNode child) {
assert(child != null);
assert(child._parent == this);
assert(child.attached == attached);
child._parent = null;
if (attached)
child.detach();
}
}