Skip to content

Latest commit

 

History

History
119 lines (90 loc) · 6.86 KB

BadgeDrawable.md

File metadata and controls

119 lines (90 loc) · 6.86 KB
Raw

BadgeDrawable

Using badges

Badge Badge with number Badge with a maximum character count
badge_icon badge_with_number_99 badge_with_999+

Note: This component is still under development and may not support the full range of customization Material Android components generally support, for instance, themed attributes.

A BadgeDrawable represents dynamic information such as a number of pending requests in a BottomNavigationView or TabLayout.

Design & API Documentation

Usage

Create an instance of BadgeDrawable by calling create(Context) or createFromAttributes(Context, AttributeSet, int, int)}.

The approach used to add and display a BadgeDrawable on top of its anchor view depends on the API level:

In API 18+ (APIs supported by ViewOverlay)

  1. Add BadgeDrawable as a ViewOverlay to the desired anchor view.
  2. Update the BadgeDrawable's coordinates (center and bounds) based on its anchor view using #updateBadgeCoordinates(View).

Both steps have been encapsulated in a util method:

BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);

In Pre API-18

  1. Set BadgeDrawable as the foreground of the anchor view's FrameLayout ancestor.
  2. Update the BadgeDrawable's coordinates (center and bounds) based on its anchor view, relative to its FrameLayout ancestor's coordinate space.

Option 1: BadgeDrawable will dynamically create and wrap the anchor view in a FrameLayout, then insert the FrameLayout into the original anchor view position in the view hierarchy. Same syntax as API 18+

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.

* BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);

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 center 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)

BadgeDrawable Attributes

Feature Relevant attributes
Color app:backgroundColor
app:badgeTextColor
Width app:badgeWidth
app:badgeWithTextWidth
Height app:badgeHeight
app:badgeWithTextHeight
Shape app:badgeShapeAppearance
app:badgeShapeAppearanceOverlay
app:badgeWithTextShapeAppearance
app:badgeWithTextShapeAppearanceOverlay
Label app:badgeText (for text)
app:number (for numbers)
Label Length app:maxCharacterCount (for all text)
app:maxNumber (for numbers only)
Label Text Color app:badgeTextColor
Label Text Appearance app:badgeTextAppearance
Badge Gravity app:badgeGravity
Offset Alignment app:offsetAlignmentMode
Horizontal Padding app:badgeWidePadding
Vertical Padding app:badgeVerticalPadding
Auto Adjust app:autoAdjustToWithinGrandparentBounds

Note: If both app:badgeText and app:number are specified, the badge label will be app:badgeText.

Talkback Support

BadgeDrawable provides a getter for its content description, which is based on the displayed number or text (if any). To specify the content description, the developer is provided with the following methods:

  • setContentDescriptionForText(CharSequence)
  • setContentDescriptionQuantityStringsResource(@PluralsRes int)
  • setContentDescriptionExceedsMaxBadgeNumberStringResource(@StringRes int)
  • setContentDescriptionNumberless(CharSequence)