Added in API level 21

RippleDrawable

open class RippleDrawable : LayerDrawable
kotlin.Any
   ↳ android.graphics.drawable.Drawable
   ↳ android.graphics.drawable.LayerDrawable
   ↳ android.graphics.drawable.RippleDrawable

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 from XML by specifying its android:id value as android.R.id#mask. At run time, a single layer may be set as the mask using setId(..., android.R.id.mask) or an existing mask layer may be replaced using setDrawableByLayerId(android.R.id.mask, ...).

<code>&lt;!-- A red ripple masked against an opaque rectangle. --&gt;
  &lt;ripple android:color="#ffff0000"&gt;
    &lt;item android:id="@android:id/mask"
          android:drawable="@android:color/white" /&gt;
  &lt;/ripple&gt;</code>

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.

<code>&lt;!-- A green ripple drawn atop a black rectangle. --&gt;
  &lt;ripple android:color="#ff00ff00"&gt;
    &lt;item android:drawable="@android:color/black" /&gt;
  &lt;/ripple&gt;
 
  &lt;!-- A blue ripple drawn atop a drawable resource. --&gt;
  &lt;ripple android:color="#ff0000ff"&gt;
    &lt;item android:drawable="@drawable/my_drawable" /&gt;
  &lt;/ripple&gt;</code>

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.

<code>&lt;!-- An unbounded red ripple. --&gt;
  &lt;ripple android:color="#ffff0000" /&gt;</code>

Summary

XML attributes
android:color The color to use for ripple effects.
Inherited XML attributes
Constants
static Int

Radius value that specifies the ripple radius should be computed based on the size of the ripple's container.

Inherited constants
Public constructors
RippleDrawable(color: ColorStateList, content: Drawable?, mask: Drawable?)

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

Public methods
open Unit

Applies the specified theme to this Drawable and its children.

open Boolean

open Unit
draw(canvas: Canvas)

Optimized for drawing ripples with a mask layer and optional content.

open Drawable.ConstantState?

open Rect

open ColorStateList

open Unit

open Int

open Unit
getOutline(outline: Outline)

Populates outline with the first available layer outline, excluding the mask layer.

open Int

open Boolean

open Unit
inflate(r: Resources, parser: XmlPullParser, attrs: AttributeSet, theme: Resources.Theme?)

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

open Unit

open Boolean

open Unit

open Drawable

open Unit

Sets the ripple color.

open Boolean
setDrawableByLayerId(id: Int, drawable: Drawable!)

open Unit

Sets the ripple effect color.

open Unit

open Unit
setHotspotBounds(left: Int, top: Int, right: Int, bottom: Int)

open Unit

Specifies how layer padding should affect the bounds of subsequent layers.

open Unit
setRadius(radius: Int)

Sets the radius in pixels of the fully expanded ripple.

open Boolean
setVisible(visible: Boolean, restart: Boolean)

Protected methods
open Unit

open Boolean

Inherited functions

XML attributes

android:color

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

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

Constants

RADIUS_AUTO

Added in API level 23
static val RADIUS_AUTO: Int

Radius value that specifies the ripple radius should be computed based on the size of the ripple's container.

Value: -1

Public constructors

RippleDrawable

Added in API level 21
RippleDrawable(
    color: ColorStateList,
    content: Drawable?,
    mask: Drawable?)

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

Parameters
color ColorStateList: The ripple color This value cannot be null.
content Drawable?: The content drawable, may be null
mask Drawable?: The mask drawable, may be null

Public methods

applyTheme

Added in API level 21
open fun applyTheme(t: Resources.Theme): Unit

Applies the specified theme to this Drawable and its children.

Parameters
t Resources.Theme: This value cannot be null.

canApplyTheme

Added in API level 21
open fun canApplyTheme(): Boolean

draw

Added in API level 21
open fun draw(canvas: Canvas): Unit

Optimized for drawing ripples with a mask layer and optional content.

Parameters
canvas Canvas: This value cannot be null.

getConstantState

Added in API level 21
open fun getConstantState(): Drawable.ConstantState?
Return
Drawable.ConstantState? The ConstantState associated to that Drawable. This value may be null.

getDirtyBounds

Added in API level 21
open fun getDirtyBounds(): Rect
Return
Rect The dirty bounds of this drawable This value cannot be null.

