BadgeDrawable
public
class
BadgeDrawable
extends Drawable
| java.lang.Object | ||
| ↳ | android.graphics.drawable.Drawable | |
| ↳ | com.google.android.material.badge.BadgeDrawable | |
BadgeDrawable contains all the layout and draw logic for a badge.
You can use BadgeDrawable to display dynamic information such as a number of pending
requests in a BottomNavigationView. To
create an instance of BadgeDrawable, use create(Context) or createFromResource(Context, int). How to add and display a BadgeDrawable on top of its
anchor view depends on the API level:
For API 18+ (APIs supported by ViewOverlay)
- Add
BadgeDrawableas aViewOverlayto the desired anchor view using BadgeUtils#attachBadgeDrawable(BadgeDrawable, View, FrameLayout) (This helper class is currently experimental). - Update the
BadgeDrawable BadgeDrawable'scoordinates (center and bounds) based on its anchor view usingupdateBadgeCoordinates(View, FrameLayout).
BadgeDrawable badgeDrawable = BadgeDrawable.create(context); badgeDrawable.setVisible(true); BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);
For Pre API-18
- Set
BadgeDrawableas the foreground of the anchor view'sFrameLayoutancestor usingBadgeUtils.attachBadgeDrawable(BadgeDrawable, View, FrameLayout)(This helper class is currently experimental). - Update the
BadgeDrawable BadgeDrawable'scoordinates (center and bounds) based on its anchor view (relative to itsFrameLayoutancestor's coordinate space), usingupdateBadgeCoordinates(View, FrameLayout).
BadgeDrawable will dynamically create and wrap the anchor view in a FrameLayout, then insert the FrameLayout into the anchor view original position in the
view hierarchy. Same syntax as API 18+
BadgeDrawable badgeDrawable = BadgeDrawable.create(context); badgeDrawable.setVisible(true); BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);Option 2: If you do not want
BadgeDrawable to modify your view hierarchy, you can specify
a FrameLayout to display the badge instead.
BadgeDrawable badgeDrawable = BadgeDrawable.create(context); BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
By default, BadgeDrawable is aligned to the top and end edges of its anchor view (with
some offsets). Call 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 setHorizontalOffset(int), setVerticalOffset(int)
Note: This is still under development and may not support the full range of customization Material Android components generally support (e.g. themed attributes).
Summary
Nested classes | |
|---|---|
@interface |
BadgeDrawable.BadgeGravity
Position the badge can be set to. |
XML attributes | |
|---|---|
Badge_backgroundColor |
|
Badge_badgeTextColor |
|
Badge_maxCharacterCount |
|
Badge_number |
|
Constants | |
|---|---|
int |
BOTTOM_END
The badge is positioned along the bottom and end edges of its anchor view |
int |
BOTTOM_START
The badge is positioned along the bottom and start edges of its anchor view |
int |
TOP_END
The badge is positioned along the top and end edges of its anchor view |
int |
TOP_START
The badge is positioned along the top and start edges of its anchor view |
Public methods | |
|---|---|
void
|
clearNumber()
Resets any badge number so that a numberless badge will be displayed. |
static
BadgeDrawable
|
create(Context context)
Creates an instance of |
static
BadgeDrawable
|
createFromResource(Context context, int id)
Returns a |
void
|
draw(Canvas canvas)
|
int
|
getAlpha()
|
int
|
getBackgroundColor()
Returns this badge's background color. |
int
|
getBadgeGravity()
|
Locale
|
getBadgeNumberLocale()
Returns the |
int
|
getBadgeTextColor()
Returns this badge's text color. |
CharSequence
|
getContentDescription()
|
FrameLayout
|
getCustomBadgeParent()
Returns a |
int
|
getHorizontalOffset()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor. |
int
|
getHorizontalOffsetWithText()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge has text. |
int
|
getHorizontalOffsetWithoutText()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge does not have text (is a dot). |
int
|
getIntrinsicHeight()
Returns the height at which the badge would like to be laid out. |
int
|
getIntrinsicWidth()
Returns the width at which the badge would like to be laid out. |
int
|
getMaxCharacterCount()
Returns this badge's max character count. |
int
|
getNumber()
Returns this badge's number. |
int
|
getOpacity()
|
int
|
getVerticalOffset()
Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor. |
int
|
getVerticalOffsetWithText()
Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor when the badge has text. |
int
|
getVerticalOffsetWithoutText()
Returns how much (in pixels) this badge is being vertically offset towards the center of its anchor when this badge does not have text (is a dot). |
boolean
|
hasNumber()
Returns whether this badge will display a number. |
boolean
|
isStateful()
|
boolean
|
onStateChange(int[] state)
|
void
|
setAlpha(int alpha)
|
void
|
setBackgroundColor(int backgroundColor)
Sets this badge's background color. |
void
|
setBadgeGravity(int gravity)
Sets this badge's gravity with respect to its anchor view. |
void
|
setBadgeNumberLocale(Locale locale)
Sets the |
void
|
setBadgeTextColor(int badgeTextColor)
Sets this badge's text color. |
void
|
setColorFilter(ColorFilter colorFilter)
|
void
|
setContentDescriptionExceedsMaxBadgeNumberStringResource(int stringsResource)
|
void
|
setContentDescriptionNumberless(CharSequence charSequence)
|
void
|
setContentDescriptionQuantityStringsResource(int stringsResource)
|
void
|
setHorizontalOffset(int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor. |
void
|
setHorizontalOffsetWithText(int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge has text. |
void
|
setHorizontalOffsetWithoutText(int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge does not have text (is a dot). |
void
|
setMaxCharacterCount(int maxCharacterCount)
Sets this badge's max character count. |
void
|
setNumber(int number)
Sets this badge's number. |
void
|
setVerticalOffset(int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor. |
void
|
setVerticalOffsetWithText(int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge has text. |
void
|
setVerticalOffsetWithoutText(int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge does not have text (is a dot). |
void
|
setVisible(boolean visible)
Convenience wrapper method for |
void
|
updateBadgeCoordinates(View anchorView, ViewGroup customBadgeParent)
This method is deprecated.
use |
void
|
updateBadgeCoordinates(View anchorView, FrameLayout customBadgeParent)
Calculates and updates this badge's center coordinates based on its anchor's bounds. |
void
|
updateBadgeCoordinates(View anchorView)
Calculates and updates this badge's center coordinates based on its anchor's bounds. |
Inherited methods | |
|---|---|
XML attributes
Badge_backgroundColor
Related methods:
Badge_badgeTextColor
Related methods:
Badge_maxCharacterCount
Related methods:
Badge_number
Related methods:
Constants
BOTTOM_END
public static final int BOTTOM_END
The badge is positioned along the bottom and end edges of its anchor view
Constant Value: 8388693 (0x00800055)
BOTTOM_START
public static final int BOTTOM_START
The badge is positioned along the bottom and start edges of its anchor view
Constant Value: 8388691 (0x00800053)
TOP_END
public static final int TOP_END
The badge is positioned along the top and end edges of its anchor view
Constant Value: 8388661 (0x00800035)
TOP_START
public static final int TOP_START
The badge is positioned along the top and start edges of its anchor view
Constant Value: 8388659 (0x00800033)
Public methods
clearNumber
public void clearNumber ()
Resets any badge number so that a numberless badge will be displayed.
create
public static BadgeDrawable create (Context context)
Creates an instance of BadgeDrawable with default values.
| Parameters | |
|---|---|
context |
Context |
| Returns | |
|---|---|
BadgeDrawable |
|
createFromResource
public static BadgeDrawable createFromResource (Context context, int id)
Returns a BadgeDrawable from the given XML resource. All attributes from R.styleable.Badge and a custom style attribute are supported. A badge resource
may look like:
<badge
xmlns:app="http://schemas.android.com/apk/res-auto"
style="@style/Widget.MaterialComponents.Badge"
app:maxCharacterCount="2"/>
| Parameters | |
|---|---|
context |
Context |
id |
int |
| Returns | |
|---|---|
BadgeDrawable |
|
draw
public void draw (Canvas canvas)
| Parameters | |
|---|---|
canvas |
Canvas |
getAlpha
public int getAlpha ()
| Returns | |
|---|---|
int |
|
getBackgroundColor
public int getBackgroundColor ()
Returns this badge's background color.
Related XML Attributes:
| Returns | |
|---|---|
int |
|
See also:
getBadgeGravity
public int getBadgeGravity ()
| Returns | |
|---|---|
int |
|
getBadgeNumberLocale
public Locale getBadgeNumberLocale ()
Returns the Locale used to show badge numbers.
| Returns | |
|---|---|
Locale |
|
getBadgeTextColor
public int getBadgeTextColor ()
Returns this badge's text color.
Related XML Attributes:
| Returns | |
|---|---|
int |
|
See also:
getContentDescription
public CharSequence getContentDescription ()
| Returns | |
|---|---|
CharSequence |
|
getCustomBadgeParent
public FrameLayout getCustomBadgeParent ()
Returns a FrameLayout that will set this BadgeDrawable as its foreground.
| Returns | |
|---|---|
FrameLayout |
|
getHorizontalOffset
public int getHorizontalOffset ()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor.
This returns the horizontal offset for badges without text. If offset for badges with text
and without text are different consider using getHorizontalOffsetWithoutText() or getHorizontalOffsetWithText().
| Returns | |
|---|---|
int |
|
getHorizontalOffsetWithText
public int getHorizontalOffsetWithText ()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge has text.
| Returns | |
|---|---|
int |
|
getHorizontalOffsetWithoutText
public int getHorizontalOffsetWithoutText ()
Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge does not have text (is a dot).
| Returns | |
|---|---|
int |
|
getIntrinsicHeight
public int getIntrinsicHeight ()
Returns the height at which the badge would like to be laid out.
| Returns | |
|---|---|
int |
|
getIntrinsicWidth
public int getIntrinsicWidth ()
Returns the width at which the badge would like to be laid out.
| Returns | |
|---|---|
int |
|
getMaxCharacterCount
public int getMaxCharacterCount ()
Returns this badge's max character count.
Related XML Attributes:
| Returns | |
|---|---|
int |
|
See also:
getNumber
public int getNumber ()
Returns this badge's number. Only non-negative integer numbers will be returned because the setter clamps negative values to 0.
WARNING: Do not call this method if you are planning to compare to BADGE_NUMBER_NONE
Related XML Attributes:
| Returns | |
|---|---|
int |
|
See also:
getOpacity
public int getOpacity ()
| Returns | |
|---|---|
int |
|
getVerticalOffset
public int getVerticalOffset ()
Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor.
This returns the vertical offset for badges without text. If offset for badges with text and
without text are different consider using getVerticalOffsetWithoutText() or getVerticalOffsetWithText().
| Returns | |
|---|---|
int |
|
getVerticalOffsetWithText
public int getVerticalOffsetWithText ()
Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor when the badge has text.
| Returns | |
|---|---|
int |
|
getVerticalOffsetWithoutText
public int getVerticalOffsetWithoutText ()
Returns how much (in pixels) this badge is being vertically offset towards the center of its anchor when this badge does not have text (is a dot).
| Returns | |
|---|---|
int |
|
hasNumber
public boolean hasNumber ()
Returns whether this badge will display a number.
| Returns | |
|---|---|
boolean |
|
isStateful
public boolean isStateful ()
| Returns | |
|---|---|
boolean |
|
onStateChange
public boolean onStateChange (int[] state)
| Parameters | |
|---|---|
state |
int |
| Returns | |
|---|---|
boolean |
|
setAlpha
public void setAlpha (int alpha)
| Parameters | |
|---|---|
alpha |
int |
setBackgroundColor
public void setBackgroundColor (int backgroundColor)
Sets this badge's background color.
Related XML Attributes:
| Parameters | |
|---|---|
backgroundColor |
int: This badge's background color. |
setBadgeGravity
public void setBadgeGravity (int gravity)
Sets this badge's gravity with respect to its anchor view.
| Parameters | |
|---|---|
gravity |
int: Constant representing one of 4 possible BadgeDrawable.BadgeGravity values.
|
setBadgeNumberLocale
public void setBadgeNumberLocale (Locale locale)
Sets the Locale used to show badge numbers.
| Parameters | |
|---|---|
locale |
Locale |
setBadgeTextColor
public void setBadgeTextColor (int badgeTextColor)
Sets this badge's text color.
Related XML Attributes:
| Parameters | |
|---|---|
badgeTextColor |
int: This badge's text color. |
setColorFilter
public void setColorFilter (ColorFilter colorFilter)
| Parameters | |
|---|---|
colorFilter |
ColorFilter |
setContentDescriptionExceedsMaxBadgeNumberStringResource
public void setContentDescriptionExceedsMaxBadgeNumberStringResource (int stringsResource)
| Parameters | |
|---|---|
stringsResource |
int |
setContentDescriptionNumberless
public void setContentDescriptionNumberless (CharSequence charSequence)
| Parameters | |
|---|---|
charSequence |
CharSequence |
setContentDescriptionQuantityStringsResource
public void setContentDescriptionQuantityStringsResource (int stringsResource)
| Parameters | |
|---|---|
stringsResource |
int |
setHorizontalOffset
public void setHorizontalOffset (int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor.
This sets the horizontal offset for badges without text (dots) and with text.
| Parameters | |
|---|---|
px |
int: badge's horizontal offset
|
setHorizontalOffsetWithText
public void setHorizontalOffsetWithText (int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge has text.
| Parameters | |
|---|---|
px |
int: badge's horizontal offset when the badge has text.
|
setHorizontalOffsetWithoutText
public void setHorizontalOffsetWithoutText (int px)
Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge does not have text (is a dot).
| Parameters | |
|---|---|
px |
int: badge's horizontal offset when the badge does not have text
|
setMaxCharacterCount
public void setMaxCharacterCount (int maxCharacterCount)
Sets this badge's max character count.
Related XML Attributes:
| Parameters | |
|---|---|
maxCharacterCount |
int: This badge's max character count. |
setNumber
public void setNumber (int number)
Sets this badge's number. Only non-negative integer numbers are supported. If the number is
negative, it will be clamped to 0. The specified value will be displayed, unless its number of
digits exceeds maxCharacterCount in which case a truncated version will be shown.
Related XML Attributes:
| Parameters | |
|---|---|
number |
int: This badge's number. |
setVerticalOffset
public void setVerticalOffset (int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor.
This sets the vertical offset for badges both without text (dots) and with text.
| Parameters | |
|---|---|
px |
int: badge's vertical offset
|
setVerticalOffsetWithText
public void setVerticalOffsetWithText (int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge has text.
| Parameters | |
|---|---|
px |
int: badge's vertical offset when the badge has text.
|
setVerticalOffsetWithoutText
public void setVerticalOffsetWithoutText (int px)
Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge does not have text (is a dot).
| Parameters | |
|---|---|
px |
int: badge's vertical offset when the badge does not have text
|
setVisible
public void setVisible (boolean visible)
Convenience wrapper method for Drawable.setVisible(boolean, boolean) with the restart parameter hardcoded to false.
| Parameters | |
|---|---|
visible |
boolean |
updateBadgeCoordinates
public void updateBadgeCoordinates (View anchorView,
ViewGroup customBadgeParent)
This method is deprecated.
use updateBadgeCoordinates(View, FrameLayout) instead.
Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally
also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on
the center coordinates. For pre API-18, coordinates will be calculated relative to customBadgeParent because the BadgeDrawable will be set as the parent's foreground.
| Parameters | |
|---|---|
anchorView |
View: This badge's anchor. |
customBadgeParent |
ViewGroup: An optional parent view that will set this BadgeDrawable as
its foreground. |
updateBadgeCoordinates
public void updateBadgeCoordinates (View anchorView,
FrameLayout customBadgeParent)
Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally
also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on
the center coordinates.
For pre API-18, if no customBadgeParent is specified, optionally wrap the anchor in
a FrameLayout (if it's not done already) that will be inserted into the anchor's view
hierarchy and calculate the badge's coordinates the parent FrameLayout because the
BadgeDrawable will be set as the parent's foreground.
| Parameters | |
|---|---|
anchorView |
View: This badge's anchor. |
customBadgeParent |
FrameLayout: An optional parent view that will set this BadgeDrawable as
its foreground.
|
updateBadgeCoordinates
public void updateBadgeCoordinates (View anchorView)
Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally
also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on
the center coordinates.
For pre API-18, optionally wrap the anchor in a FrameLayout (if it's not done
already) that will be inserted into the anchor's view hierarchy and calculate the badge's
coordinates the parent FrameLayout because the BadgeDrawable will be set as the
parent's foreground.
| Parameters | |
|---|---|
anchorView |
View: This badge's anchor.
|
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2022-05-11 UTC.