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 {@link #onAbsorb(int)}, {@link #onPull(float)}, and {@link #onRelease()}, * and draw the effect using {@link #draw(Canvas)} in the widget's overridden * {@link android.view.View#draw(Canvas)} method. If {@link #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
* {@link #draw(Canvas)} method.
android:edgeEffectType="glow".
*/
public static final int TYPE_GLOW = 0;
/**
* Use a stretch for the edge effect. From XML, use
* android:edgeEffectType="stretch".
*/
public static final int TYPE_STRETCH = 1;
/**
* The velocity threshold before the spring animation is considered settled.
* The idea here is that velocity should be less than 1 pixel per frame (~16ms).
*/
private static final double VELOCITY_THRESHOLD = 1.0 / 0.016;
/**
* The value threshold before the spring animation is considered close enough to
* the destination to be settled. This should be around 1 pixel.
*/
private static final double VALUE_THRESHOLD = 1;
/**
* The natural frequency of the stretch spring.
*/
private static final double NATURAL_FREQUENCY = 17.55;
/**
* The damping ratio of the stretch spring.
*/
private static final double DAMPING_RATIO = 0.92;
/** @hide */
@IntDef({TYPE_GLOW, TYPE_STRETCH})
@Retention(RetentionPolicy.SOURCE)
public @interface EdgeEffectType {
}
private static final float LINEAR_STRETCH_INTENSITY = 0.06f;
private static final float EXP_STRETCH_INTENSITY = 0.06f;
private static final float SCROLL_DIST_AFFECTED_BY_EXP_STRETCH = 0.33f;
@SuppressWarnings("UnusedDeclaration")
private static final String TAG = "EdgeEffect";
// Time it will take the effect to fully recede in ms
private static final int RECEDE_TIME = 600;
// Time it will take before a pulled glow begins receding in ms
private static final int PULL_TIME = 167;
// Time it will take in ms for a pulled glow to decay to partial strength before release
private static final int PULL_DECAY_TIME = 2000;
private static final float MAX_ALPHA = 0.15f;
private static final float GLOW_ALPHA_START = .09f;
private static final float MAX_GLOW_SCALE = 2.f;
private static final float PULL_GLOW_BEGIN = 0.f;
// Minimum velocity that will be absorbed
private static final int MIN_VELOCITY = 100;
// Maximum velocity, clamps at this value
private static final int MAX_VELOCITY = 10000;
private static final float EPSILON = 0.001f;
private static final double ANGLE = Math.PI / 6;
private static final float SIN = (float) Math.sin(ANGLE);
private static final float COS = (float) Math.cos(ANGLE);
private static final float RADIUS_FACTOR = 0.6f;
private float mGlowAlpha;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private float mGlowScaleY;
private float mDistance;
private float mVelocity; // only for stretch animations
private float mGlowAlphaStart;
private float mGlowAlphaFinish;
private float mGlowScaleYStart;
private float mGlowScaleYFinish;
private long mStartTime;
private float mDuration;
private final Interpolator mInterpolator = new DecelerateInterpolator();
private static final int STATE_IDLE = 0;
private static final int STATE_PULL = 1;
private static final int STATE_ABSORB = 2;
private static final int STATE_RECEDE = 3;
private static final int STATE_PULL_DECAY = 4;
private static final float PULL_DISTANCE_ALPHA_GLOW_FACTOR = 0.8f;
private static final int VELOCITY_GLOW_FACTOR = 6;
private int mState = STATE_IDLE;
private float mPullDistance;
private final Rect mBounds = new Rect();
private float mWidth;
private float mHeight;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 123769450)
private final Paint mPaint = new Paint();
private float mRadius;
private float mBaseGlowScale;
private float mDisplacement = 0.5f;
private float mTargetDisplacement = 0.5f;
private @EdgeEffectType int mEdgeEffectType = TYPE_GLOW;
private Matrix mTmpMatrix = null;
private float[] mTmpPoints = null;
/**
* Construct a new EdgeEffect with a theme appropriate for the provided context.
* @param context Context used to provide theming and resource information for the EdgeEffect
*/
public EdgeEffect(Context context) {
this(context, null, Compatibility.isChangeEnabled(USE_STRETCH_EDGE_EFFECT_BY_DEFAULT));
}
/**
* Construct a new EdgeEffect with a theme appropriate for the provided context.
* @param context Context used to provide theming and resource information for the EdgeEffect
* @param attrs The attributes of the XML tag that is inflating the view
*/
public EdgeEffect(@NonNull Context context, @Nullable AttributeSet attrs) {
this(context, attrs,
Compatibility.isChangeEnabled(USE_STRETCH_EDGE_EFFECT_BY_DEFAULT)
|| Compatibility.isChangeEnabled(USE_STRETCH_EDGE_EFFECT_FOR_SUPPORTED));
}
private EdgeEffect(@NonNull Context context, @Nullable AttributeSet attrs,
boolean defaultStretch) {
final TypedArray a = context.obtainStyledAttributes(
attrs, com.android.internal.R.styleable.EdgeEffect);
final int themeColor = a.getColor(
com.android.internal.R.styleable.EdgeEffect_colorEdgeEffect, 0xff666666);
mEdgeEffectType = a.getInt(
com.android.internal.R.styleable.EdgeEffect_edgeEffectType,
defaultStretch ? TYPE_STRETCH : TYPE_GLOW);
a.recycle();
mPaint.setAntiAlias(true);
mPaint.setColor((themeColor & 0xffffff) | 0x33000000);
mPaint.setStyle(Paint.Style.FILL);
mPaint.setBlendMode(DEFAULT_BLEND_MODE);
}
/**
* Set the size of this edge effect in pixels.
*
* @param width Effect width in pixels
* @param height Effect height in pixels
*/
public void setSize(int width, int height) {
final float r = width * RADIUS_FACTOR / SIN;
final float y = COS * r;
final float h = r - y;
final float or = height * RADIUS_FACTOR / SIN;
final float oy = COS * or;
final float oh = or - oy;
mRadius = r;
mBaseGlowScale = h > 0 ? Math.min(oh / h, 1.f) : 1.f;
mBounds.set(mBounds.left, mBounds.top, width, (int) Math.min(height, h));
mWidth = width;
mHeight = height;
}
/**
* Reports if this EdgeEffect's animation is finished. If this method returns false
* after a call to {@link #draw(Canvas)} the host widget should schedule another
* drawing pass to continue the animation.
*
* @return true if animation is finished, false if drawing should continue on the next frame.
*/
public boolean isFinished() {
return mState == STATE_IDLE;
}
/**
* Immediately finish the current animation.
* After this call {@link #isFinished()} will return true.
*/
public void finish() {
mState = STATE_IDLE;
mDistance = 0;
mVelocity = 0;
}
/**
* 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 {@link android.view.View#invalidate()} after this
* and draw the results accordingly.
*
* Views using EdgeEffect should favor {@link #onPull(float, float)} when the displacement * of the pull point is known.
* * @param deltaDistance 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. */ public void onPull(float deltaDistance) { onPull(deltaDistance, 0.5f); } /** * 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 {@link android.view.View#invalidate()} after this * and draw the results accordingly. * * @param deltaDistance 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. * @param displacement 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. */ public void onPull(float deltaDistance, float displacement) { final long now = AnimationUtils.currentAnimationTimeMillis(); mTargetDisplacement = displacement; if (mState == STATE_PULL_DECAY && now - mStartTime < mDuration && mEdgeEffectType == TYPE_GLOW) { return; } if (mState != STATE_PULL) { if (mEdgeEffectType == TYPE_STRETCH) { // Restore the mPullDistance to the fraction it is currently showing -- we want // to "catch" the current stretch value. mPullDistance = mDistance; } else { mGlowScaleY = Math.max(PULL_GLOW_BEGIN, mGlowScaleY); } } mState = STATE_PULL; mStartTime = now; mDuration = PULL_TIME; mPullDistance += deltaDistance; mDistance = Math.max(0f, mPullDistance); mVelocity = 0; if (mPullDistance == 0) { mGlowScaleY = mGlowScaleYStart = 0; mGlowAlpha = mGlowAlphaStart = 0; } else { final float absdd = Math.abs(deltaDistance); mGlowAlpha = mGlowAlphaStart = Math.min(MAX_ALPHA, mGlowAlpha + (absdd * PULL_DISTANCE_ALPHA_GLOW_FACTOR)); final float scale = (float) (Math.max(0, 1 - 1 / Math.sqrt(Math.abs(mPullDistance) * mBounds.height()) - 0.3d) / 0.7d); mGlowScaleY = mGlowScaleYStart = scale; } mGlowAlphaFinish = mGlowAlpha; mGlowScaleYFinish = mGlowScaleY; } /** * 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 {@link android.view.View#invalidate()} after this * and draw the results accordingly. This works similarly to {@link #onPull(float, float)}, * but returns the amount ofdeltaDistance that has been consumed. If the
* {@link #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();
* }
*
*
* @param deltaDistance 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.
* @param displacement 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 The amount of deltaDistance that was consumed, a number between
* 0 and deltaDistance.
*/
public float onPullDistance(float deltaDistance, float displacement) {
float finalDistance = Math.max(0f, deltaDistance + mDistance);
float delta = finalDistance - mDistance;
if (delta == 0f && mDistance == 0f) {
return 0f; // No pull, don't do anything.
}
if (mState != STATE_PULL && mState != STATE_PULL_DECAY && mEdgeEffectType == TYPE_GLOW) {
// Catch the edge glow in the middle of an animation.
mPullDistance = mDistance;
mState = STATE_PULL;
}
onPull(delta, displacement);
return delta;
}
/**
* Returns the pull distance needed to be released to remove the showing effect.
* It is determined by the {@link #onPull(float, float)} deltaDistance and
* any animating values, including from {@link #onAbsorb(int)} and {@link #onRelease()}.
*
* This can be used in conjunction with {@link #onPullDistance(float, float)} to
* release the currently showing effect.
*
* @return The pull distance that must be released to remove the showing effect.
*/
public float getDistance() {
return mDistance;
}
/**
* 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 {@link android.view.View#invalidate()} and thereby
* draw the results accordingly.
*/
public void onRelease() {
mPullDistance = 0;
if (mState != STATE_PULL && mState != STATE_PULL_DECAY) {
return;
}
mState = STATE_RECEDE;
mGlowAlphaStart = mGlowAlpha;
mGlowScaleYStart = mGlowScaleY;
mGlowAlphaFinish = 0.f;
mGlowScaleYFinish = 0.f;
mVelocity = 0.f;
mStartTime = AnimationUtils.currentAnimationTimeMillis();
mDuration = RECEDE_TIME;
}
/**
* Call when the effect absorbs an impact at the given velocity.
* Used when a fling reaches the scroll boundary.
*
* When using a {@link android.widget.Scroller} or {@link android.widget.OverScroller},
* the method getCurrVelocity will provide a reasonable approximation
* to use here.