[Badge] Deprecate bottom badge gravities and update docs and usages in catalog

PiperOrigin-RevId: 543527285

Author: imhappi

catalog/java/io/material/catalog/bottomnav/BottomNavigationDemoFragment.java

@@ -50,8 +50,6 @@ public abstract class BottomNavigationDemoFragment extends DemoFragment {
       new int[] {
         BadgeDrawable.TOP_END,
         BadgeDrawable.TOP_START,
-        BadgeDrawable.BOTTOM_END,
-        BadgeDrawable.BOTTOM_START
       };
 
   private int numVisibleChildren = 3;

catalog/java/io/material/catalog/bottomnav/res/values/arrays.xml

@@ -19,7 +19,5 @@
   <string-array name="cat_bottom_nav_badge_gravity_titles">
     <item>@string/cat_bottom_nav_badge_gravity_top_end</item>
     <item>@string/cat_bottom_nav_badge_gravity_top_start</item>
-    <item>@string/cat_bottom_nav_badge_gravity_bottom_end</item>
-    <item>@string/cat_bottom_nav_badge_gravity_bottom_start</item>
   </string-array>
 </resources>

catalog/java/io/material/catalog/bottomnav/res/values/strings.xml

@@ -53,8 +53,6 @@
 
   <string name="cat_bottom_nav_badge_gravity_top_end">Top end</string>
   <string name="cat_bottom_nav_badge_gravity_top_start">Top start</string>
-  <string name="cat_bottom_nav_badge_gravity_bottom_end">Bottom end</string>
-  <string name="cat_bottom_nav_badge_gravity_bottom_start">Bottom start</string>
 
   <string name="cat_bottom_nav_badge_gravity_spinner_label">Badge gravity</string>
   <string name="cat_bottom_nav_label_active_bold" translatable="false">Bold active label</string>

catalog/java/io/material/catalog/navigationrail/NavigationRailDemoFragment.java

@@ -50,8 +50,6 @@ public class NavigationRailDemoFragment extends DemoFragment {
       new int[] {
         BadgeDrawable.TOP_END,
         BadgeDrawable.TOP_START,
-        BadgeDrawable.BOTTOM_END,
-        BadgeDrawable.BOTTOM_START
       };
 
   private int numVisibleChildren = 3;

catalog/java/io/material/catalog/navigationrail/res/values/arrays.xml

@@ -19,7 +19,5 @@
   <string-array name="cat_navigation_rail_badge_gravity_titles">
     <item>@string/cat_navigation_rail_badge_gravity_top_end</item>
     <item>@string/cat_navigation_rail_badge_gravity_top_start</item>
-    <item>@string/cat_navigation_rail_badge_gravity_bottom_end</item>
-    <item>@string/cat_navigation_rail_badge_gravity_bottom_start</item>
   </string-array>
 </resources>

catalog/java/io/material/catalog/navigationrail/res/values/strings.xml

@@ -89,10 +89,6 @@
           description="Label for the option that will cause badges to be positioned at the end, above the icon. [CHAR_LIMIT=50]">Top end</string>
   <string name="cat_navigation_rail_badge_gravity_top_start"
           description="Label for the option that will cause badges to be positioned at the start, above the icon. [CHAR_LIMIT=50]">Top start</string>
-  <string name="cat_navigation_rail_badge_gravity_bottom_end"
-          description="Label for the option that will cause badges to be positioned at the end, below the icon. [CHAR_LIMIT=50]">Bottom end</string>
-  <string name="cat_navigation_rail_badge_gravity_bottom_start"
-          description="Label for the option that will cause badges to be positioned at starting, below the icon. [CHAR_LIMIT=50]">Bottom start</string>
   <string name="cat_navigation_rail_label_active_bold"
           description="Label for controlling whether the active label is bold. [CHAR_LIMIT=50]" translatable="false">Bold active label</string>
 

docs/components/BadgeDrawable.md

@@ -76,10 +76,11 @@ can specify a `FrameLayout` to display the badge instead.
 
 ### `BadgeDrawable` Gravity Modes
 
-`BadgeDrawable` provides four pre-packaged gravity modes that control how the
-badge aligns with its anchor view. By default (`TOP_END`) badge aligns with the
-top and end edges of the anchor (with some offsets). The other options are
-`TOP_START`, `BOTTOM_START` and `BOTTOM_END`.
+`BadgeDrawable` offers two gravity modes to control how the badge aligns with
+its anchor view. By default, (`TOP_END`) badge aligns with the top and end edges
+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
 

lib/java/com/google/android/material/badge/BadgeDrawable.java

@@ -30,6 +30,7 @@
 import android.graphics.Rect;
 import android.graphics.drawable.Drawable;
 import android.text.TextUtils;
+import android.util.Log;
 import android.view.Gravity;
 import android.view.View;
 import android.view.ViewGroup;
@@ -116,15 +117,17 @@
  * </pre>
  *
  * <p>By default, {@code BadgeDrawable} is aligned to the top and end edges of its anchor view (with
- * some offsets). Call {@link #setBadgeGravity(int)} to change it to one of the other supported
- * modes. To adjust the badge's offsets w.r.t. the anchor's center, use {@link
+ * some offsets). Call {@link #setBadgeGravity(int)} to change it to {@link #TOP_START}, the other
+ * supported mode. To adjust the badge's offsets w.r.t. the anchor's center, use {@link
  * BadgeDrawable#setHorizontalOffset(int)}, {@link BadgeDrawable#setVerticalOffset(int)}
  *
  * <p>Note: This is still under development and may not support the full range of customization
  * Material Android components generally support (e.g. themed attributes).
  */
 public class BadgeDrawable extends Drawable implements TextDrawableDelegate {
 
+  private static final String TAG = "Badge";
+
   /** Position the badge can be set to. */
   @IntDef({
       TOP_END,
@@ -141,11 +144,21 @@ public class BadgeDrawable extends Drawable implements TextDrawableDelegate {
   /** The badge is positioned along the top and start edges of its anchor view */
   public static final int TOP_START = Gravity.TOP | Gravity.START;
 
-  /** The badge is positioned along the bottom and end edges of its anchor view */
-  public static final int BOTTOM_END = Gravity.BOTTOM | Gravity.END;
+  /**
+   * The badge is positioned along the bottom and end edges of its anchor view
+   *
+   * @deprecated Bottom badge gravities are deprecated in favor of top gravities; use {@link
+   *     #TOP_START} or {@link #TOP_END} instead.
+   */
+  @Deprecated public static final int BOTTOM_END = Gravity.BOTTOM | Gravity.END;
 
-  /** The badge is positioned along the bottom and start edges of its anchor view */
-  public static final int BOTTOM_START = Gravity.BOTTOM | Gravity.START;
+  /**
+   * The badge is positioned along the bottom and start edges of its anchor view
+   *
+   * @deprecated Bottom badge gravities are deprecated in favor of top gravities; use {@link
+   *     #TOP_START} or {@link #TOP_END} instead.
+   */
+  @Deprecated public static final int BOTTOM_START = Gravity.BOTTOM | Gravity.START;
 
   @StyleRes private static final int DEFAULT_STYLE = R.style.Widget_MaterialComponents_Badge;
   @AttrRes private static final int DEFAULT_THEME_ATTR = R.attr.badgeStyle;
@@ -664,9 +677,13 @@ public int getBadgeGravity() {
   /**
    * Sets this badge's gravity with respect to its anchor view.
    *
-   * @param gravity Constant representing one of 4 possible {@link BadgeGravity} values.
+   * @param gravity Constant representing one of the possible {@link BadgeGravity} values. There are
+   *     two recommended gravities: {@link #TOP_START} and {@link #TOP_END}.
    */
   public void setBadgeGravity(@BadgeGravity int gravity) {
+    if (gravity == BOTTOM_START || gravity == BOTTOM_END) {
+      Log.w(TAG, "Bottom badge gravities are deprecated; please use a top gravity instead.");
+    }
     if (state.getBadgeGravity() != gravity) {
       state.setBadgeGravity(gravity);
       onBadgeGravityUpdated();