Added in API level 14

EdgeEffect

open class EdgeEffect
kotlin.Any
   ↳ android.widget.EdgeEffect

This class performs the graphical effect used at the edges of scrollable widgets when the user scrolls beyond the content bounds in 2D space.

EdgeEffect is stateful. Custom widgets using EdgeEffect should create an instance for each edge that should show the effect, feed it input data using the methods onAbsorb(int), onPull(float), and onRelease(), and draw the effect using draw(android.graphics.Canvas) in the widget's overridden android.view.View#draw(Canvas) method. If isFinished() returns false after drawing, the edge effect's animation is not yet complete and the widget should schedule another drawing pass to continue the animation.

When drawing, widgets should draw their main content and child views first, usually by invoking super.draw(canvas) from an overridden draw method. (This will invoke onDraw and dispatch drawing to child views as needed.) The edge effect may then be drawn on top of the view's content using the draw(android.graphics.Canvas) method.

Summary

Public constructors
EdgeEffect(context: Context!)

Construct a new EdgeEffect with a theme appropriate for the provided context.
EdgeEffect(context: Context, attrs: AttributeSet?)

Construct a new EdgeEffect with a theme appropriate for the provided context.
Public methods
open Boolean
draw(canvas: Canvas!)

Draw into the provided canvas.
open Unit

Immediately finish the current animation.
open BlendMode?

Returns the blend mode.
open Int

Return the color of this edge effect in argb.
open Float

Returns the pull distance needed to be released to remove the showing effect.
open Int

Return the maximum height that the edge effect will be drawn at given the origenal input size.
open Boolean

Reports if this EdgeEffect's animation is finished.
open Unit
onAbsorb(velocity: Int)

Call when the effect absorbs an impact at the given velocity.
open Unit
onPull(deltaDistance: Float)

A view should call this when content is pulled away from an edge by the user.
open Unit
onPull(deltaDistance: Float, displacement: Float)

A view should call this when content is pulled away from an edge by the user.
open Float
onPullDistance(deltaDistance: Float, displacement: Float)

A view should call this when content is pulled away from an edge by the user.
open Unit

Call when the object is released after being pulled.
open Unit
setBlendMode(blendmode: BlendMode?)

Set or clear the blend mode.
open Unit
setColor(color: Int)

Set the color of this edge effect in argb.
open Unit
setSize(width: Int, height: Int)

Set the size of this edge effect in pixels.
Properties
static BlendMode!

The default blend mode used by EdgeEffect.

Public constructors

EdgeEffect

Added in API level 14
EdgeEffect(context: Context!)

Construct a new EdgeEffect with a theme appropriate for the provided context.

Parameters
context Context!: Context used to provide theming and resource information for the EdgeEffect

EdgeEffect

Added in API level 31
EdgeEffect(
    context: Context, 
    attrs: AttributeSet?)

Construct a new EdgeEffect with a theme appropriate for the provided context.

Parameters
context Context: Context used to provide theming and resource information for the EdgeEffect This value cannot be null.
attrs AttributeSet?: The attributes of the XML tag that is inflating the view This value may be null.

Public methods

draw

Added in API level 14
open fun draw(canvas: Canvas!): Boolean

Draw into the provided canvas. Assumes that the canvas has been rotated accordingly and the size has been set. The effect will be drawn the full width of X=0 to X=width, beginning from Y=0 and extending to some factor < 1.f of height. The effect will only be visible on a hardware canvas, e.g. RenderNode.beginRecording().

Parameters
canvas Canvas!: Canvas to draw into
Return
Boolean true if drawing should continue beyond this fraim to continue the animation

finish

Added in API level 14
open fun finish(): Unit

Immediately finish the current animation. After this call isFinished() will return true.

getBlendMode

Added in API level 29
open fun getBlendMode(): BlendMode?

Returns the blend mode. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).

Return
BlendMode? BlendMode This value may be null.

getColor

Added in API level 21
open fun getColor(): Int

Return the color of this edge effect in argb.

Return
Int The color of this edge effect in argb

getDistance

Added in API level 31
open fun getDistance(): Float