getEffectColor

Added in API level 31
open fun getEffectColor(): ColorStateList
Return
ColorStateList The ripple effect color as a color state list. This value cannot be null.

getHotspotBounds

Added in API level 23
open fun getHotspotBounds(outRect: Rect): Unit
Parameters
outRect Rect: the rect to populate with the hotspot bounds This value cannot be null.

getOutline

Added in API level 21
open fun getOutline(outline: Outline): Unit

Populates outline with the first available layer outline, excluding the mask layer.

Parameters
outline Outline: Outline in which to place the first available layer outline This value cannot be null.

getRadius

Added in API level 23
open fun getRadius(): Int
Return
Int the radius in pixels of the fully expanded ripple if an explicit radius has been set, or RADIUS_AUTO if the radius is computed based on the container size

hasFocusStateSpecified

Added in API level 31
open fun hasFocusStateSpecified(): Boolean
Return
Boolean true if android.R.attr#state_focused is specified for this drawable.

inflate

Added in API level 21
open fun inflate(
    r: Resources,
    parser: XmlPullParser,
    attrs: AttributeSet,
    theme: Resources.Theme?
): Unit

Inflate this Drawable from an XML resource optionally styled by a theme. This can't be called more than once for each Drawable. Note that framework may have called this once to create the Drawable instance from XML resource.

Parameters
r Resources: This value cannot be null.
parser XmlPullParser: This value cannot be null.
attrs AttributeSet: This value cannot be null.
theme Resources.Theme?: This value may be null.
Exceptions
org.xmlpull.v1.XmlPullParserException
java.io.IOException

invalidateSelf

Added in API level 21
open fun invalidateSelf(): Unit

isStateful

Added in API level 21
open fun isStateful(): Boolean
Return
Boolean True if this drawable changes its appearance based on state, false otherwise.

jumpToCurrentState

Added in API level 21
open fun jumpToCurrentState(): Unit

mutate

Added in API level 21
open fun mutate(): Drawable
Return
Drawable This drawable. This value cannot be null.

setColor

Added in API level 21
open fun setColor(color: ColorStateList): Unit

Sets the ripple color.

Parameters
color ColorStateList: Ripple color as a color state list. This value cannot be null.

setDrawableByLayerId

Added in API level 21
open fun setDrawableByLayerId(
    id: Int,
    drawable: Drawable!
): Boolean
Parameters
id Int: The layer ID to search for.
drawable Drawable!: The replacement Drawable.
Return
Boolean Whether the Drawable was replaced (could return false if the id was not found).

setEffectColor

Added in API level 31
open fun setEffectColor(color: ColorStateList): Unit

Sets the ripple effect color.

Parameters
color ColorStateList: Ripple color as a color state list. This value cannot be null.

setHotspot

Added in API level 21
open fun setHotspot(
    x: Float,
    y: Float
): Unit
Parameters
x Float: The X coordinate of the center of the hotspot
y Float: The Y coordinate of the center of the hotspot

setHotspotBounds

Added in API level 21
open fun setHotspotBounds(
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
): Unit
Parameters
left Int: position in pixels of the left bound
top Int: position in pixels of the top bound
right Int: position in pixels of the right bound
bottom Int: position in pixels of the bottom bound

setPaddingMode

Added in API level 21
open fun setPaddingMode(mode: Int): Unit

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

Parameters
mode Int: padding mode, one of:

setRadius

Added in API level 23
open fun setRadius(radius: Int): Unit

Sets the radius in pixels of the fully expanded ripple.

Parameters
radius Int: ripple radius in pixels, or RADIUS_AUTO to compute the radius based on the container size

setVisible

Added in API level 21
open fun setVisible(
    visible: Boolean,
    restart: Boolean
): Boolean
Parameters
visible Boolean: Set to true if visible, false if not.
restart Boolean: 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.
Return
Boolean boolean Returns true if the new visibility is different than its previous state.

Protected methods

onBoundsChange

Added in API level 21
protected open fun onBoundsChange(bounds: Rect): Unit
Parameters
bounds Rect: This value cannot be null.

onStateChange

Added in API level 21
protected open fun onStateChange(stateSet: IntArray): Boolean
Parameters
state This value cannot be null.
Return
Boolean 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.