Skip to content

Commit f8c8551

Browse files
authored
fix(widgets): dismiss open RawTooltip on Escape key (WCAG 1.4.13) (flutter#192966)
## Description Improves `RawTooltip` keyboard accessibility (`WCAG 1.4.13 Dismissible`, http://b/463905826): - **`RawTooltip` `Escape` key dismissal**: Registers a `HardwareKeyboard` handler in `RawTooltipState` that dismisses open tooltips on `LogicalKeyboardKey.escape` (`KeyDownEvent`) and consumes the key event when a tooltip is open, preventing `Escape` from prematurely closing parent modal dialogs (such as `DatePickerDialog`) while a tooltip is displayed. - *(Note: The accompanying Material changes for `Autocomplete`, `DrawerHeader`, and `TooltipThemeData.ignorePointer` will be submitted separately to `packages/material_ui` in `flutter/packages` per [flutter#188444](flutter#188444 Fixes http://b/463905826 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 9dc1569 commit f8c8551

2 files changed

Lines changed: 79 additions & 0 deletions

File tree

‎packages/flutter/lib/src/widgets/raw_tooltip.dart‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -591,11 +591,23 @@ class RawTooltipState extends State<RawTooltip> with SingleTickerProviderStateMi
591591
assert(mounted);
592592
switch ((_animationStatus.isDismissed, status.isDismissed)) {
593593
case (false, true):
594+
HardwareKeyboard.instance.removeHandler(_handleKeyEvent);
594595
RawTooltip._openedTooltips.remove(this);
595596
_overlayController.hide();
596597
case (true, false):
597598
_overlayController.show();
598599
RawTooltip._openedTooltips.add(this);
600+
// Register a global HardwareKeyboard handler while the tooltip is open
601+
// rather than wrapping child in a Shortcuts widget or relying solely on
602+
// WidgetsApp's root Focus handler (app.dart):
603+
// 1. A local Shortcuts widget around RawTooltip.child only receives key
604+
// events when primaryFocus is inside RawTooltip.child, which misses
605+
// tooltips triggered by pointer hover when focus is elsewhere.
606+
// 2. WidgetsApp's root Focus handler is an ancestor of route content, so
607+
// focused descendants that consume Escape (such as EditableText's
608+
// DoNothingAndStopPropagationTextIntent or RawMenuAnchor/DropdownMenu)
609+
// stop propagation before the event bubbles up to WidgetsApp.
610+
HardwareKeyboard.instance.addHandler(_handleKeyEvent);
599611
SemanticsService.tooltip(widget.semanticsTooltip ?? '');
600612
case (true, true) || (false, false):
601613
break;
@@ -808,6 +820,15 @@ class RawTooltipState extends State<RawTooltip> with SingleTickerProviderStateMi
808820
return true;
809821
}
810822

823+
bool _handleKeyEvent(KeyEvent event) {
824+
if (event is KeyDownEvent &&
825+
event.logicalKey == LogicalKeyboardKey.escape &&
826+
RawTooltip._openedTooltips.isNotEmpty) {
827+
return RawTooltip.dismissAllToolTips();
828+
}
829+
return false;
830+
}
831+
811832
@protected
812833
@override
813834
void initState() {
@@ -873,6 +894,7 @@ class RawTooltipState extends State<RawTooltip> with SingleTickerProviderStateMi
873894
@override
874895
void dispose() {
875896
GestureBinding.instance.pointerRouter.removeGlobalRoute(_handleGlobalPointerEvent);
897+
HardwareKeyboard.instance.removeHandler(_handleKeyEvent);
876898
RawTooltip._openedTooltips.remove(this);
877899
// _longPressRecognizer.dispose() and _tapRecognizer.dispose() may call
878900
// their registered onCancel callbacks if there's a gesture in progress.

‎packages/flutter/test/widgets/raw_tooltip_test.dart‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3219,6 +3219,63 @@ void main() {
32193219
await tester.pumpAndSettle();
32203220
expect(find.text(tooltipText), findsNothing);
32213221
});
3222+
3223+
testWidgets(
3224+
'Escape key dismisses hovered RawTooltip even when primaryFocus is on a sibling consuming Escape',
3225+
(WidgetTester tester) async {
3226+
final key = GlobalKey<RawTooltipState>();
3227+
final siblingFocusNode = FocusNode();
3228+
addTearDown(siblingFocusNode.dispose);
3229+
3230+
await tester.pumpWidget(
3231+
Directionality(
3232+
textDirection: TextDirection.ltr,
3233+
child: Overlay(
3234+
initialEntries: <OverlayEntry>[
3235+
OverlayEntry(
3236+
builder: (BuildContext context) => Column(
3237+
children: <Widget>[
3238+
// Simulates a focused TextField/EditableText or menu whose
3239+
// local Shortcuts/Focus consumes Escape and stops propagation
3240+
// before reaching any ancestor Focus/Shortcuts in WidgetsApp,
3241+
// while primaryFocus is outside RawTooltip.child.
3242+
Focus(
3243+
focusNode: siblingFocusNode,
3244+
onKeyEvent: (FocusNode node, KeyEvent event) {
3245+
if (event.logicalKey == LogicalKeyboardKey.escape) {
3246+
return KeyEventResult.handled;
3247+
}
3248+
return KeyEventResult.ignored;
3249+
},
3250+
child: const SizedBox(width: 100.0, height: 100.0),
3251+
),
3252+
RawTooltip(
3253+
key: key,
3254+
semanticsTooltip: tooltipText,
3255+
tooltipBuilder: (BuildContext context, Animation<double> animation) =>
3256+
const Text(tooltipText),
3257+
child: const SizedBox(width: 100.0, height: 100.0),
3258+
),
3259+
],
3260+
),
3261+
),
3262+
],
3263+
),
3264+
),
3265+
);
3266+
3267+
siblingFocusNode.requestFocus();
3268+
key.currentState!.ensureTooltipVisible();
3269+
await tester.pumpAndSettle();
3270+
expect(siblingFocusNode.hasPrimaryFocus, isTrue);
3271+
expect(find.text(tooltipText), findsOneWidget);
3272+
3273+
await tester.sendKeyEvent(LogicalKeyboardKey.escape);
3274+
await tester.pumpAndSettle();
3275+
expect(find.text(tooltipText), findsNothing);
3276+
expect(siblingFocusNode.hasPrimaryFocus, isTrue);
3277+
},
3278+
);
32223279
}
32233280

32243281
Future<void> setWidgetForTooltipMode(

0 commit comments

Comments
 (0)