Android APIs
public class

RippleDrawable

extends LayerDrawable
java.lang.Object
   ↳ android.graphics.drawable.Drawable
     ↳ android.graphics.drawable.LayerDrawable
       ↳ android.graphics.drawable.RippleDrawable

Class Overview

Drawable that shows a ripple effect in response to state changes. The anchoring position of the ripple for a given state may be specified by calling setHotspot(float, float) with the corresponding state attribute identifier.

A touch feedback drawable may contain multiple child layers, including a special mask layer that is not drawn to the screen. A single layer may be set as the mask by specifying its android:id value as mask. 

 <!-- A red ripple masked against an opaque rectangle. --/>
 <ripple android:color="#ffff0000">
   <item android:id="@android:id/mask"
         android:drawable="#ffffffff" />
 <ripple />

If a mask layer is set, the ripple effect will be masked against that layer before it is drawn over the composite of the remaining child layers.

If no mask layer is set, the ripple effect is masked against the composite of the child layers. 

 <!-- A blue ripple drawn atop a green rectangle. --/>
 <ripple android:color="#ff00ff00">
   <item android:drawable="#ff0000ff" />
 <ripple />

 <!-- A red ripple drawn atop a drawable resource. --/>
 <ripple android:color="#ff00ff00">
   <item android:drawable="@drawable/my_drawable" />
 <ripple />

If no child layers or mask is specified and the ripple is set as a View background, the ripple will be drawn atop the first available parent background within the View's hierarchy. In this case, the drawing region may extend outside of the Drawable bounds. 

 <!-- An unbounded green ripple. --/>
 <ripple android:color="#ff0000ff" />

Summary

XML Attributes
Attribute Name Related Method Description
android:color The color to use for ripple effects. 
[Expand]
Inherited XML Attributes
From class android.graphics.drawable.LayerDrawable
[Expand]
Inherited Constants
From class android.graphics.drawable.LayerDrawable
Public Constructors
RippleDrawable(Drawable content, Drawable mask)
Creates a new ripple drawable with the specified content and mask drawables.
Public Methods
void applyTheme(Resources.Theme t)
Applies the specified theme to this Drawable and its children.
boolean canApplyTheme()
void draw(Canvas canvas)
Draw in its bounds (set via setBounds) respecting optional effects such as alpha (set via setAlpha) and color filter (set via setColorFilter).
Drawable.ConstantState getConstantState()
Return a Drawable.ConstantState instance that holds the shared state of this Drawable.
Rect getDirtyBounds()
Return the drawable's dirty bounds Rect.
int getOpacity()
Return the opacity/transparency of this Drawable.
void inflate(Resources r, XmlPullParser parser, AttributeSet attrs, Resources.Theme theme)
Inflate this Drawable from an XML resource optionally styled by a theme.
boolean isStateful()
Indicates whether this drawable will change its appearance based on state.
void setAlpha(int alpha)
Specify an alpha value for the drawable.
void setColor(ColorStateList color)
void setColorFilter(ColorFilter cf)
Specify an optional color filter for the drawable.
boolean setDrawableByLayerId(int id, Drawable drawable)
Sets (or replaces) the Drawable for the layer with the given id.
void setHotspot(float x, float y)
Specifies the hotspot's location within the drawable.
void setHotspotBounds(int left, int top, int right, int bottom)
Sets the bounds to which the hotspot is constrained, if they should be different from the drawable bounds.
void setPaddingMode(int mode)
Specifies how layer padding should affect the bounds of subsequent layers.
boolean setVisible(boolean visible, boolean restart)
Set whether this Drawable is visible.
Protected Methods
void onBoundsChange(Rect bounds)
Override this in your subclass to change appearance if you vary based on the bounds.
boolean onStateChange(int[] stateSet)
Override this in your subclass to change appearance if you recognize the specified state.
[Expand]
Inherited Methods
From class android.graphics.drawable.LayerDrawable
From class android.graphics.drawable.Drawable
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback

XML Attributes

android:color

The color to use for ripple effects. This attribute is required.

Must be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol color.

Related Methods

Public Constructors

public RippleDrawable (Drawable content, Drawable mask)

Creates a new ripple drawable with the specified content and mask drawables.

Parameters
content The content drawable, may be null
mask The mask drawable, may be null

