1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

/// 调用回调以响应常见指针事件的widget
/// A widget that calls callbacks in response to common pointer events.
///
/// 它侦听可以构造手势的事件，例如按下、移动、然后释放或取消指针时
/// It listens to events that can construct gestures, such as when the
/// pointer is pressed, moved, then released or canceled.
///
/// 它不侦听鼠标独有的事件，例如当鼠标进入、退出或悬停某个区域而不按下任何按钮时。对于这些事件，请使用MouseRegion
/// It does not listen to events that are exclusive to mouse, such as when the
/// mouse enters, exits or hovers a region without pressing any buttons. For
/// these events, use [MouseRegion].
///
/// 考虑使用GestureDetector监听更高级别的手势，而不是监听原始指针事件
/// Rather than listening for raw pointer events, consider listening for
/// higher-level gestures using [GestureDetector].
class Listener extends SingleChildRenderObjectWidget {

  const Listener({
    super.key,
    this.onPointerDown,
    this.onPointerMove,
    this.onPointerUp,
    this.onPointerHover,
    this.onPointerCancel,
    this.onPointerPanZoomStart,
    this.onPointerPanZoomUpdate,
    this.onPointerPanZoomEnd,
    this.onPointerSignal,
    this.behavior = HitTestBehavior.deferToChild,
    super.child,
  });

  final PointerDownEventListener? onPointerDown;

  final PointerMoveEventListener? onPointerMove;

  final PointerUpEventListener? onPointerUp;

  final PointerHoverEventListener? onPointerHover;

  final PointerCancelEventListener? onPointerCancel;

  final PointerPanZoomStartEventListener? onPointerPanZoomStart;

  final PointerPanZoomUpdateEventListener? onPointerPanZoomUpdate;

  final PointerPanZoomEndEventListener? onPointerPanZoomEnd;

  final PointerSignalEventListener? onPointerSignal;

  final HitTestBehavior behavior;

  @override
  RenderPointerListener createRenderObject(BuildContext context) {
    return RenderPointerListener(
      onPointerDown: onPointerDown,
      onPointerMove: onPointerMove,
      onPointerUp: onPointerUp,
      onPointerHover: onPointerHover,
      onPointerCancel: onPointerCancel,
      onPointerPanZoomStart: onPointerPanZoomStart,
      onPointerPanZoomUpdate: onPointerPanZoomUpdate,
      onPointerPanZoomEnd: onPointerPanZoomEnd,
      onPointerSignal: onPointerSignal,
      behavior: behavior,
    );
  }

  @override
  void updateRenderObject(BuildContext context, RenderPointerListener renderObject) {
    renderObject
      ..onPointerDown = onPointerDown
      ..onPointerMove = onPointerMove
      ..onPointerUp = onPointerUp
      ..onPointerHover = onPointerHover
      ..onPointerCancel = onPointerCancel
      ..onPointerPanZoomStart = onPointerPanZoomStart
      ..onPointerPanZoomUpdate = onPointerPanZoomUpdate
      ..onPointerPanZoomEnd = onPointerPanZoomEnd
      ..onPointerSignal = onPointerSignal
      ..behavior = behavior;
  }

}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

void main() {
  _runApp(const MyApp());
}

void _runApp(Widget app) {
  final WidgetsBinding binding = WidgetsFlutterBinding.ensureInitialized();
  Timer.run(() {
    binding.attachRootWidget(app);
  });
  binding.scheduleWarmUpFrame();
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Listener(
      child: const ColoredBox(color: Colors.blueAccent),
      onPointerDown: (PointerDownEvent event) => debugPrint('$event'),
      onPointerMove: (PointerMoveEvent event) => debugPrint('$event'),
      onPointerUp: (PointerUpEvent event) => debugPrint('$event'),
      onPointerCancel: (PointerCancelEvent event) => debugPrint('$event'),
    );
  }
}

1
2
3
4

I/flutter (26592): _TransformedPointerDownEvent#ec489(position: Offset(152.4, 615.2))
I/flutter (26592): _TransformedPointerMoveEvent#27677(position: Offset(155.0, 615.2))
I/flutter (26592): _TransformedPointerMoveEvent#7e2ef(position: Offset(157.7, 615.2))
I/flutter (26592): _TransformedPointerUpEvent#fd843(position: Offset(157.7, 615.2))

