Adds tooltip to semantics node (#87684)

Author: chunhtai

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

@@ -698,7 +698,7 @@ class TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
     _enableFeedback = widget.enableFeedback ?? tooltipTheme.enableFeedback ?? _defaultEnableFeedback;
 
     Widget result = Semantics(
-      label: _excludeFromSemantics
+      tooltip: _excludeFromSemantics
           ? null
           : _tooltipMessage,
       child: widget.child,

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -3859,6 +3859,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     AttributedString? attributedIncreasedValue,
     AttributedString? attributedDecreasedValue,
     AttributedString? attributedHint,
+    String? tooltip,
     SemanticsHintOverrides? hintOverrides,
     TextDirection? textDirection,
     SemanticsSortKey? sortKey,
@@ -3917,6 +3918,7 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
        _attributedIncreasedValue = attributedIncreasedValue,
        _attributedDecreasedValue = attributedDecreasedValue,
        _attributedHint = attributedHint,
+       _tooltip = tooltip,
        _hintOverrides = hintOverrides,
        _textDirection = textDirection,
        _sortKey = sortKey,
@@ -4311,6 +4313,18 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
     markNeedsSemanticsUpdate();
   }
 
+  /// If non-null, sets the [SemanticsNode.tooltip] semantic to the given value.
+  ///
+  /// The reading direction is given by [textDirection].
+  String? get tooltip => _tooltip;
+  String? _tooltip;
+  set tooltip(String? value) {
+    if (_tooltip == value)
+      return;
+    _tooltip = value;
+    markNeedsSemanticsUpdate();
+  }
+
   /// If non-null, sets the [SemanticsConfiguration.hintOverrides] to the given value.
   SemanticsHintOverrides? get hintOverrides => _hintOverrides;
   SemanticsHintOverrides? _hintOverrides;
@@ -4843,6 +4857,8 @@ class RenderSemanticsAnnotations extends RenderProxyBox {
       config.attributedDecreasedValue = attributedDecreasedValue!;
     if (attributedHint != null)
       config.attributedHint = attributedHint!;
+    if (tooltip != null)
+      config.tooltip = tooltip!;
     if (hintOverrides != null && hintOverrides!.isNotEmpty)
       config.hintOverrides = hintOverrides;
     if (scopesRoute != null)

packages/flutter/lib/src/semantics/semantics.dart

@@ -316,6 +316,7 @@ class SemanticsData with Diagnosticable {
     required this.attributedIncreasedValue,
     required this.attributedDecreasedValue,
     required this.attributedHint,
+    required this.tooltip,
     required this.textDirection,
     required this.rect,
     required this.elevation,
@@ -339,6 +340,7 @@ class SemanticsData with Diagnosticable {
        assert(attributedDecreasedValue != null),
        assert(attributedIncreasedValue != null),
        assert(attributedHint != null),
+       assert(tooltip == '' || textDirection != null, 'A SemanticsData object with tooltip "$tooltip" had a null textDirection.'),
        assert(attributedLabel.string == '' || textDirection != null, 'A SemanticsData object with label "${attributedLabel.string}" had a null textDirection.'),
        assert(attributedValue.string == '' || textDirection != null, 'A SemanticsData object with value "${attributedValue.string}" had a null textDirection.'),
        assert(attributedDecreasedValue.string == '' || textDirection != null, 'A SemanticsData object with decreasedValue "${attributedDecreasedValue.string}" had a null textDirection.'),
@@ -429,6 +431,11 @@ class SemanticsData with Diagnosticable {
   /// See also [hint], which exposes just the raw text.
   final AttributedString attributedHint;
 
+  /// A textual description of the widget's tooltip.
+  ///
+  /// The reading direction is given by [textDirection].
+  final String tooltip;
+
   /// The reading direction for the text in [label], [value],
   /// [increasedValue], [decreasedValue], and [hint].
   final TextDirection? textDirection;
@@ -587,6 +594,7 @@ class SemanticsData with Diagnosticable {
     properties.add(AttributedStringProperty('increasedValue', attributedIncreasedValue));
     properties.add(AttributedStringProperty('decreasedValue', attributedDecreasedValue));
     properties.add(AttributedStringProperty('hint', attributedHint));
+    properties.add(StringProperty('tooltip', tooltip, defaultValue: ''));
     properties.add(EnumProperty<TextDirection>('textDirection', textDirection, defaultValue: null));
     if (textSelection?.isValid ?? false)
       properties.add(MessageProperty('textSelection', '[${textSelection!.start}, ${textSelection!.end}]'));
@@ -610,6 +618,7 @@ class SemanticsData with Diagnosticable {
         && other.attributedIncreasedValue == attributedIncreasedValue
         && other.attributedDecreasedValue == attributedDecreasedValue
         && other.attributedHint == attributedHint
+        && other.tooltip == tooltip
         && other.textDirection == textDirection
         && other.rect == rect
         && setEquals(other.tags, tags)
@@ -637,6 +646,7 @@ class SemanticsData with Diagnosticable {
     attributedIncreasedValue,
     attributedDecreasedValue,
     attributedHint,
+    tooltip,
     textDirection,
     rect,
     tags,
@@ -648,8 +658,8 @@ class SemanticsData with Diagnosticable {
     scrollExtentMin,
     platformViewId,
     maxValueLength,
-    currentValueLength,
     Object.hash(
+      currentValueLength,
       transform,
       elevation,
       thickness,
@@ -785,6 +795,7 @@ class SemanticsProperties extends DiagnosticableTree {
     this.decreasedValue,
     this.attributedDecreasedValue,
     this.hint,
+    this.tooltip,
     this.attributedHint,
     this.hintOverrides,
     this.textDirection,
@@ -1178,6 +1189,16 @@ class SemanticsProperties extends DiagnosticableTree {
   ///  * [hint] for a plain string version of this property.
   final AttributedString? attributedHint;
 
+  /// Provides a textual description of the widget's tooltip.
+  ///
+  /// In Android, this property sets the `AccessibilityNodeInfo.setTooltipText`.
+  /// In iOS, this property is appended to the end of the
+  /// `UIAccessibilityElement.accessibilityLabel`.
+  ///
+  /// If a [tooltip] is provided, there must either by an ambient
+  /// [Directionality] or an explicit [textDirection] should be provided.
+  final String? tooltip;
+
   /// Provides hint values which override the default hints on supported
   /// platforms.
   ///
@@ -1469,6 +1490,7 @@ class SemanticsProperties extends DiagnosticableTree {
     properties.add(AttributedStringProperty('attributedDecreasedValue', attributedDecreasedValue, defaultValue: null));
     properties.add(StringProperty('hint', hint, defaultValue: null));
     properties.add(AttributedStringProperty('attributedHint', attributedHint, defaultValue: null));
+    properties.add(StringProperty('tooltip', tooltip));
     properties.add(EnumProperty<TextDirection>('textDirection', textDirection, defaultValue: null));
     properties.add(DiagnosticsProperty<SemanticsSortKey>('sortKey', sortKey, defaultValue: null));
     properties.add(DiagnosticsProperty<SemanticsHintOverrides>('hintOverrides', hintOverrides, defaultValue: null));
@@ -1898,6 +1920,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
         || _attributedValue != config.attributedValue
         || _attributedIncreasedValue != config.attributedIncreasedValue
         || _attributedDecreasedValue != config.attributedDecreasedValue
+        || _tooltip != config.tooltip
         || _flags != config._flags
         || _textDirection != config.textDirection
         || _sortKey != config._sortKey
@@ -2027,6 +2050,12 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
   AttributedString get attributedHint => _attributedHint;
   AttributedString _attributedHint = _kEmptyConfig.attributedHint;
 
+  /// A textual description of the widget's tooltip.
+  ///
+  /// The reading direction is given by [textDirection].
+  String get tooltip => _tooltip;
+  String _tooltip = _kEmptyConfig.tooltip;
+
   /// The elevation along the z-axis at which the [rect] of this [SemanticsNode]
   /// is located above its parent.
   ///
@@ -2235,6 +2264,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
     _attributedIncreasedValue = config.attributedIncreasedValue;
     _attributedDecreasedValue = config.attributedDecreasedValue;
     _attributedHint = config.attributedHint;
+    _tooltip = config.tooltip;
     _hintOverrides = config.hintOverrides;
     _elevation = config.elevation;
     _thickness = config.thickness;
@@ -2282,6 +2312,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
     AttributedString attributedIncreasedValue = _attributedIncreasedValue;
     AttributedString attributedDecreasedValue = _attributedDecreasedValue;
     AttributedString attributedHint = _attributedHint;
+    String tooltip = _tooltip;
     TextDirection? textDirection = _textDirection;
     Set<SemanticsTag>? mergedTags = tags == null ? null : Set<SemanticsTag>.of(tags!);
     TextSelection? textSelection = _textSelection;
@@ -2336,6 +2367,8 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
           attributedIncreasedValue = node._attributedIncreasedValue;
         if (attributedDecreasedValue == null || attributedDecreasedValue.string == '')
           attributedDecreasedValue = node._attributedDecreasedValue;
+        if (tooltip == '')
+          tooltip = node._tooltip;
         if (node.tags != null) {
           mergedTags ??= <SemanticsTag>{};
           mergedTags!.addAll(node.tags!);
@@ -2385,6 +2418,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
       attributedIncreasedValue: attributedIncreasedValue,
       attributedDecreasedValue: attributedDecreasedValue,
       attributedHint: attributedHint,
+      tooltip: tooltip,
       textDirection: textDirection,
       rect: rect,
       transform: transform,
@@ -2457,6 +2491,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
       decreasedValueAttributes: data.attributedDecreasedValue.attributes,
       hint: data.attributedHint.string,
       hintAttributes: data.attributedHint.attributes,
+      tooltip: data.tooltip,
       textDirection: data.textDirection,
       textSelectionBase: data.textSelection != null ? data.textSelection!.baseOffset : -1,
       textSelectionExtent: data.textSelection != null ? data.textSelection!.extentOffset : -1,
@@ -2595,6 +2630,7 @@ class SemanticsNode extends AbstractNode with DiagnosticableTreeMixin {
     properties.add(AttributedStringProperty('increasedValue', _attributedIncreasedValue));
     properties.add(AttributedStringProperty('decreasedValue', _attributedDecreasedValue));
     properties.add(AttributedStringProperty('hint', _attributedHint));
+    properties.add(StringProperty('tooltip', _tooltip, defaultValue: ''));
     properties.add(EnumProperty<TextDirection>('textDirection', _textDirection, defaultValue: null));
     properties.add(DiagnosticsProperty<SemanticsSortKey>('sortKey', sortKey, defaultValue: null));
     if (_textSelection?.isValid ?? false)
@@ -3955,6 +3991,16 @@ class SemanticsConfiguration {
     _hasBeenAnnotated = true;
   }
 
+  /// A textual description of the widget's tooltip.
+  ///
+  /// The reading direction is given by [textDirection].
+  String get tooltip => _tooltip;
+  String _tooltip = '';
+  set tooltip(String tooltip) {
+    _tooltip = tooltip;
+    _hasBeenAnnotated = true;
+  }
+
   /// Provides hint values which override the default hints on supported
   /// platforms.
   SemanticsHintOverrides? get hintOverrides => _hintOverrides;
@@ -4420,6 +4466,8 @@ class SemanticsConfiguration {
       otherAttributedString: child._attributedHint,
       otherTextDirection: child.textDirection,
     );
+    if (_tooltip == '')
+      _tooltip = child._tooltip;
 
     _thickness = math.max(_thickness, child._thickness + child._elevation);
 
@@ -4442,6 +4490,7 @@ class SemanticsConfiguration {
       .._attributedDecreasedValue = _attributedDecreasedValue
       .._attributedHint = _attributedHint
       .._hintOverrides = _hintOverrides
+      .._tooltip = _tooltip
       .._elevation = _elevation
       .._thickness = _thickness
       .._flags = _flags

packages/flutter/lib/src/widgets/basic.dart

@@ -6695,6 +6695,7 @@ class Semantics extends SingleChildRenderObjectWidget {
     AttributedString? attributedDecreasedValue,
     String? hint,
     AttributedString? attributedHint,
+    String? tooltip,
     String? onTapHint,
     String? onLongPressHint,
     TextDirection? textDirection,
@@ -6759,6 +6760,7 @@ class Semantics extends SingleChildRenderObjectWidget {
       attributedDecreasedValue: attributedDecreasedValue,
       hint: hint,
       attributedHint: attributedHint,
+      tooltip: tooltip,
       textDirection: textDirection,
       sortKey: sortKey,
       tagForChildren: tagForChildren,
@@ -6901,6 +6903,7 @@ class Semantics extends SingleChildRenderObjectWidget {
       attributedIncreasedValue: _effectiveAttributedIncreasedValue,
       attributedDecreasedValue: _effectiveAttributedDecreasedValue,
       attributedHint: _effectiveAttributedHint,
+      tooltip: properties.tooltip,
       hintOverrides: properties.hintOverrides,
       textDirection: _getTextDirection(context),
       sortKey: properties.sortKey,
@@ -6936,7 +6939,8 @@ class Semantics extends SingleChildRenderObjectWidget {
     final bool containsText = properties.attributedLabel != null ||
                               properties.label != null ||
                               properties.value != null ||
-                              properties.hint != null;
+                              properties.hint != null ||
+                              properties.tooltip != null;
 
     if (!containsText)
       return null;
@@ -6977,6 +6981,7 @@ class Semantics extends SingleChildRenderObjectWidget {
       ..attributedIncreasedValue = _effectiveAttributedIncreasedValue
       ..attributedDecreasedValue = _effectiveAttributedDecreasedValue
       ..attributedHint = _effectiveAttributedHint
+      ..tooltip = properties.tooltip
       ..hintOverrides = properties.hintOverrides
       ..namesRoute = properties.namesRoute
       ..textDirection = _getTextDirection(context)

packages/flutter/lib/src/widgets/semantics_debugger.dart

@@ -281,27 +281,33 @@ class _SemanticsDebuggerPainter extends CustomPainter {
 
     assert(data.attributedLabel != null);
     final String message;
-    if (data.attributedLabel.string.isEmpty) {
+    final String tooltipAndLabel = <String>[
+      if (data.tooltip.isNotEmpty)
+        data.tooltip,
+      if (data.attributedLabel.string.isNotEmpty)
+        data.attributedLabel.string,
+    ].join('\n');
+    if (tooltipAndLabel.isEmpty) {
       message = annotations.join('; ');
     } else {
-      final String label;
+      final String effectivelabel;
       if (data.textDirection == null) {
-        label = '${Unicode.FSI}${data.attributedLabel.string}${Unicode.PDI}';
+        effectivelabel = '${Unicode.FSI}$tooltipAndLabel${Unicode.PDI}';
         annotations.insert(0, 'MISSING TEXT DIRECTION');
       } else {
         switch (data.textDirection!) {
           case TextDirection.rtl:
-            label = '${Unicode.RLI}${data.attributedLabel.string}${Unicode.PDF}';
+            effectivelabel = '${Unicode.RLI}$tooltipAndLabel${Unicode.PDF}';
             break;
           case TextDirection.ltr:
-            label = data.attributedLabel.string;
+            effectivelabel = tooltipAndLabel;
             break;
         }
       }
       if (annotations.isEmpty) {
-        message = label;
+        message = effectivelabel;
       } else {
-        message = '$label (${annotations.join('; ')})';
+        message = '$effectivelabel (${annotations.join('; ')})';
       }
     }
 

packages/flutter/test/material/back_button_test.dart

@@ -154,7 +154,7 @@ void main() {
     await tester.pumpAndSettle();
 
     expect(tester.getSemantics(find.byType(BackButton)), matchesSemantics(
-      label: 'Back',
+      tooltip: 'Back',
       isButton: true,
       hasEnabledState: true,
       isEnabled: true,

packages/flutter/test/material/calendar_date_picker_test.dart

@@ -649,15 +649,15 @@ void main() {
 
         // Prev/Next month buttons.
         expect(tester.getSemantics(previousMonthIcon), matchesSemantics(
-          label: 'Previous month',
+          tooltip: 'Previous month',
           isButton: true,
           hasTapAction: true,
           isEnabled: true,
           hasEnabledState: true,
           isFocusable: true,
         ));
         expect(tester.getSemantics(nextMonthIcon), matchesSemantics(
-          label: 'Next month',
+          tooltip: 'Next month',
           isButton: true,
           hasTapAction: true,
           isEnabled: true,

packages/flutter/test/material/chip_test.dart

@@ -1964,7 +1964,7 @@ void main() {
                             ],
                             children: <TestSemantics>[
                               TestSemantics(
-                                label: 'Delete',
+                                tooltip: 'Delete',
                                 actions: <SemanticsAction>[SemanticsAction.tap],
                                 textDirection: TextDirection.ltr,
                                 flags: <SemanticsFlag>[

packages/flutter/test/material/date_picker_test.dart

@@ -817,7 +817,7 @@ void main() {
 
         // Input mode toggle button
         expect(tester.getSemantics(switchToInputIcon), matchesSemantics(
-          label: 'Switch to input',
+          tooltip: 'Switch to input',
           isButton: true,
           hasTapAction: true,
           isEnabled: true,
@@ -860,7 +860,7 @@ void main() {
 
         // Input mode toggle button
         expect(tester.getSemantics(switchToCalendarIcon), matchesSemantics(
-          label: 'Switch to calendar',
+          tooltip: 'Switch to calendar',
           isButton: true,
           hasTapAction: true,
           isEnabled: true,