hit_test.dart 2.47 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.

Ian Hickson's avatar
Ian Hickson committed
5 6 7
import 'events.dart';

/// An object that can hit-test pointers.
Ian Hickson's avatar
Ian Hickson committed
8
abstract class HitTestable { // ignore: one_member_abstracts
9 10 11 12
  /// Check whether the given position hits this object.
  ///
  /// If this given position hits this object, consider adding a [HitTestEntry]
  /// to the given hit test result.
Ian Hickson's avatar
Ian Hickson committed
13 14
  void hitTest(HitTestResult result, Point position);
}
15

16 17
/// An object that can dispatch events.
abstract class HitTestDispatcher { // ignore: one_member_abstracts
18
  /// Override this method to dispatch events.
19 20 21
  void dispatchEvent(PointerEvent event, HitTestResult result);
}

Adam Barth's avatar
Adam Barth committed
22
/// An object that can handle events.
Ian Hickson's avatar
Ian Hickson committed
23
abstract class HitTestTarget { // ignore: one_member_abstracts
24
  /// Override this method to receive events.
Ian Hickson's avatar
Ian Hickson committed
25
  void handleEvent(PointerEvent event, HitTestEntry entry);
26 27
}

Adam Barth's avatar
Adam Barth committed
28 29 30 31
/// Data collected during a hit test about a specific [HitTestTarget].
///
/// Subclass this object to pass additional information from the hit test phase
/// to the event propagation phase.
32
class HitTestEntry {
33
  /// Creates a hit test entry.
34
  const HitTestEntry(this.target);
Adam Barth's avatar
Adam Barth committed
35 36

  /// The [HitTestTarget] encountered during the hit test.
37
  final HitTestTarget target;
Ian Hickson's avatar
Ian Hickson committed
38

39
  @override
Ian Hickson's avatar
Ian Hickson committed
40
  String toString() => '$target';
41 42
}

Adam Barth's avatar
Adam Barth committed
43
/// The result of performing a hit test.
44
class HitTestResult {
45 46 47 48
  /// Creates a hit test result.
  ///
  /// If the [path] argument is null, the [path] field will be initialized with
  /// and empty list.
49
  HitTestResult({ List<HitTestEntry> path })
50
    : _path = path ?? <HitTestEntry>[];
51

52
  /// An unmodifiable list of [HitTestEntry] objects recorded during the hit test.
Adam Barth's avatar
Adam Barth committed
53
  ///
54 55 56
  /// The first entry in the path is the most specific, typically the one at
  /// the leaf of tree being hit tested. Event propagation starts with the most
  /// specific (i.e., first) entry and proceeds in order through the path.
57 58
  List<HitTestEntry> get path => new List<HitTestEntry>.unmodifiable(_path);
  final List<HitTestEntry> _path;
59

Adam Barth's avatar
Adam Barth committed
60 61 62
  /// Add a [HitTestEntry] to the path.
  ///
  /// The new entry is added at the end of the path, which means entries should
Ian Hickson's avatar
Ian Hickson committed
63 64
  /// be added in order from most specific to least specific, typically during an
  /// upward walk of the tree being hit tested.
Adam Barth's avatar
Adam Barth committed
65
  void add(HitTestEntry entry) {
66
    _path.add(entry);
67
  }
Ian Hickson's avatar
Ian Hickson committed
68

69
  @override
70
  String toString() => 'HitTestResult(${_path.isEmpty ? "<empty path>" : _path.join(", ")})';
71
}