1
2
3
4
5

// /FlutterSDK/flutter/bin/cache/pkg/sky_engine/lib/ui/hooks.dart
@pragma('vm:entry-point')
void _dispatchPointerDataPacket(ByteData packet) {
  PlatformDispatcher.instance._dispatchPointerDataPacket(packet);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

PointerDataPacketCallback? get onPointerDataPacket => _onPointerDataPacket;
PointerDataPacketCallback? _onPointerDataPacket;
Zone _onPointerDataPacketZone = Zone.root;
set onPointerDataPacket(PointerDataPacketCallback? callback) {
  _onPointerDataPacket = callback;
  _onPointerDataPacketZone = Zone.current;
}

// Called from the engine, via hooks.dart
void _dispatchPointerDataPacket(ByteData packet) {
  if (onPointerDataPacket != null) {
    _invoke1<PointerDataPacket>(
      // 传入PointerDataPacketCallback回调
      onPointerDataPacket,
      _onPointerDataPacketZone,
      _unpackPointerDataPacket(packet),
    );
  }
}

1

typedef PointerDataPacketCallback = void Function(PointerDataPacket packet);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// /FlutterSDK/flutter/bin/cache/pkg/sky_engine/lib/ui/hooks.dart
void _invoke1<A>(void Function(A a)? callback, Zone zone, A arg) {
  if (callback == null) {
    return;
  }
  if (identical(zone, Zone.current)) {
    callback(arg);
  } else {
    zone.runUnaryGuarded<A>(callback, arg);
  }
}

1
2
3
4
5
6
7
8

mixin GestureBinding on BindingBase implements HitTestable, HitTestDispatcher, HitTestTarget {
  @override
  void initInstances() {
    super.initInstances();
    _instance = this;
    platformDispatcher.onPointerDataPacket = _handlePointerDataPacket;
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

final Queue<PointerEvent> _pendingPointerEvents = Queue<PointerEvent>();

void _handlePointerDataPacket(ui.PointerDataPacket packet) {
  // 我们将指针数据转换为逻辑像素，以便例如触摸斜率可以以与设备无关的方式定义。
  // We convert pointer data to logical pixels so that e.g. the touch slop can be
  // defined in a device-independent manner.
  try {
    _pendingPointerEvents.addAll(PointerEventConverter.expand(packet.data, _devicePixelRatioForView));
    // lockEvents当前是否正在锁定事件。绑定触发事件的子类应该首先检查它，如果设置了，则对事件进行排队而不是触发它们。调用unlocked时应刷新事件。
    // 主要用于非用户交互时间，例如允许reassembleApplication在遍历树时阻止输入（部分异步执行），或者锁定事件，以便触摸事件等在预定帧完成之前不会自行插入。
    if (!locked) {
      _flushPointerEventQueue();
    }
  } catch (error, stack) {
    FlutterError.reportError(FlutterErrorDetails(
      exception: error,
      stack: stack,
      library: 'gestures library',
      context: ErrorDescription('while handling a pointer data packet'),
    ));
  }
}

1
2
3
4
5
6
7

void _flushPointerEventQueue() {
  assert(!locked);

  while (_pendingPointerEvents.isNotEmpty) {
    handlePointerEvent(_pendingPointerEvents.removeFirst());
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 将事件分派到通过对其位置进行命中测试找到的目标。
void handlePointerEvent(PointerEvent event) {
  assert(!locked);

  if (resamplingEnabled) {
    _resampler.addOrDispatch(event);
    _resampler.sample(samplingOffset, _samplingClock);
    return;
  }

  // Stop resampler if resampling is not enabled. This is a no-op if
  // resampling was never enabled.
  _resampler.stop();
  _handlePointerEventImmediately(event);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
41
42

void _handlePointerEventImmediately(PointerEvent event) {
  HitTestResult? hitTestResult;
  if (event is PointerDownEvent || event is PointerSignalEvent || event is PointerHoverEvent || event is PointerPanZoomStartEvent) {
    assert(!_hitTests.containsKey(event.pointer), 'Pointer of ${event.toString(minLevel: DiagnosticLevel.debug)} unexpectedly has a HitTestResult associated with it.');
    // 分析一
    hitTestResult = HitTestResult();
    hitTestInView(hitTestResult, event.position, event.viewId);
    if (event is PointerDownEvent || event is PointerPanZoomStartEvent) {
      _hitTests[event.pointer] = hitTestResult;
    }
    assert(() {
      if (debugPrintHitTestResults) {
        debugPrint('${event.toString(minLevel: DiagnosticLevel.debug)}: $hitTestResult');
      }
      return true;
    }());
  } else if (event is PointerUpEvent || event is PointerCancelEvent || event is PointerPanZoomEndEvent) {
    // 分析二
    hitTestResult = _hitTests.remove(event.pointer);
  } else if (event.down || event is PointerPanZoomUpdateEvent) {
    // 因为指针向下时发生的事件（例如 [PointerMoveEvent]）应该分派到其初始 PointerDownEvent 所在的相同位置，所以我们希望重用指针向下时找到的路径，而不是每次都进行命中检测是时候我们得到这样的事件了。
    // Because events that occur with the pointer down (like
    // [PointerMoveEvent]s) should be dispatched to the same place that their
    // initial PointerDownEvent was, we want to re-use the path we found when
    // the pointer went down, rather than do hit detection each time we get
    // such an event.
    // 分析三
    hitTestResult = _hitTests[event.pointer];
  }
  assert(() {
    if (debugPrintMouseHoverEvents && event is PointerHoverEvent) {
      debugPrint('$event');
    }
    return true;
  }());
  // 分析四
  if (hitTestResult != null ||
      event is PointerAddedEvent ||
      event is PointerRemovedEvent) {
    dispatchEvent(event, hitTestResult);
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

@override
void hitTestInView(HitTestResult result, Offset position, int viewId) {
  // Currently Flutter only supports one view, the implicit view `renderView`.
  // TODO(dkwingsmt): After Flutter supports multi-view, look up the correct
  // render view for the ID.
  // https://github.com/flutter/flutter/issues/121573
  assert(viewId == _implicitViewId,
      'Unexpected view ID $viewId (expecting implicit view ID $_implicitViewId)');
  assert(viewId == renderView.flutterView.viewId);
  renderView.hitTest(result, position: position);
  super.hitTestInView(result, position, viewId);
}

1
2
3
4
5
6
7
8

// 确定哪些HitTestTarget对象位于指定视图中的给定位置
@override // from HitTestable
void hitTestInView(HitTestResult result, Offset position, int viewId) {
  // 这里创建了一个HitTestEntry实例，传入this，此处this指的是WidgetsFlutterBinding，这个看runApp方法就可以知道
  // 然后把HitTestEntry实例添加进HitTestResult保存，该HitTestEntry实例在List中是最后一个位置
  // 这里添加进来和手势识别GestureDetector相关，看它的handleEvent方法，这里本文先不讲
  result.add(HitTestEntry(this));
}

1
2
3
4
5
6
7

bool hitTest(HitTestResult result, { required Offset position }) {
  if (child != null) {
    child!.hitTest(BoxHitTestResult.wrap(result), position: position);
  }
  result.add(HitTestEntry(this));
  return true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 确定位于给定位置的渲染对象集
@override
bool hitTest(BoxHitTestResult result, { required Offset position }) {
  bool hitTarget = false;
  // 判断事件的触发位置是否位于组件范围内
  if (size.contains(position)) {
    hitTarget = hitTestChildren(result, position: position) || hitTestSelf(position);
    if (hitTarget || behavior == HitTestBehavior.translucent) {
      result.add(BoxHitTestEntry(this, position));
    }
  }
  return hitTarget;
}

1
2
3
4

@override
bool hitTestChildren(BoxHitTestResult result, { required Offset position }) {
  return child?.hitTest(result, position: position) ?? false;
}

1
2
3
4

@override
bool hitTestChildren(BoxHitTestResult result, { required Offset position }) {
  return defaultHitTestChildren(result, position: position);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

bool defaultHitTestChildren(BoxHitTestResult result, { required Offset position }) {
  // 遍历所有子组件（子节点从后向前遍历）
  ChildType? child = lastChild;
  while (child != null) {
    // The x, y parameters have the top left of the node's box as the origin.
    final ParentDataType childParentData = child.parentData! as ParentDataType;
    // 子组件的hitTest方法的返回值
    final bool isHit = result.addWithPaintOffset(
      offset: childParentData.offset,
      position: position,
      hitTest: (BoxHitTestResult result, Offset transformed) {
        assert(transformed == position - childParentData.offset);
        // 调用子组件的hitTest方法
        return child!.hitTest(result, position: transformed);
      },
    );
    // 一旦有一个子节点的 hitTest() 方法返回 true，则终止遍历，直接返回true
    if (isHit) {
      return true;
    }
    child = childParentData.previousSibling;
  }
  return false;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

bool addWithPaintOffset({
  required Offset? offset,
  required Offset position,
  required BoxHitTest hitTest,
}) {
  final Offset transformedPosition = offset == null ? position : position - offset;
  if (offset != null) {
    pushOffset(-offset);
  }
  // 子组件的hitTest方法的返回值
  final bool isHit = hitTest(this, transformedPosition);
  if (offset != null) {
    popTransform();
  }
  return isHit;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
41
42
43
44

@override // from HitTestDispatcher
@pragma('vm:notify-debugger-on-exception')
void dispatchEvent(PointerEvent event, HitTestResult? hitTestResult) {
  assert(!locked);
  // No hit test information implies that this is a [PointerAddedEvent] or
  // [PointerRemovedEvent]. These events are specially routed here; other
  // events will be routed through the `handleEvent` below.
  if (hitTestResult == null) {
    assert(event is PointerAddedEvent || event is PointerRemovedEvent);
    try {
      pointerRouter.route(event);
    } catch (exception, stack) {
      FlutterError.reportError(FlutterErrorDetailsForPointerEventDispatcher(
        exception: exception,
        stack: stack,
        library: 'gesture library',
        context: ErrorDescription('while dispatching a non-hit-tested pointer event'),
        event: event,
        informationCollector: () => <DiagnosticsNode>[
          DiagnosticsProperty<PointerEvent>('Event', event, style: DiagnosticsTreeStyle.errorProperty),
        ],
      ));
    }
    return;
  }
  for (final HitTestEntry entry in hitTestResult.path) {
    try {
      entry.target.handleEvent(event.transformed(entry.transform), entry);
    } catch (exception, stack) {
      FlutterError.reportError(FlutterErrorDetailsForPointerEventDispatcher(
        exception: exception,
        stack: stack,
        library: 'gesture library',
        context: ErrorDescription('while dispatching a pointer event'),
        event: event,
        hitTestEntry: entry,
        informationCollector: () => <DiagnosticsNode>[
          DiagnosticsProperty<PointerEvent>('Event', event, style: DiagnosticsTreeStyle.errorProperty),
          DiagnosticsProperty<HitTestTarget>('Target', entry.target, style: DiagnosticsTreeStyle.errorProperty),
        ],
      ));
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

@override
void handleEvent(PointerEvent event, HitTestEntry entry) {
  assert(debugHandleEvent(event, entry));
  if (event is PointerDownEvent) {
    return onPointerDown?.call(event);
  }
  if (event is PointerMoveEvent) {
    return onPointerMove?.call(event);
  }
  if (event is PointerUpEvent) {
    return onPointerUp?.call(event);
  }
  if (event is PointerHoverEvent) {
    return onPointerHover?.call(event);
  }
  if (event is PointerCancelEvent) {
    return onPointerCancel?.call(event);
  }
  if (event is PointerPanZoomStartEvent) {
    return onPointerPanZoomStart?.call(event);
  }
  if (event is PointerPanZoomUpdateEvent) {
    return onPointerPanZoomUpdate?.call(event);
  }
  if (event is PointerPanZoomEndEvent) {
    return onPointerPanZoomEnd?.call(event);
  }
  if (event is PointerSignalEvent) {
    return onPointerSignal?.call(event);
  }
}

1
2
3
4

else if (event is PointerUpEvent || event is PointerCancelEvent || event is PointerPanZoomEndEvent) {
  // 分析二
  hitTestResult = _hitTests.remove(event.pointer);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@override
bool hitTest(BoxHitTestResult result, { required Offset position }) {
  bool hitTarget = false;
  if (size.contains(position)) {
    hitTarget = hitTestChildren(result, position: position) || hitTestSelf(position);
    if (hitTarget || behavior == HitTestBehavior.translucent) {
      result.add(BoxHitTestEntry(this, position));
    }
  }
  return hitTarget;
}

@override
bool hitTestSelf(Offset position) => behavior == HitTestBehavior.opaque;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Stack(
        children: [
          _createWidget(1),
          _createWidget(2),
        ],
      ),
    );
  }

  Widget _createWidget(int index) {
    return Listener(
      behavior: HitTestBehavior.translucent,  // 放开此行，点击会同时输出 2 和 1
      // behavior: HitTestBehavior.opaque,    // 放开此行，点击只会输出 2
      onPointerDown: (PointerDownEvent event) => debugPrint('$index'),
      child: const SizedBox.expand(),
    );
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
41
42
43
44
45
46
47
48
49
50

bool hitTest(BoxHitTestResult result, { required Offset position }) {
  assert(() {
    if (!hasSize) {
      if (debugNeedsLayout) {
        throw FlutterError.fromParts(<DiagnosticsNode>[
          ErrorSummary('Cannot hit test a render box that has never been laid out.'),
          describeForError('The hitTest() method was called on this RenderBox'),
          ErrorDescription(
            "Unfortunately, this object's geometry is not known at this time, "
            'probably because it has never been laid out. '
            'This means it cannot be accurately hit-tested.',
          ),
          ErrorHint(
            'If you are trying '
            'to perform a hit test during the layout phase itself, make sure '
            "you only hit test nodes that have completed layout (e.g. the node's "
            'children, after their layout() method has been called).',
          ),
        ]);
      }
      throw FlutterError.fromParts(<DiagnosticsNode>[
        ErrorSummary('Cannot hit test a render box with no size.'),
        describeForError('The hitTest() method was called on this RenderBox'),
        ErrorDescription(
          'Although this node is not marked as needing layout, '
          'its size is not set.',
        ),
        ErrorHint(
          'A RenderBox object must have an '
          'explicit size before it can be hit-tested. Make sure '
          'that the RenderBox in question sets its size during layout.',
        ),
      ]);
    }
    return true;
  }());
  if (_size!.contains(position)) {
    if (hitTestChildren(result, position: position) || hitTestSelf(position)) {
      result.add(BoxHitTestEntry(this, position));
      return true;
    }
  }
  return false;
}

@protected
bool hitTestSelf(Offset position) => false;

@protected
bool hitTestChildren(BoxHitTestResult result, { required Offset position }) => false;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

@override
bool hitTest(BoxHitTestResult result, { required Offset position }) {
  bool hitTarget = false;
  if (size.contains(position)) {
    hitTarget = hitTestChildren(result, position: position) || hitTestSelf(position);
    if (hitTarget || behavior == HitTestBehavior.translucent) {
      result.add(BoxHitTestEntry(this, position));
    }
  }
  return hitTarget;
}

@override
bool hitTestSelf(Offset position) => behavior == HitTestBehavior.opaque;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Listener(
      child: AbsorbPointer(
        child: Listener(
          child: const ColoredBox(color: Colors.blueAccent),
          onPointerDown: (PointerDownEvent event) => debugPrint('inner down'),
        ),
      ),
      onPointerDown: (PointerDownEvent event) => debugPrint('outer down'),
    );
  }
}

1
2
3
4
5
6

@override
bool hitTest(BoxHitTestResult result, { required Offset position }) {
  return absorbing
      ? size.contains(position)
      : super.hitTest(result, position: position);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Listener(
      child: IgnorePointer(
        child: Listener(
          child: const ColoredBox(color: Colors.blueAccent),
          onPointerDown: (PointerDownEvent event) => debugPrint('inner down'),
        ),
      ),
      onPointerDown: (PointerDownEvent event) => debugPrint('outer down'),
    );
  }
}

1
2
3
4

@override
bool hitTest(BoxHitTestResult result, { required Offset position }) {
  return !ignoring && super.hitTest(result, position: position);
}