Skip to content

Commit 97b17bf

Browse files
committed
docs(widgets): explain why RawTooltip uses HardwareKeyboard over Shortcuts
1 parent 4278395 commit 97b17bf

2 files changed

Lines changed: 60 additions & 36 deletions

File tree

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -597,6 +597,16 @@ class RawTooltipState extends State<RawTooltip> with SingleTickerProviderStateMi
597597
case (true, false):
598598
_overlayController.show();
599599
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.
600610
HardwareKeyboard.instance.addHandler(_handleKeyEvent);
601611
SemanticsService.tooltip(widget.semanticsTooltip ?? '');
602612
case (true, true) || (false, false):

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

Lines changed: 50 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -3220,48 +3220,62 @@ void main() {
32203220
expect(find.text(tooltipText), findsNothing);
32213221
});
32223222

3223-
testWidgets('Escape key dismisses open RawTooltip without moving focus', (
3224-
WidgetTester tester,
3225-
) async {
3226-
final key = GlobalKey<RawTooltipState>();
3227-
final focusNode = FocusNode();
3228-
addTearDown(focusNode.dispose);
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);
32293229

3230-
await tester.pumpWidget(
3231-
Directionality(
3232-
textDirection: TextDirection.ltr,
3233-
child: Overlay(
3234-
initialEntries: <OverlayEntry>[
3235-
OverlayEntry(
3236-
builder: (BuildContext context) => Center(
3237-
child: RawTooltip(
3238-
key: key,
3239-
semanticsTooltip: tooltipText,
3240-
tooltipBuilder: (BuildContext context, Animation<double> animation) =>
3241-
const Text(tooltipText),
3242-
child: Focus(
3243-
focusNode: focusNode,
3244-
child: const SizedBox(width: 100.0, height: 100.0),
3245-
),
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+
],
32463260
),
32473261
),
3248-
),
3249-
],
3262+
],
3263+
),
32503264
),
3251-
),
3252-
);
3265+
);
32533266

3254-
focusNode.requestFocus();
3255-
key.currentState!.ensureTooltipVisible();
3256-
await tester.pumpAndSettle();
3257-
expect(focusNode.hasPrimaryFocus, isTrue);
3258-
expect(find.text(tooltipText), findsOneWidget);
3267+
siblingFocusNode.requestFocus();
3268+
key.currentState!.ensureTooltipVisible();
3269+
await tester.pumpAndSettle();
3270+
expect(siblingFocusNode.hasPrimaryFocus, isTrue);
3271+
expect(find.text(tooltipText), findsOneWidget);
32593272

3260-
await tester.sendKeyEvent(LogicalKeyboardKey.escape);
3261-
await tester.pumpAndSettle();
3262-
expect(find.text(tooltipText), findsNothing);
3263-
expect(focusNode.hasPrimaryFocus, isTrue);
3264-
});
3273+
await tester.sendKeyEvent(LogicalKeyboardKey.escape);
3274+
await tester.pumpAndSettle();
3275+
expect(find.text(tooltipText), findsNothing);
3276+
expect(siblingFocusNode.hasPrimaryFocus, isTrue);
3277+
},
3278+
);
32653279
}
32663280

32673281
Future<void> setWidgetForTooltipMode(

0 commit comments

Comments
 (0)