[Badge] Deprecate autoAdjustToGrandparentBounds attribute since now…

… badges automatically move within first ancestor view that does not clip children PiperOrigin-RevId: 630215388
material-components · May 3, 2024 · 0d265b7 · 0d265b7
1 parent 8f8c6ee
commit 0d265b7
Show file tree

Hide file tree

Showing 5 changed files with 21 additions and 8 deletions.
diff --git a/docs/components/BadgeDrawable.md b/docs/components/BadgeDrawable.md
@@ -79,7 +79,7 @@ Option 2: If you do not want `BadgeDrawable` to modify your view hierarchy, you
 can specify a `FrameLayout` to display the badge instead.
 
 ```java
-* BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
+BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
 ```
 
 ### `BadgeDrawable` Gravity Modes
@@ -90,13 +90,17 @@ of the anchor (with some offsets). Alternatively, you can use `TOP_START` to
 align the badge with the top and start edges of the anchor. Note that
 `BOTTOM_START` and `BOTTOM_END` are deprecated and not recommended for use.
 
-### `BadgeDrawable` center offsets
+### `BadgeDrawable` placement and offsets
 
 By default, `BadgeDrawable` is aligned with the top and end edges of its anchor
 view (with some offsets if `offsetAlignmentMode` is `legacy`). Call `setBadgeGravity(int)` to change it to one of the
 other supported modes. To adjust the badge's offsets relative to the anchor's
 center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 
+Regardless of offsets, badges are automatically moved to within the bounds of
+its first ancestor view that does not clip its children, to ensure that the
+badge is not clipped if there is enough space.
+
 ### `BadgeDrawable` Attributes
 
 | Feature | Relevant attributes |
@@ -114,7 +118,6 @@ center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
 | Horizontal Padding | `app:badgeWidePadding` |
 | Vertical Padding | `app:badgeVerticalPadding` |
 | Large Font Vertical Offset| `app:largeFontVerticalOffsetAdjustment` |
-| Auto Adjust | `app:autoAdjustToWithinGrandparentBounds` |
 
 **Note:** If both `app:badgeText` and `app:number` are specified, the badge label will be `app:badgeText`.
 

diff --git a/lib/java/com/google/android/material/badge/BadgeDrawable.java b/lib/java/com/google/android/material/badge/BadgeDrawable.java
@@ -1078,12 +1078,15 @@ int getAdditionalVerticalOffset() {
  }
 
  /**
- * Sets whether or not to auto adjust the badge placement to within the badge anchor's
- * grandparent view.
+ * Sets whether or not to auto adjust the badge placement to within the badge anchor's grandparent
+ * view.
  *
- * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within
- * the anchor's grandparent view.
+ * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within the anchor's
+ * grandparent view.
+ * @deprecated Badges now automatically adjust their bounds within the first ancestor view that *
+ * clips its children.
  */
+ @Deprecated
  public void setAutoAdjustToWithinGrandparentBounds(boolean autoAdjustToWithinGrandparentBounds) {
  if (state.isAutoAdjustedToGrandparentBounds() == autoAdjustToWithinGrandparentBounds) {
  return;

diff --git a/lib/java/com/google/android/material/badge/BadgeState.java b/lib/java/com/google/android/material/badge/BadgeState.java
@@ -604,10 +604,14 @@ void setNumberLocale(Locale locale) {
  currentState.numberLocale = locale;
  }
 
+ /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+ @Deprecated
  boolean isAutoAdjustedToGrandparentBounds() {
  return currentState.autoAdjustToWithinGrandparentBounds;
  }
 
+ /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+ @Deprecated
  void setAutoAdjustToGrandparentBounds(boolean autoAdjustToGrandparentBounds) {
  overridingState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;
  currentState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;

diff --git a/lib/java/com/google/android/material/badge/res-public/values/public.xml b/lib/java/com/google/android/material/badge/res-public/values/public.xml
@@ -37,6 +37,8 @@
  <public name="badgeShapeAppearance" type="attr"/>
  <public name="badgeWithTextShapeAppearance" type="attr"/>
  <public name="badgeShapeAppearanceOverlay" type="attr"/>
+ <!-- Deprecated. Badges are automatically moved to within first ancestor
+ that clips its children. -->
  <public name="autoAdjustToWithinGrandparentBounds" type="attr"/>
  <public name="badgeWithTextShapeAppearanceOverlay" type="attr"/>
  <public name="Widget.MaterialComponents.Badge" type="style"/>

diff --git a/lib/java/com/google/android/material/badge/res/values/attrs.xml b/lib/java/com/google/android/material/badge/res/values/attrs.xml
@@ -98,7 +98,8 @@
  attribute determines how much to shift the normal vertical offset by. -->
  <attr name="largeFontVerticalOffsetAdjustment" format="dimension"/>
  <!-- Automatically move the badge so it is within the anchor view's
- grandparent's bounds. -->
+ grandparent's bounds. Deprecated, badges are now automatically moved to
+ within the first ancestor that clips its children. -->
  <attr name="autoAdjustToWithinGrandparentBounds" format="boolean"/>
  </declare-styleable>