Skip to content

Commit 5909913

Browse files
authored
[material_ui] Add tertiary tap callbacks to InkResponse and InkWell (flutter#12676)
Ported from flutter/flutter#191971, which was opened against `flutter/flutter` before I noticed the Material code freeze (flutter/flutter#188444). That PR has been closed in favour of this one. `GestureDetector` exposes `onTertiaryTapDown`, `onTertiaryTapUp` and `onTertiaryTapCancel`, but `InkResponse`/`InkWell` only forward the primary and secondary button callbacks. That means a middle click on an `InkWell` — the usual way to open a link in a new tab or window on desktop and web — can't be handled without wrapping the widget in a second gesture detector, which then has to be reconciled with the ink splash. This PR adds the three tertiary callbacks to `InkResponse` and `InkWell`, mirroring the existing secondary button plumbing: - The pressed highlight and ink splash start on tertiary tap down and are resolved on tap up or cancel, exactly as they are for the secondary button. - The tertiary button is only listened for when `onTertiaryTapDown` or `onTertiaryTapUp` is non-null, so widgets that don't opt in behave exactly as before (no splash on middle click, same as today). - `onTertiaryTapCancel` alone does not enable the button, which matches how `onSecondaryTapCancel` already behaves. There is no `onTertiaryTap` because `TapGestureRecognizer`/`GestureDetector` don't have one; `onTertiaryTapUp` is the completion signal for that button. This follows the approach suggested in the issue: a specific widget with a concrete use case, rather than a general reworking of the button callback pattern. **Tests added** to `packages/material_ui/test/ink_well_test.dart`: - `InkWell tertiary tap test` — verifies the down/up ordering on a completed middle click, and down/cancel when the pointer is dragged away. - `InkWell tertiary tap highlights only when a tertiary callback is defined` — verifies the pressed highlight is raised and lowered on a tertiary press when a tertiary callback is supplied, and that a tertiary press is ignored when one is not. A pending changelog entry is included with a `minor` version bump, since this is additive API. Fixes flutter/flutter#129058 ## Pre-Review Checklist
1 parent af6f7ac commit 5909913

3 files changed

Lines changed: 186 additions & 1 deletion

File tree

‎packages/material_ui/lib/src/ink_well.dart‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,9 @@ class InkResponse extends StatelessWidget {
315315
this.onSecondaryTapUp,
316316
this.onSecondaryTapDown,
317317
this.onSecondaryTapCancel,
318+
this.onTertiaryTapUp,
319+
this.onTertiaryTapDown,
320+
this.onTertiaryTapCancel,
318321
this.onHighlightChanged,
319322
this.onHover,
320323
this.mouseCursor,
@@ -410,6 +413,35 @@ class InkResponse extends StatelessWidget {
410413
/// * [kSecondaryButton], the button this callback responds to.
411414
final GestureTapCallback? onSecondaryTapCancel;
412415

416+
/// Called when the user taps down on this part of the material with a
417+
/// tertiary button.
418+
///
419+
/// A common use case for the tertiary button is opening a link in a new tab
420+
/// or window with a middle click of a mouse.
421+
///
422+
/// See also:
423+
///
424+
/// * [kTertiaryButton], the button this callback responds to.
425+
final GestureTapDownCallback? onTertiaryTapDown;
426+
427+
/// Called when the user releases a tertiary button tap that was started on
428+
/// this part of the material.
429+
///
430+
/// See also:
431+
///
432+
/// * [onTertiaryTapDown], which is called when the tertiary button tap
433+
/// starts.
434+
/// * [kTertiaryButton], the button this callback responds to.
435+
final GestureTapUpCallback? onTertiaryTapUp;
436+
437+
/// Called when the user cancels a tertiary button tap that was started on
438+
/// this part of the material.
439+
///
440+
/// See also:
441+
///
442+
/// * [kTertiaryButton], the button this callback responds to.
443+
final GestureTapCancelCallback? onTertiaryTapCancel;
444+
413445
/// Called when this part of the material either becomes highlighted or stops
414446
/// being highlighted.
415447
///
@@ -674,6 +706,9 @@ class InkResponse extends StatelessWidget {
674706
onSecondaryTapUp: onSecondaryTapUp,
675707
onSecondaryTapDown: onSecondaryTapDown,
676708
onSecondaryTapCancel: onSecondaryTapCancel,
709+
onTertiaryTapUp: onTertiaryTapUp,
710+
onTertiaryTapDown: onTertiaryTapDown,
711+
onTertiaryTapCancel: onTertiaryTapCancel,
677712
onHighlightChanged: onHighlightChanged,
678713
onHover: onHover,
679714
mouseCursor: mouseCursor,
@@ -732,6 +767,9 @@ class _InkResponseStateWidget extends StatefulWidget {
732767
this.onSecondaryTapUp,
733768
this.onSecondaryTapDown,
734769
this.onSecondaryTapCancel,
770+
this.onTertiaryTapUp,
771+
this.onTertiaryTapDown,
772+
this.onTertiaryTapCancel,
735773
this.onHighlightChanged,
736774
this.onHover,
737775
this.mouseCursor,
@@ -771,6 +809,9 @@ class _InkResponseStateWidget extends StatefulWidget {
771809
final GestureTapUpCallback? onSecondaryTapUp;
772810
final GestureTapDownCallback? onSecondaryTapDown;
773811
final GestureTapCallback? onSecondaryTapCancel;
812+
final GestureTapUpCallback? onTertiaryTapUp;
813+
final GestureTapDownCallback? onTertiaryTapDown;
814+
final GestureTapCancelCallback? onTertiaryTapCancel;
774815
final ValueChanged<bool>? onHighlightChanged;
775816
final ValueChanged<bool>? onHover;
776817
final MouseCursor? mouseCursor;
@@ -815,6 +856,9 @@ class _InkResponseStateWidget extends StatefulWidget {
815856
if (onSecondaryTapUp != null) 'secondary tap up',
816857
if (onSecondaryTapDown != null) 'secondary tap down',
817858
if (onSecondaryTapCancel != null) 'secondary tap cancel',
859+
if (onTertiaryTapUp != null) 'tertiary tap up',
860+
if (onTertiaryTapDown != null) 'tertiary tap down',
861+
if (onTertiaryTapCancel != null) 'tertiary tap cancel',
818862
];
819863
properties.add(IterableProperty<String>('gestures', gestures, ifEmpty: '<none>'));
820864
properties.add(DiagnosticsProperty<MouseCursor>('mouseCursor', mouseCursor));
@@ -1183,6 +1227,25 @@ class _InkResponseState extends State<_InkResponseStateWidget>
11831227
widget.onSecondaryTapUp?.call(details);
11841228
}
11851229

1230+
void handleTertiaryTapDown(TapDownDetails details) {
1231+
handleAnyTapDown(details);
1232+
widget.onTertiaryTapDown?.call(details);
1233+
}
1234+
1235+
void handleTertiaryTapUp(TapUpDetails details) {
1236+
_currentSplash?.confirm();
1237+
_currentSplash = null;
1238+
updateHighlight(_HighlightType.pressed, value: false);
1239+
widget.onTertiaryTapUp?.call(details);
1240+
}
1241+
1242+
void handleTertiaryTapCancel() {
1243+
_currentSplash?.cancel();
1244+
_currentSplash = null;
1245+
widget.onTertiaryTapCancel?.call();
1246+
updateHighlight(_HighlightType.pressed, value: false);
1247+
}
1248+
11861249
void _startNewSplash({TapDownDetails? details, BuildContext? context}) {
11871250
assert(details != null || context != null);
11881251

@@ -1284,7 +1347,9 @@ class _InkResponseState extends State<_InkResponseStateWidget>
12841347
}
12851348

12861349
bool isWidgetEnabled(_InkResponseStateWidget widget) {
1287-
return _primaryButtonEnabled(widget) || _secondaryButtonEnabled(widget);
1350+
return _primaryButtonEnabled(widget) ||
1351+
_secondaryButtonEnabled(widget) ||
1352+
_tertiaryButtonEnabled(widget);
12881353
}
12891354

12901355
bool _primaryButtonEnabled(_InkResponseStateWidget widget) {
@@ -1302,9 +1367,14 @@ class _InkResponseState extends State<_InkResponseStateWidget>
13021367
widget.onSecondaryTapDown != null;
13031368
}
13041369

1370+
bool _tertiaryButtonEnabled(_InkResponseStateWidget widget) {
1371+
return widget.onTertiaryTapUp != null || widget.onTertiaryTapDown != null;
1372+
}
1373+
13051374
bool get enabled => isWidgetEnabled(widget);
13061375
bool get _primaryEnabled => _primaryButtonEnabled(widget);
13071376
bool get _secondaryEnabled => _secondaryButtonEnabled(widget);
1377+
bool get _tertiaryEnabled => _tertiaryButtonEnabled(widget);
13081378

13091379
void handleMouseEnter(PointerEnterEvent event) {
13101380
_hovering = true;
@@ -1409,6 +1479,9 @@ class _InkResponseState extends State<_InkResponseStateWidget>
14091479
onSecondaryTapUp: _secondaryEnabled ? handleSecondaryTapUp : null,
14101480
onSecondaryTap: _secondaryEnabled ? handleSecondaryTap : null,
14111481
onSecondaryTapCancel: _secondaryEnabled ? handleSecondaryTapCancel : null,
1482+
onTertiaryTapDown: _tertiaryEnabled ? handleTertiaryTapDown : null,
1483+
onTertiaryTapUp: _tertiaryEnabled ? handleTertiaryTapUp : null,
1484+
onTertiaryTapCancel: _tertiaryEnabled ? handleTertiaryTapCancel : null,
14121485
behavior: HitTestBehavior.opaque,
14131486
excludeFromSemantics: true,
14141487
child: widget.child,
@@ -1524,6 +1597,9 @@ class InkWell extends InkResponse {
15241597
super.onSecondaryTapUp,
15251598
super.onSecondaryTapDown,
15261599
super.onSecondaryTapCancel,
1600+
super.onTertiaryTapUp,
1601+
super.onTertiaryTapDown,
1602+
super.onTertiaryTapCancel,
15271603
super.onHighlightChanged,
15281604
super.onHover,
15291605
super.mouseCursor,
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds `onTertiaryTapDown`, `onTertiaryTapUp` and `onTertiaryTapCancel` to `InkResponse` and `InkWell`, so a tertiary (middle) button click can be handled directly.
3+
version: minor

‎packages/material_ui/test/ink_well_test.dart‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2500,6 +2500,112 @@ void main() {
25002500
},
25012501
);
25022502

2503+
testWidgets('InkWell tertiary tap test', (WidgetTester tester) async {
2504+
final log = <String>[];
2505+
2506+
await tester.pumpWidget(
2507+
Directionality(
2508+
textDirection: TextDirection.ltr,
2509+
child: Material(
2510+
child: Center(
2511+
child: InkWell(
2512+
onTertiaryTapDown: (TapDownDetails details) {
2513+
log.add('tertiary-tap-down');
2514+
},
2515+
onTertiaryTapUp: (TapUpDetails details) {
2516+
log.add('tertiary-tap-up');
2517+
},
2518+
onTertiaryTapCancel: () {
2519+
log.add('tertiary-tap-cancel');
2520+
},
2521+
),
2522+
),
2523+
),
2524+
),
2525+
);
2526+
2527+
await tester.tap(find.byType(InkWell), pointer: 1, buttons: kTertiaryButton);
2528+
2529+
expect(log, equals(<String>['tertiary-tap-down', 'tertiary-tap-up']));
2530+
log.clear();
2531+
2532+
final TestGesture gesture = await tester.startGesture(
2533+
tester.getCenter(find.byType(InkWell)),
2534+
pointer: 2,
2535+
buttons: kTertiaryButton,
2536+
);
2537+
await gesture.moveTo(const Offset(100, 100));
2538+
await gesture.up();
2539+
2540+
expect(log, equals(<String>['tertiary-tap-down', 'tertiary-tap-cancel']));
2541+
});
2542+
2543+
testWidgets('InkWell tertiary tap highlights only when a tertiary callback is defined', (
2544+
WidgetTester tester,
2545+
) async {
2546+
final log = <bool>[];
2547+
2548+
Widget buildFrame({required bool withTertiaryTapDown, required bool withTertiaryTapUp}) {
2549+
return Directionality(
2550+
textDirection: TextDirection.ltr,
2551+
child: Material(
2552+
child: Center(
2553+
child: SizedBox(
2554+
width: 100.0,
2555+
height: 100.0,
2556+
child: InkWell(
2557+
onTap: () {},
2558+
onHighlightChanged: log.add,
2559+
onTertiaryTapDown: withTertiaryTapDown ? (TapDownDetails details) {} : null,
2560+
onTertiaryTapUp: withTertiaryTapUp ? (TapUpDetails details) {} : null,
2561+
),
2562+
),
2563+
),
2564+
),
2565+
);
2566+
}
2567+
2568+
// Each of onTertiaryTapDown and onTertiaryTapUp, alone or together,
2569+
// enables tertiary button handling.
2570+
for (final (bool withTertiaryTapDown, bool withTertiaryTapUp) in <(bool, bool)>[
2571+
(false, true),
2572+
(true, false),
2573+
(true, true),
2574+
]) {
2575+
await tester.pumpWidget(
2576+
buildFrame(withTertiaryTapDown: withTertiaryTapDown, withTertiaryTapUp: withTertiaryTapUp),
2577+
);
2578+
2579+
final TestGesture gesture = await tester.startGesture(
2580+
tester.getRect(find.byType(InkWell)).center,
2581+
buttons: kTertiaryButton,
2582+
);
2583+
await tester.pump(const Duration(milliseconds: 200));
2584+
2585+
expect(log, equals(<bool>[true]));
2586+
log.clear();
2587+
2588+
await gesture.up();
2589+
await tester.pump(const Duration(milliseconds: 200));
2590+
2591+
expect(log, equals(<bool>[false]));
2592+
log.clear();
2593+
}
2594+
2595+
// Without a tertiary callback, a tertiary button press is ignored.
2596+
await tester.pumpWidget(buildFrame(withTertiaryTapDown: false, withTertiaryTapUp: false));
2597+
2598+
final TestGesture gesture = await tester.startGesture(
2599+
tester.getRect(find.byType(InkWell)).center,
2600+
buttons: kTertiaryButton,
2601+
);
2602+
await tester.pump(const Duration(milliseconds: 200));
2603+
2604+
expect(log, isEmpty);
2605+
2606+
await gesture.up();
2607+
});
2608+
25032609
testWidgets('try out hoverDuration property', (WidgetTester tester) async {
25042610
final log = <String>[];
25052611

0 commit comments

Comments
 (0)