Public Methods

public void applyTheme (Resources.Theme t)

Applies the specified theme to this Drawable and its children.

public boolean canApplyTheme ()

public void draw (Canvas canvas)

Draw in its bounds (set via setBounds) respecting optional effects such as alpha (set via setAlpha) and color filter (set via setColorFilter).

Parameters
canvas The canvas to draw into

public Drawable.ConstantState getConstantState ()

Return a Drawable.ConstantState instance that holds the shared state of this Drawable.

Returns
  • The ConstantState associated to that Drawable.

public Rect getDirtyBounds ()

Return the drawable's dirty bounds Rect. Note: for efficiency, the returned object may be the same object stored in the drawable (though this is not guaranteed).

By default, this returns the full drawable bounds. Custom drawables may override this method to perform more precise invalidation.

Returns
  • The dirty bounds of this drawable

public int getOpacity ()

Return the opacity/transparency of this Drawable. The returned value is one of the abstract format constants in PixelFormat: UNKNOWN, TRANSLUCENT, TRANSPARENT, or OPAQUE.

Generally a Drawable should be as conservative as possible with the value it returns. For example, if it contains multiple child drawables and only shows one of them at a time, if only one of the children is TRANSLUCENT and the others are OPAQUE then TRANSLUCENT should be returned. You can use the method resolveOpacity(int, int) to perform a standard reduction of two opacities to the appropriate single output.

Note that the returned value does not take into account a custom alpha or color filter that has been applied by the client through the setAlpha(int) or setColorFilter(ColorFilter) methods.

Returns
  • int The opacity class of the Drawable.

public void inflate (Resources r, XmlPullParser parser, AttributeSet attrs, Resources.Theme theme)

Inflate this Drawable from an XML resource optionally styled by a theme.

Parameters
r Resources used to resolve attribute values
parser XML parser from which to inflate this Drawable
attrs Base set of attribute values
theme Theme to apply, may be null
Throws
XmlPullParserException
IOException

public boolean isStateful ()

Indicates whether this drawable will change its appearance based on state. Clients can use this to determine whether it is necessary to calculate their state and call setState.

Returns
  • True if this drawable changes its appearance based on state, false otherwise.

public void setAlpha (int alpha)

Specify an alpha value for the drawable. 0 means fully transparent, and 255 means fully opaque.

public void setColor (ColorStateList color)

public void setColorFilter (ColorFilter cf)

Specify an optional color filter for the drawable. Pass null to remove any existing color filter.

Parameters
cf the color filter to apply, or null to remove the existing color filter

public boolean setDrawableByLayerId (int id, Drawable drawable)

Sets (or replaces) the Drawable for the layer with the given id.

Parameters
id The layer ID to search for.
drawable The replacement Drawable.
Returns
  • Whether the Drawable was replaced (could return false if the id was not found).

public void setHotspot (float x, float y)

Specifies the hotspot's location within the drawable.

Parameters
x The X coordinate of the center of the hotspot
y The Y coordinate of the center of the hotspot

public void setHotspotBounds (int left, int top, int right, int bottom)

Sets the bounds to which the hotspot is constrained, if they should be different from the drawable bounds.

public void setPaddingMode (int mode)

Specifies how layer padding should affect the bounds of subsequent layers. The default and recommended value for RippleDrawable is PADDING_MODE_STACK.

Parameters
mode padding mode, one of:
See Also

public boolean setVisible (boolean visible, boolean restart)

Set whether this Drawable is visible. This generally does not impact the Drawable's behavior, but is a hint that can be used by some Drawables, for example, to decide whether run animations.

Parameters
visible Set to true if visible, false if not.
restart You can supply true here to force the drawable to behave as if it has just become visible, even if it had last been set visible. Used for example to force animations to restart.
Returns
  • boolean Returns true if the new visibility is different than its previous state.

Protected Methods

protected void onBoundsChange (Rect bounds)

Override this in your subclass to change appearance if you vary based on the bounds.

protected boolean onStateChange (int[] stateSet)

Override this in your subclass to change appearance if you recognize the specified state.

Returns
  • Returns true if the state change has caused the appearance of the Drawable to change (that is, it needs to be drawn), else false if it looks the same and there is no need to redraw it since its last state.