[TextField][A11y] Add tooltip support to TextInputLayout icons

- The icon's `contentDescription` is used as the tooltip text.
- Tooltips are only shown for icons that are interactive (focusable). Decorative-only icons will not display a tooltip.
- `CheckableImageButton` is updated to provide a callback for when its focusable state changes, which is used to trigger tooltip updates.
- API-level differences are handled to ensure that custom `OnLongClickListeners` are not overridden by the tooltip's long-press listener on older platforms (pre-API 26).

PiperOrigin-RevId: 794951524

Author: Material Design Team

lib/java/com/google/android/material/internal/CheckableImageButton.java

@@ -27,6 +27,7 @@
 import android.view.accessibility.AccessibilityEvent;
 import android.widget.Checkable;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.annotation.RestrictTo;
 import androidx.core.view.AccessibilityDelegateCompat;
 import androidx.core.view.ViewCompat;
@@ -44,6 +45,9 @@ public class CheckableImageButton extends AppCompatImageButton implements Checka
   private boolean checkable = true;
   private boolean pressable = true;
 
+  @Nullable
+  private OnFocusableChangedListener onFocusableChangedListener;
+
   public CheckableImageButton(Context context) {
     this(context, null);
   }
@@ -100,6 +104,16 @@ public void setPressed(boolean pressed) {
     }
   }
 
