1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// @docImport 'package:flutter/rendering.dart';
6/// @docImport 'package:flutter/widgets.dart';
7library;
8
9import 'package:flutter/foundation.dart';
10import 'package:flutter/gestures.dart';
11
12import 'mouse_cursor.dart';
13
14export 'package:flutter/foundation.dart' show DiagnosticPropertiesBuilder;
15export 'package:flutter/gestures.dart' show PointerEnterEvent, PointerExitEvent, PointerHoverEvent;
16
17export 'mouse_cursor.dart' show MouseCursor;
18
19/// Signature for listening to [PointerEnterEvent] events.
20///
21/// Used by [MouseTrackerAnnotation], [MouseRegion] and [RenderMouseRegion].
22typedef PointerEnterEventListener = void Function(PointerEnterEvent event);
23
24/// Signature for listening to [PointerExitEvent] events.
25///
26/// Used by [MouseTrackerAnnotation], [MouseRegion] and [RenderMouseRegion].
27typedef PointerExitEventListener = void Function(PointerExitEvent event);
28
29/// Signature for listening to [PointerHoverEvent] events.
30///
31/// Used by [MouseTrackerAnnotation], [MouseRegion] and [RenderMouseRegion].
32typedef PointerHoverEventListener = void Function(PointerHoverEvent event);
33
34/// The annotation object used to annotate regions that are interested in mouse
35/// movements.
36///
37/// To use an annotation, return this object as a [HitTestEntry] in a hit test.
38/// Typically this is implemented by making a [RenderBox] implement this class
39/// (see [RenderMouseRegion]).
40///
41/// [MouseTracker] uses this class as a label to filter the hit test results. Hit
42/// test entries that are also [MouseTrackerAnnotation]s are considered as valid
43/// targets in terms of computing mouse related effects, such as enter events,
44/// exit events, and mouse cursor events.
45///
46/// See also:
47///
48/// * [MouseTracker], which uses [MouseTrackerAnnotation].
49class MouseTrackerAnnotation with Diagnosticable {
50 /// Creates an immutable [MouseTrackerAnnotation].
51 const MouseTrackerAnnotation({
52 this.onEnter,
53 this.onExit,
54 this.cursor = MouseCursor.defer,
55 this.validForMouseTracker = true,
56 });
57
58 /// Triggered when a mouse pointer, with or without buttons pressed, has
59 /// entered the region and [validForMouseTracker] is true.
60 ///
61 /// This callback is triggered when the pointer has started to be contained by
62 /// the region, either due to a pointer event, or due to the movement or
63 /// disappearance of the region. This method is always matched by a later
64 /// [onExit].
65 ///
66 /// See also:
67 ///
68 /// * [onExit], which is triggered when a mouse pointer exits the region.
69 /// * [MouseRegion.onEnter], which uses this callback.
70 final PointerEnterEventListener? onEnter;
71
72 /// Triggered when a mouse pointer, with or without buttons pressed, has
73 /// exited the region and [validForMouseTracker] is true.
74 ///
75 /// This callback is triggered when the pointer has stopped being contained
76 /// by the region, either due to a pointer event, or due to the movement or
77 /// disappearance of the region. This method always matches an earlier
78 /// [onEnter].
79 ///
80 /// See also:
81 ///
82 /// * [onEnter], which is triggered when a mouse pointer enters the region.
83 /// * [MouseRegion.onExit], which uses this callback, but is not triggered in
84 /// certain cases and does not always match its earlier [MouseRegion.onEnter].
85 final PointerExitEventListener? onExit;
86
87 /// The mouse cursor for mouse pointers that are hovering over the region.
88 ///
89 /// When a mouse enters the region, its cursor will be changed to the [cursor].
90 /// When the mouse leaves the region, the cursor will be set by the region
91 /// found at the new location.
92 ///
93 /// Defaults to [MouseCursor.defer], deferring the choice of cursor to the next
94 /// region behind it in hit-test order.
95 ///
96 /// See also:
97 ///
98 /// * [MouseRegion.cursor], which provide values to this field.
99 final MouseCursor cursor;
100
101 /// Whether this is included when [MouseTracker] collects the list of
102 /// annotations.
103 ///
104 /// If [validForMouseTracker] is false, this object is excluded from the
105 /// current annotation list even if it's included in the hit test, affecting
106 /// mouse-related behavior such as enter events, exit events, and mouse
107 /// cursors. The [validForMouseTracker] does not affect hit testing.
108 ///
109 /// The [validForMouseTracker] is true for [MouseTrackerAnnotation]s built by
110 /// the constructor.
111 final bool validForMouseTracker;
112
113 @override
114 void debugFillProperties(DiagnosticPropertiesBuilder properties) {
115 super.debugFillProperties(properties);
116 properties.add(
117 FlagsSummary<Function?>('callbacks', <String, Function?>{
118 'enter': onEnter,
119 'exit': onExit,
120 }, ifEmpty: '<none>'),
121 );
122 properties.add(
123 DiagnosticsProperty<MouseCursor>('cursor', cursor, defaultValue: MouseCursor.defer),
124 );
125 }
126}
127