Skip to content

Commit 3c422dd

Browse files
Introduce exitDuration to Tooltip for mouse pointer devices (#138321)
This PR introduces a new property `exitDuration` to Tooltip, the counterpart to `waitDuration`. The need for this is shown by #136586. This changes the behaviour of `showDuration` on mouse pointer devices. This is because the use cases for the current behaviour on touch screen devices vs mouse pointer devices is fundamentally different. <details> <summary>Demo: tooltip with showDuration set</summary> Tooltip disappears after 100 ms when moving away the mouse. Tooltip will not disappear when hovered. https://github.com/flutter/flutter/assets/5138348/81d36dc9-78e0-4723-a84b-2552843ee181 </details> Currently, when `showDuration` is set, this adjusts the time it takes for the tooltip to hide _after_ a mouse pointer has left the tooltip. This is not the same use case as its effect on touch screen devices, where it dictates how long the tooltip stays on screen after a long press. That is needed because the tooltip takes up screen space and there is not an intuitive way to hide it, whereas when using a mouse users expect to simply have to hover somewhere else. Having the tooltip stay around will look broken. Thus, this PR splits the two use cases. `showDuration` no longer affects mouse pointer devices at all*. There is a precedent for such mouse pointer-only behaviour in `waitDuration`. Instead, I have split up the two use cases and created the new property `exitDuration`, which will still allow for tweaking the time it takes for the tooltip to hide after the user has moved their mouse pointer somewhere else. *Note: Should `showDuration` affect [this line](https://github.com/flutter/flutter/blob/e33d4b86270e3c012ba13d68d6e90f2eabc4912b/packages/flutter/lib/src/material/tooltip.dart#L610)? Fixes #136586. Note: I noticed that when I made the change, no tests were broken. Hopefully, the tests added here help that in the future. I also noticed that in the _existing_ tests, the `waitDuration` tests contain assertions that implicate that it is the role of `waitDuration` to change this behaviour, but that's not currently (nor in the new behaviour) true, so I have fixed those tests.
1 parent 6d4d012 commit 3c422dd

5 files changed

Lines changed: 225 additions & 18 deletions

File tree

‎examples/api/test/material/tooltip/tooltip.1_test.dart‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,9 @@ void main() {
1515
const example.TooltipExampleApp(),
1616
);
1717

18-
TestGesture? gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
18+
final TestGesture gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
1919
addTearDown(() async {
20-
if (gesture != null) {
21-
return gesture.removePointer();
22-
}
20+
return gesture.removePointer();
2321
});
2422
await gesture.addPointer();
2523
await gesture.moveTo(const Offset(1.0, 1.0));
@@ -38,14 +36,9 @@ void main() {
3836
// Move the mouse away and wait for the tooltip to disappear.
3937
await gesture.moveTo(const Offset(1.0, 1.0));
4038
await tester.pump();
41-
// Wait a second and the tooltip should still be visible.
42-
await tester.pump(const Duration(seconds: 1));
43-
expect(find.text(tooltipText), findsOneWidget);
4439
// Wait another second and the tooltip should be gone.
4540
await tester.pump(const Duration(seconds: 1));
4641
await tester.pumpAndSettle();
47-
await gesture.removePointer();
48-
gesture = null;
4942
expect(find.text(tooltipText), findsNothing);
5043
});
5144
}

