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 BadgeDrawable as a ViewOverlay to the desired anchor view using BadgeUtils#attachBadgeDrawable(BadgeDrawable, View, FrameLayout) (This helper class is currently experimental).
  • Update the BadgeDrawable BadgeDrawable's coordinates (center and bounds) based on its anchor view using updateBadgeCoordinates(View, FrameLayout). 
 BadgeDrawable badgeDrawable = BadgeDrawable.create(context);
 badgeDrawable.setVisible(true);
 BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);

For Pre API-18

Option 1: 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_badgeShapeAppearance  
Badge_badgeShapeAppearanceOverlay  
Badge_badgeTextAppearance  
Badge_badgeTextColor  
Badge_badgeWithTextShapeAppearance  
Badge_badgeWithTextShapeAppearanceOverlay  
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 BadgeDrawable with default values.

static BadgeDrawable createFromResource(Context context, int id)

Returns a BadgeDrawable from the given XML resource.

void draw(Canvas canvas)
int getAlpha()
int getBackgroundColor()

Returns this badge's background color.

int getBadgeGravity()
Locale getBadgeNumberLocale()

Returns the Locale used to show badge numbers.

int getBadgeTextColor()

Returns this badge's text color.

CharSequence getContentDescription()
FrameLayout getCustomBadgeParent()

Returns a FrameLayout that will set this BadgeDrawable as its foreground.

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 Locale used to show badge numbers.

void setBadgeTextColor(int badgeTextColor)

Sets this badge's text color.

void setBadgeWithTextShapeAppearance(int id)

Sets this badge with text's shape appearance resource.

void setBadgeWithTextShapeAppearanceOverlay(int id)

Sets this badge with text's shape appearance overlay resource.

void setBadgeWithoutTextShapeAppearance(int id)

Sets this badge without text's shape appearance resource.

void setBadgeWithoutTextShapeAppearanceOverlay(int id)

Sets this badge without text's shape appearance overlay resource.

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 setTextAppearance(int id)

Sets this badge's text appearance resource.

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 Drawable.setVisible(boolean, boolean) with the restart parameter hardcoded to false.

void updateBadgeCoordinates(View anchorView, ViewGroup customBadgeParent)

This method is deprecated. use updateBadgeCoordinates(View, FrameLayout) instead.

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_badgeShapeAppearance

Related methods:

Badge_badgeShapeAppearanceOverlay

Related methods:

Badge_badgeTextAppearance

Related methods:

Badge_badgeTextColor

Related methods:

Badge_badgeWithTextShapeAppearance

Related methods:

Badge_badgeWithTextShapeAppearanceOverlay

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

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

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

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.

setBadgeWithTextShapeAppearance

public void setBadgeWithTextShapeAppearance (int id)

Sets this badge with text's shape appearance resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance res id when there is text.

setBadgeWithTextShapeAppearanceOverlay

public void setBadgeWithTextShapeAppearanceOverlay (int id)

Sets this badge with text's shape appearance overlay resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance overlay res id when there is text.

setBadgeWithoutTextShapeAppearance

public void setBadgeWithoutTextShapeAppearance (int id)

Sets this badge without text's shape appearance resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance res id when there is no text.

setBadgeWithoutTextShapeAppearanceOverlay

public void setBadgeWithoutTextShapeAppearanceOverlay (int id)

Sets this badge without text's shape appearance overlay resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance overlay res id when there is no text.

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.

setTextAppearance

public void setTextAppearance (int id)

Sets this badge's text appearance resource.

Related XML Attributes:

Parameters
id int: This badge's text appearance res id.

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.