EdgeEffectCompat

Added in 1.1.0

class EdgeEffectCompat


Helper for accessing EdgeEffect. This class is used to access EdgeEffect on platform versions that support it. When running on older platforms it will result in no-ops. It should be used by views that wish to use the standard Android visual effects at the edges of scrolling containers.

Summary

Public constructors

This function is deprecated.

Use EdgeEffect constructor directly or create.

Public functions

java-static EdgeEffect
create(context: Context, attrs: AttributeSet?)

Constructs and returns a new EdgeEffect themed using the given context, allowing support for the view attributes.

Boolean
draw(canvas: Canvas!)

This function is deprecated.

Use draw directly.

Unit

This function is deprecated.

Use finish directly.

java-static Float
getDistance(edgeEffect: EdgeEffect)

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

Boolean

This function is deprecated.

Use isFinished directly.

Boolean
onAbsorb(velocity: Int)

This function is deprecated.

Use onAbsorb directly.

Boolean
onPull(deltaDistance: Float)

This function is deprecated.

Use onPull.

Boolean
onPull(deltaDistance: Float, displacement: Float)

This function is deprecated.

Use onPull directly.

java-static Unit
onPull(edgeEffect: EdgeEffect, deltaDistance: Float, displacement: Float)

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

java-static Float
onPullDistance(
    edgeEffect: EdgeEffect,
    deltaDistance: Float,
    displacement: Float
)

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

Boolean

This function is deprecated.

Use onRelease directly.

Unit
setSize(width: Int, height: Int)

This function is deprecated.

Use setSize directly.

Public constructors

EdgeEffectCompat

Added in 1.1.0
Deprecated in 1.1.0
EdgeEffectCompat(context: Context!)

Construct a new EdgeEffect themed using the given context.

Note: On platform versions that do not support EdgeEffect, all operations on the newly constructed object will be mocked/no-ops.

Parameters
context: Context!

Context to use for theming the effect

Public functions

create

Added in 1.7.0
java-static fun create(context: Context, attrs: AttributeSet?): EdgeEffect

Constructs and returns a new EdgeEffect themed using the given context, allowing support for the view attributes.

Parameters
context: Context

Context to use for theming the effect

attrs: AttributeSet?

The attributes of the XML tag that is inflating the view

draw

Added in 1.1.0
Deprecated in 1.1.0
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.

Parameters
canvas: Canvas!

Canvas to draw into

Returns
Boolean

true if drawing should continue beyond this frame to continue the animation

finish

Added in 1.1.0
Deprecated in 1.1.0
fun finish(): Unit

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

getDistance

Added in 1.7.0
java-static fun getDistance(edgeEffect: EdgeEffect): Float

Returns the pull distance needed to be released to remove the showing effect. It is determined by the onPulldeltaDistance and any animating values, including from onAbsorb and onRelease. This can be used in conjunction with onPullDistance to release the currently showing effect. On API level 30 and earlier, this will return 0.

Returns
Float

The pull distance that must be released to remove the showing effect or 0 for API level 30 and earlier.

isFinished

Added in 1.1.0
Deprecated in 1.1.0
fun isFinished(): Boolean

Reports if this EdgeEffectCompat's animation is finished. If this method returns false after a call to draw the host widget should schedule another drawing pass to continue the animation.

Returns
Boolean

true if animation is finished, false if drawing should continue on the next frame.

onAbsorb

Added in 1.1.0
Deprecated in 1.1.0
fun onAbsorb(velocity: Int): Boolean

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

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

Parameters
velocity: Int

Velocity at impact in pixels per second.

Returns
Boolean

true if the host view should invalidate, false if it should not.

onPull

Added in 1.1.0
Deprecated in 1.1.0
fun onPull(deltaDistance: Float): Boolean

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 invalidate if this method returns true 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.

Returns
Boolean

true if the host view should call invalidate, false if it should not.

onPull

Added in 1.1.0
Deprecated in 1.1.0
fun onPull(deltaDistance: Float, displacement: Float): Boolean

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 invalidate if this method returns true and draw the results accordingly. Views using EdgeEffect should favor onPull 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.

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.

Returns
Boolean

true if the host view should call invalidate, false if it should not.

onPull

Added in 1.1.0
java-static fun onPull(edgeEffect: EdgeEffect, 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 invalidate after call this method and draw the results accordingly.

Parameters
edgeEffect: EdgeEffect

The EdgeEffect that is attached to the view that is getting pulled away from an edge by the user.

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.

See also
onPull

onPullDistance

Added in 1.7.0
java-static fun onPullDistance(
    edgeEffect: EdgeEffect,
    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 invalidate after this and draw the results accordingly. This works similarly to onPull, but returns the amount of deltaDistance that has been consumed. For API level 31 and above, if the getDistance is currently 0 and deltaDistance is negative, this function will return 0 and the drawn value will remain unchanged. For API level 30 and below, this will consume all of the provided value and return deltaDistance. This method can be used to reverse the effect from a pull or absorb and partially consume some of a motion:

    if (deltaY < 0 && EdgeEffectCompat.getDistance(edgeEffect) != 0) {
        float displacement = x / getWidth();
        float dist = deltaY / getHeight();
        float consumed = EdgeEffectCompat.onPullDistance(edgeEffect, dist, displacement);
        deltaY -= consumed * getHeight();
        if (edgeEffect.getDistance() == 0f) edgeEffect.onRelease();
    }
Parameters
edgeEffect: EdgeEffect

EdgeEffect to use.

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.

Returns
Float

The amount of deltaDistance that was consumed, a number between 0 and deltaDistance.

onRelease

Added in 1.1.0
Deprecated in 1.1.0
fun onRelease(): Boolean

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 invalidate if this method returns true and thereby draw the results accordingly.

Returns
Boolean

true if the host view should invalidate, false if it should not.

setSize

Added in 1.1.0
Deprecated in 1.1.0
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