‎packages/flutter/lib/src/material/tooltip.dart‎

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,7 @@ class Tooltip extends StatefulWidget {
185185
this.textAlign,
186186
this.waitDuration,
187187
this.showDuration,
188+
this.exitDuration,
188189
this.enableTapToDismiss = true,
189190
this.triggerMode,
190191
this.enableFeedback,
@@ -301,13 +302,28 @@ class Tooltip extends StatefulWidget {
301302

302303
/// The length of time that the tooltip will be shown after a long press is
303304
/// released (if triggerMode is [TooltipTriggerMode.longPress]) or a tap is
304-
/// released (if triggerMode is [TooltipTriggerMode.tap]) or mouse pointer
305-
/// exits the widget.
305+
/// released (if triggerMode is [TooltipTriggerMode.tap]). This property
306+
/// does not affect mouse pointer devices.
306307
///
307-
/// Defaults to 1.5 seconds for long press and tap released or 0.1 seconds
308-
/// for mouse pointer exits the widget.
308+
/// Defaults to 1.5 seconds for long press and tap released
309+
///
310+
/// See also:
311+
///
312+
/// * [exitDuration], which allows configuring the time untill a pointer
313+
/// dissapears when hovering.
309314
final Duration? showDuration;
310315

316+
/// The length of time that a pointer must have stopped hovering over a
317+
/// tooltip's widget before the tooltip will be hidden.
318+
///
319+
/// Defaults to 100 milliseconds.
320+
///
321+
/// See also:
322+
///
323+
/// * [showDuration], which allows configuring the length of time that a
324+
/// tooltip will be visible after touch events are released.
325+
final Duration? exitDuration;
326+
311327
/// Whether the tooltip can be dismissed by tap.
312328
///
313329
/// The default value is true.
@@ -388,6 +404,7 @@ class Tooltip extends StatefulWidget {
388404
properties.add(FlagProperty('semantics', value: excludeFromSemantics, ifTrue: 'excluded', showName: true));
389405
properties.add(DiagnosticsProperty<Duration>('wait duration', waitDuration, defaultValue: null));
390406
properties.add(DiagnosticsProperty<Duration>('show duration', showDuration, defaultValue: null));
407+
properties.add(DiagnosticsProperty<Duration>('exit duration', exitDuration, defaultValue: null));
391408
properties.add(DiagnosticsProperty<TooltipTriggerMode>('triggerMode', triggerMode, defaultValue: null));
392409
properties.add(FlagProperty('enableFeedback', value: enableFeedback, ifTrue: 'true', showName: true));
393410
properties.add(DiagnosticsProperty<TextAlign>('textAlign', textAlign, defaultValue: null));
@@ -405,7 +422,7 @@ class TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
405422
static const Duration _fadeInDuration = Duration(milliseconds: 150);
406423
static const Duration _fadeOutDuration = Duration(milliseconds: 75);
407424
static const Duration _defaultShowDuration = Duration(milliseconds: 1500);
408-
static const Duration _defaultHoverShowDuration = Duration(milliseconds: 100);
425+
static const Duration _defaultHoverExitDuration = Duration(milliseconds: 100);
409426
static const Duration _defaultWaitDuration = Duration.zero;
410427
static const bool _defaultExcludeFromSemantics = false;
411428
static const TooltipTriggerMode _defaultTriggerMode = TooltipTriggerMode.longPress;
@@ -419,7 +436,7 @@ class TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
419436
late TooltipThemeData _tooltipTheme;
420437

421438
Duration get _showDuration => widget.showDuration ?? _tooltipTheme.showDuration ?? _defaultShowDuration;
422-
Duration get _hoverShowDuration => widget.showDuration ?? _tooltipTheme.showDuration ?? _defaultHoverShowDuration;
439+
Duration get _hoverExitDuration => widget.exitDuration ?? _tooltipTheme.exitDuration ?? _defaultHoverExitDuration;
423440
Duration get _waitDuration => widget.waitDuration ?? _tooltipTheme.waitDuration ?? _defaultWaitDuration;
424441
TooltipTriggerMode get _triggerMode => widget.triggerMode ?? _tooltipTheme.triggerMode ?? _defaultTriggerMode;
425442
bool get _enableFeedback => widget.enableFeedback ?? _tooltipTheme.enableFeedback ?? _defaultEnableFeedback;
@@ -669,7 +686,7 @@ class TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
669686
}
670687
_activeHoveringPointerDevices.remove(event.device);
671688
if (_activeHoveringPointerDevices.isEmpty) {
672-
_scheduleDismissTooltip(withDelay: _hoverShowDuration);
689+
_scheduleDismissTooltip(withDelay: _hoverExitDuration);
673690
}
674691
}
675692

‎packages/flutter/lib/src/material/tooltip_theme.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ class TooltipThemeData with Diagnosticable {
4141
this.textAlign,
4242
this.waitDuration,
4343
this.showDuration,
44+
this.exitDuration,
4445
this.triggerMode,
4546
this.enableFeedback,
4647
});
@@ -96,6 +97,10 @@ class TooltipThemeData with Diagnosticable {
9697
/// The length of time that the tooltip will be shown once it has appeared.
9798
final Duration? showDuration;
9899

100+
/// The length of time that a pointer must have stopped hovering over a
101+
/// tooltip's widget before the tooltip will be hidden.
102+
final Duration? exitDuration;
103+
99104
/// The [TooltipTriggerMode] that will show the tooltip.
100105
final TooltipTriggerMode? triggerMode;
101106

@@ -126,6 +131,7 @@ class TooltipThemeData with Diagnosticable {
126131
TextAlign? textAlign,
127132
Duration? waitDuration,
128133
Duration? showDuration,
134+
Duration? exitDuration,
129135
TooltipTriggerMode? triggerMode,
130136
bool? enableFeedback,
131137
}) {
@@ -181,6 +187,7 @@ class TooltipThemeData with Diagnosticable {
181187
textAlign,
182188
waitDuration,
183189
showDuration,
190+
exitDuration,
184191
triggerMode,
185192
enableFeedback,
186193
);
@@ -205,6 +212,7 @@ class TooltipThemeData with Diagnosticable {
205212
&& other.textAlign == textAlign
206213
&& other.waitDuration == waitDuration
207214
&& other.showDuration == showDuration
215+
&& other.exitDuration == exitDuration
208216
&& other.triggerMode == triggerMode
209217
&& other.enableFeedback == enableFeedback;
210218
}
@@ -223,6 +231,7 @@ class TooltipThemeData with Diagnosticable {
223231
properties.add(DiagnosticsProperty<TextAlign>('textAlign', textAlign, defaultValue: null));
224232
properties.add(DiagnosticsProperty<Duration>('wait duration', waitDuration, defaultValue: null));
225233
properties.add(DiagnosticsProperty<Duration>('show duration', showDuration, defaultValue: null));
234+
properties.add(DiagnosticsProperty<Duration>('exit duration', exitDuration, defaultValue: null));
226235
properties.add(DiagnosticsProperty<TooltipTriggerMode>('triggerMode', triggerMode, defaultValue: null));
227236
properties.add(FlagProperty('enableFeedback', value: enableFeedback, ifTrue: 'true', showName: true));
228237
}

‎packages/flutter/test/material/tooltip_test.dart‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2431,6 +2431,104 @@ void main() {
24312431
expect(find.text(tooltipText), findsNothing);
24322432
});
24332433