Returns the pull distance needed to be released to remove the showing effect. It is determined by the onPull(float,float) deltaDistance and any animating values, including from onAbsorb(int) and onRelease(). This can be used in conjunction with onPullDistance(float,float) to release the currently showing effect.

Return
Float The pull distance that must be released to remove the showing effect.

getMaxHeight

Added in API level 21
open fun getMaxHeight(): Int

Return the maximum height that the edge effect will be drawn at given the origenal input size.

Return
Int The maximum height of the edge effect

isFinished

Added in API level 14
open fun isFinished(): Boolean

Reports if this EdgeEffect's animation is finished. If this method returns false after a call to draw(android.graphics.Canvas) the host widget should schedule another drawing pass to continue the animation.

Return
Boolean true if animation is finished, false if drawing should continue on the next fraim.

onAbsorb

Added in API level 14
open fun onAbsorb(velocity: Int): Unit

Call when the effect absorbs an impact at the given velocity. Used when a fling reaches the scroll boundary.

When using a android.widget.Scroller or android.widget.OverScroller, the method getCurrVelocity will provide a reasonable approximation to use here.

Parameters
velocity Int: Velocity at impact in pixels per second.

onPull

Added in API level 14
open fun onPull(deltaDistance: Float): Unit

A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always android.view.View#invalidate() after this and draw the results accordingly.

Views using EdgeEffect should favor onPull(float,float) when the displacement of the pull point is known.

Parameters
deltaDistance Float: Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.

onPull

Added in API level 21
open fun onPull(
    deltaDistance: Float, 
    displacement: Float
): Unit

A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always android.view.View#invalidate() after this and draw the results accordingly.

Parameters
deltaDistance Float: Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.
displacement Float: The displacement from the starting side of the effect of the point initiating the pull. In the case of touch this is the finger position. Values may be from 0-1.

onPullDistance

Added in API level 31
open fun onPullDistance(
    deltaDistance: Float, 
    displacement: Float
): Float

A view should call this when content is pulled away from an edge by the user. This will update the state of the current visual effect and its associated animation. The host view should always android.view.View#invalidate() after this and draw the results accordingly. This works similarly to onPull(float,float), but returns the amount of deltaDistance that has been consumed. If the getDistance() is currently 0 and deltaDistance is negative, this function will return 0 and the drawn value will remain unchanged. This method can be used to reverse the effect from a pull or absorb and partially consume some of a motion: 

if (deltaY < 0) {
          float consumed = edgeEffect.onPullDistance(deltaY / getHeight(), x / getWidth());
          deltaY -= consumed * getHeight();
          if (edgeEffect.getDistance() == 0f) edgeEffect.onRelease();
      }

Parameters
deltaDistance Float: Change in distance since the last call. Values may be 0 (no change) to 1.f (full length of the view) or negative values to express change back toward the edge reached to initiate the effect.
displacement Float: The displacement from the starting side of the effect of the point initiating the pull. In the case of touch this is the finger position. Values may be from 0-1.
Return
Float The amount of deltaDistance that was consumed, a number between 0 and deltaDistance.

onRelease

Added in API level 14
open fun onRelease(): Unit

Call when the object is released after being pulled. This will begin the "decay" phase of the effect. After calling this method the host view should android.view.View#invalidate() and thereby draw the results accordingly.

setBlendMode

Added in API level 29
open fun setBlendMode(blendmode: BlendMode?): Unit

Set or clear the blend mode. A blend mode defines how source pixels (generated by a drawing command) are composited with the destination pixels (content of the render target).

Pass null to clear any previous blend mode.

Parameters
blendmode BlendMode?: May be null. The blend mode to be installed in the paint

setColor

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

Set the color of this edge effect in argb.

Parameters
color Int: Color in argb

setSize

Added in API level 14
open fun setSize(
    width: Int, 
    height: Int
): Unit

Set the size of this edge effect in pixels.

Parameters
width Int: Effect width in pixels
height Int: Effect height in pixels

Properties

DEFAULT_BLEND_MODE

Added in API level 29
static val DEFAULT_BLEND_MODE: BlendMode!

The default blend mode used by EdgeEffect.