+  @Override
+  public void setFocusable(boolean focusable) {
+    boolean originalFocusable = isFocusable();
+    super.setFocusable(focusable);
+
+    if (originalFocusable != focusable && onFocusableChangedListener != null) {
+      onFocusableChangedListener.onFocusableChanged(this, focusable);
+    }
+  }
+
   @Override
   public int[] onCreateDrawableState(int extraSpace) {
     if (checked) {
@@ -131,6 +145,12 @@ protected void onRestoreInstanceState(Parcelable state) {
     setChecked(savedState.checked);
   }
 
+  @Override
+  protected void onDetachedFromWindow() {
+    onFocusableChangedListener = null;
+    super.onDetachedFromWindow();
+  }
+
   /** Sets image button to be checkable or not. */
   public void setCheckable(boolean checkable) {
     if (this.checkable != checkable) {
@@ -154,6 +174,26 @@ public boolean isPressable() {
     return pressable;
   }
 
+  /** Register a callback to be invoked when the focusable state of this view changes. */
+  public void setOnFocusableChangedListener(
+      @Nullable OnFocusableChangedListener onFocusableChangedListener) {
+    this.onFocusableChangedListener = onFocusableChangedListener;
+  }
+
+  /**
+   * Interface definition for a callback to be invoked when the focusable state of this view
+   * changes.
+   */
+  public interface OnFocusableChangedListener {
+    /**
+     * Called when the focusable state of a view has changed.
+     *
+     * @param view The view whose focusable state has changed.
+     * @param focusable The new focusable state of view.
+     */
+    void onFocusableChanged(@NonNull View view, boolean focusable);
+  }
+
   static class SavedState extends AbsSavedState {
 
     boolean checked;

lib/java/com/google/android/material/textfield/EndCompoundLayout.java

@@ -26,6 +26,7 @@
 import static com.google.android.material.textfield.IconHelper.setIconOnClickListener;
 import static com.google.android.material.textfield.IconHelper.setIconOnLongClickListener;
 import static com.google.android.material.textfield.IconHelper.setIconScaleType;
+import static com.google.android.material.textfield.IconHelper.updateIconTooltip;
 import static com.google.android.material.textfield.TextInputLayout.END_ICON_CLEAR_TEXT;
 import static com.google.android.material.textfield.TextInputLayout.END_ICON_CUSTOM;
 import static com.google.android.material.textfield.TextInputLayout.END_ICON_DROPDOWN_MENU;
@@ -182,6 +183,17 @@ public void onEditTextAttached(@NonNull TextInputLayout textInputLayout) {
     addView(endIconFrame);
     addView(errorIconView);
 
+    errorIconView.setOnFocusableChangedListener(
+        (v, focusable) ->
+            updateIconTooltip(
+                errorIconView,
+                errorIconOnLongClickListener,
+                errorIconView.getContentDescription()));
+    endIconView.setOnFocusableChangedListener(
+        (v, focusable) ->
+            updateIconTooltip(
+                endIconView, endIconOnLongClickListener, getEndIconContentDescription()));
+
     textInputLayout.addOnEditTextAttachedListener(onEditTextAttachedListener);
     addOnAttachStateChangeListener(
         new OnAttachStateChangeListener() {
@@ -363,7 +375,6 @@ void setEndIconMode(@EndIconMode int endIconMode) {
     setEndIconVisible(endIconMode != END_ICON_NONE);
     EndIconDelegate delegate = getEndIconDelegate();
     setEndIconDrawable(getIconResId(delegate));
-    setEndIconContentDescription(delegate.getIconContentDescriptionResId());
     setEndIconCheckable(delegate.isIconCheckable());
     if (delegate.isBoxBackgroundModeSupported(textInputLayout.getBoxBackgroundMode())) {
       setUpDelegate(delegate);
@@ -375,6 +386,7 @@ void setEndIconMode(@EndIconMode int endIconMode) {
               + endIconMode);
     }
     setEndIconOnClickListener(delegate.getOnIconClickListener());
+    setEndIconContentDescription(delegate.getIconContentDescriptionResId());
     if (editText != null) {
       delegate.onEditTextAttached(editText);
       setOnFocusChangeListenersIfNeeded(delegate);
@@ -534,6 +546,7 @@ void setEndIconContentDescription(@StringRes int resId) {
   void setEndIconContentDescription(@Nullable CharSequence endIconContentDescription) {
     if (getEndIconContentDescription() != endIconContentDescription) {
       endIconView.setContentDescription(endIconContentDescription);
+      updateIconTooltip(endIconView, endIconOnLongClickListener, endIconContentDescription);
     }
   }
 

lib/java/com/google/android/material/textfield/IconHelper.java

@@ -21,8 +21,10 @@
 import android.content.res.ColorStateList;
 import android.graphics.PorterDuff;
 import android.graphics.drawable.Drawable;
+import android.os.Build;
 import android.os.Build.VERSION;
 import android.os.Build.VERSION_CODES;
+import androidx.appcompat.widget.TooltipCompat;
 import android.view.View;
 import android.view.View.OnClickListener;
 import android.view.View.OnLongClickListener;
@@ -61,7 +63,12 @@ private static void setIconClickable(
     iconView.setFocusable(iconFocusable);
     iconView.setClickable(iconClickable);
     iconView.setPressable(iconClickable);
-    iconView.setLongClickable(iconLongClickable);
+    // Pre-O, the tooltip is set via a long-click listener. If we have a custom OnClickListener but
+    // no custom OnLongClickListener, do not set the view to not be long-clickable, so that the
+    // tooltip can be shown.
+    if (VERSION.SDK_INT >= VERSION_CODES.O || !iconFocusable || iconLongClickable) {
+      iconView.setLongClickable(iconLongClickable);
+    }
     iconView.setImportantForAccessibility(
         iconFocusable
             ? View.IMPORTANT_FOR_ACCESSIBILITY_YES
@@ -173,4 +180,30 @@ static ImageView.ScaleType convertScaleType(int scaleType) {
         return ImageView.ScaleType.CENTER;
     }
   }
+
+  /**
+   * Updates the tooltip for an icon, handling API-level-specific behavior.
+   *
+   * <p>The tooltip is only set if the icon is focusable.
+   *
+   * <p>On API 26 and above, this method calls {@link
+   * android.view.View#setTooltipText(CharSequence)}. This is safe to use even with a custom {@link
+   * OnLongClickListener}.
+   *
+   * <p>On API levels below 26, this method uses {@link TooltipCompat#setTooltipText(View,
+   * CharSequence)}, but only if a custom {@link OnLongClickListener} has not been set. This is to
+   * avoid overwriting a developer-provided long-press listener. Thus, a custom {@link
+   * OnLongClickListener} will override the tooltip.
+   */
+  static void updateIconTooltip(
+      @NonNull CheckableImageButton iconView,
+      @Nullable OnLongClickListener onLongClickListener,
+      @Nullable CharSequence tooltip) {
+    final CharSequence tooltipText = iconView.isFocusable() ? tooltip : null;
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      iconView.setTooltipText(tooltipText);
+    } else if (onLongClickListener == null) {
+      TooltipCompat.setTooltipText(iconView, tooltipText);
+    }
+  }
 }

lib/java/com/google/android/material/textfield/StartCompoundLayout.java

@@ -26,6 +26,7 @@
 import static com.google.android.material.textfield.IconHelper.setIconOnClickListener;
 import static com.google.android.material.textfield.IconHelper.setIconOnLongClickListener;
 import static com.google.android.material.textfield.IconHelper.setIconScaleType;
+import static com.google.android.material.textfield.IconHelper.updateIconTooltip;
 
 import android.annotation.SuppressLint;
 import android.content.res.ColorStateList;
@@ -100,6 +101,11 @@ class StartCompoundLayout extends LinearLayout {
 
     addView(startIconView);
     addView(prefixTextView);
+
+    startIconView.setOnFocusableChangedListener(
+        (v, focusable) ->
+            updateIconTooltip(
+                startIconView, startIconOnLongClickListener, getStartIconContentDescription()));
   }
 
   private void initStartIconView(TintTypedArray a) {
@@ -254,6 +260,7 @@ boolean isStartIconCheckable() {
   void setStartIconContentDescription(@Nullable CharSequence startIconContentDescription) {
     if (getStartIconContentDescription() != startIconContentDescription) {
       startIconView.setContentDescription(startIconContentDescription);
+      updateIconTooltip(startIconView, startIconOnLongClickListener, startIconContentDescription);
     }
   }
 

tests/javatests/com/google/android/material/testutils/TestUtilsMatchers.java

@@ -25,6 +25,7 @@
 import android.graphics.drawable.Drawable;
 import android.os.Build;
 import androidx.appcompat.view.menu.MenuItemImpl;
+import android.text.TextUtils;
 import android.view.Gravity;
 import android.view.Menu;
 import android.view.View;
@@ -35,6 +36,7 @@
 import androidx.annotation.ColorInt;
 import androidx.annotation.IdRes;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.core.view.GravityCompat;
 import androidx.core.view.ViewCompat;
 import androidx.core.widget.TextViewCompat;
@@ -514,6 +516,21 @@ public boolean matchesSafely(View view) {
     };
   }
 
+  /** Returns a matcher that matches {@link View}s that are long-clickable. */
+  public static Matcher<View> isLongClickable() {
+    return new TypeSafeMatcher<View>() {
+      @Override
+      public void describeTo(Description description) {
+        description.appendText("is long-clickable");
+      }
+
+      @Override
+      public boolean matchesSafely(View view) {
+        return view.isLongClickable();
+      }
+    };
+  }
+
   /**
    * Returns a matcher that matches views which have a z-value greater than 0. Also matches if the
    * platform we're running on does not support z-values.
@@ -624,4 +641,30 @@ public boolean matchesSafely(View view) {
       }
     };
   }
+
+  /**
+   * Returns a matcher that matches {@link View}s with the specified tooltip text. Only works for
+   * API 26+
+   */
+  public static Matcher<View> withTooltipText(@Nullable final CharSequence text) {
+    return new BoundedMatcher<View, View>(View.class) {
+      @Override
+      public void describeTo(Description description) {
+        description.appendText("with tooltip text: ");
+        if (text == null) {
+          description.appendText("null");
+        } else {
+          description.appendText(text.toString());
+        }
+      }
+
+      @Override
+      protected boolean matchesSafely(View item) {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+          return false;
+        }
+        return TextUtils.equals(item.getTooltipText(), text);
+      }
+    };
+  }
 }

tests/javatests/com/google/android/material/testutils/TextInputLayoutActions.java

@@ -1025,4 +1025,24 @@ public void perform(UiController uiController, View view) {
       }
     };
   }
+
+  /** Sets end icon content description on {@link TextInputLayout} */
+  public static ViewAction setEndIconContentDescription(final CharSequence contentDescription) {
+    return new ViewAction() {
+      @Override
+      public Matcher<View> getConstraints() {
+        return isAssignableFrom(TextInputLayout.class);
+      }
+
+      @Override
+      public String getDescription() {
+        return "set end icon content description";
+      }
+
+      @Override
+      public void perform(UiController uiController, View view) {
+        ((TextInputLayout) view).setEndIconContentDescription(contentDescription);
+      }
+    };
+  }
 }