2434+
testWidgetsWithLeakTracking('Hovered tooltips with showDuration set do dismiss when hovering elswhere', (WidgetTester tester) async {
2435+
const Duration waitDuration = Duration.zero;
2436+
const Duration showDuration = Duration(seconds: 1);
2437+
2438+
await tester.pumpWidget(
2439+
const MaterialApp(
2440+
home: Center(
2441+
child: Tooltip(
2442+
message: tooltipText,
2443+
waitDuration: waitDuration,
2444+
showDuration: showDuration,
2445+
triggerMode: TooltipTriggerMode.longPress,
2446+
child: SizedBox(
2447+
width: 100.0,
2448+
height: 100.0,
2449+
),
2450+
),
2451+
),
2452+
),
2453+
);
2454+
2455+
final TestGesture gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
2456+
addTearDown(gesture.removePointer);
2457+
await gesture.moveTo(tester.getCenter(find.byTooltip(tooltipText)));
2458+
await tester.pump(const Duration(seconds: 1));
2459+
expect(find.text(tooltipText), findsOneWidget, reason: 'Tooltip should be visible when hovered.');
2460+
2461+
await gesture.moveTo(Offset.zero);
2462+
// Set a duration equal to the default exit
2463+
await tester.pump(const Duration(milliseconds: 100));
2464+
await tester.pumpAndSettle();
2465+
expect(find.text(tooltipText), findsNothing,
2466+
reason: 'Tooltip should not wait for showDuration before it hides itself.');
2467+
});
2468+
2469+
testWidgetsWithLeakTracking('Hovered tooltips hide after stopping the hover', (WidgetTester tester) async {
2470+
await tester.pumpWidget(
2471+
const MaterialApp(
2472+
home: Center(
2473+
child: SizedBox.square(
2474+
dimension: 10.0,
2475+
child: Tooltip(
2476+
message: tooltipText,
2477+
triggerMode: TooltipTriggerMode.longPress,
2478+
child: SizedBox.expand(),
2479+
),
2480+
),
2481+
),
2482+
),
2483+
);
2484+
2485+
final TestGesture gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
2486+
addTearDown(gesture.removePointer);
2487+
await gesture.moveTo(tester.getCenter(find.byTooltip(tooltipText)));
2488+
await tester.pump(const Duration(seconds: 1));
2489+
expect(find.text(tooltipText), findsOneWidget, reason: 'Tooltip should be visible when hovered.');
2490+
2491+
await gesture.moveTo(Offset.zero);
2492+
await tester.pump(const Duration(milliseconds: 100));
2493+
await tester.pumpAndSettle();
2494+
expect(find.text(tooltipText), findsNothing, reason: 'Tooltip should be hidden when no longer hovered.');
2495+
});
2496+
2497+
testWidgetsWithLeakTracking('Hovered tooltips hide after stopping the hover and exitDuration expires', (WidgetTester tester) async {
2498+
const Duration exitDuration = Duration(seconds: 1);
2499+
await tester.pumpWidget(
2500+
const MaterialApp(
2501+
home: Center(
2502+
child: SizedBox.square(
2503+
dimension: 10.0,
2504+
child: Tooltip(
2505+
message: tooltipText,
2506+
exitDuration: exitDuration,
2507+
triggerMode: TooltipTriggerMode.longPress,
2508+
child: SizedBox.expand(),
2509+
),
2510+
),
2511+
),
2512+
),
2513+
);
2514+
2515+
final TestGesture gesture = await tester.createGesture(kind: PointerDeviceKind.mouse);
2516+
addTearDown(gesture.removePointer);
2517+
await gesture.moveTo(tester.getCenter(find.byTooltip(tooltipText)));
2518+
await tester.pump(const Duration(seconds: 1));
2519+
expect(find.text(tooltipText), findsOneWidget, reason: 'Tooltip should be visible when hovered.');
2520+
2521+
await gesture.moveTo(Offset.zero);
2522+
await tester.pump(const Duration(milliseconds: 100));
2523+
await tester.pumpAndSettle();
2524+
expect(find.text(tooltipText), findsOneWidget,
2525+
reason: 'Tooltip should wait untill exitDuration expires before being hidden');
2526+
2527+
await tester.pump(const Duration(seconds: 1));
2528+
await tester.pumpAndSettle();
2529+
expect(find.text(tooltipText), findsNothing, reason: 'Tooltip should be hidden when no longer hovered.');
2530+
});
2531+
24342532
testWidgetsWithLeakTracking('Tooltip should not be shown with empty message (with child)', (WidgetTester tester) async {
24352533
await tester.pumpWidget(
24362534
const MaterialApp(

0 commit comments

Comments
 (0)