java.lang.Object
↳androidx.core.widget.EdgeEffectCompat
Gradle dependencies
compile group: 'androidx.core', name: 'core', version: '1.9.0-alpha04'
- groupId: androidx.core
- artifactId: core
- version: 1.9.0-alpha04
Artifact androidx.core:core:1.9.0-alpha04 it located at Google repository (https://maven.google.com/)
Androidx artifact mapping:
androidx.core:core com.android.support:support-compat
Androidx class mapping:
androidx.core.widget.EdgeEffectCompat android.support.v4.widget.EdgeEffectCompat
Overview
Helper for accessing .
This class is used to access 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
Constructors |
---|
public | EdgeEffectCompat(Context context)
Construct a new EdgeEffect themed using the given context. |
Methods |
---|
public static EdgeEffect | create(Context context, AttributeSet attrs)
Constructs and returns a new EdgeEffect themed using the given context, allowing support
for the view attributes. |
public boolean | draw(Canvas canvas)
Draw into the provided canvas. |
public void | finish()
Immediately finish the current animation. |
public static float | getDistance(EdgeEffect edgeEffect)
Returns the pull distance needed to be released to remove the showing effect. |
public boolean | isFinished()
Reports if this EdgeEffectCompat's animation is finished. |
public boolean | onAbsorb(int velocity)
Call when the effect absorbs an impact at the given velocity. |
public static void | onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement)
A view should call this when content is pulled away from an edge by the user. |
public boolean | onPull(float deltaDistance)
A view should call this when content is pulled away from an edge by the user. |
public boolean | onPull(float deltaDistance, float displacement)
A view should call this when content is pulled away from an edge by the user. |
public static float | onPullDistance(EdgeEffect edgeEffect, float deltaDistance, float displacement)
A view should call this when content is pulled away from an edge by the user. |
public boolean | onRelease()
Call when the object is released after being pulled. |
public void | setSize(int width, int height)
Set the size of this edge effect in pixels. |
from java.lang.Object | clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructors
public
EdgeEffectCompat(Context context)
Deprecated: Use constructor directly or
EdgeEffectCompat.create(Context, AttributeSet).
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 to use for theming the effect
Methods
public static EdgeEffect
create(Context context, AttributeSet attrs)
Constructs and returns a new EdgeEffect themed using the given context, allowing support
for the view attributes.
Parameters:
context: Context to use for theming the effect
attrs: The attributes of the XML tag that is inflating the view
public static float
getDistance(EdgeEffect edgeEffect)
Returns the pull distance needed to be released to remove the showing effect.
It is determined by the EdgeEffectCompat.onPull(float, float) deltaDistance
and
any animating values, including from EdgeEffectCompat.onAbsorb(int) and EdgeEffectCompat.onRelease().
This can be used in conjunction with EdgeEffectCompat.onPullDistance(EdgeEffect, float, float) to
release the currently showing effect.
On API level 30 and earlier, this will return 0.
Returns:
The pull distance that must be released to remove the showing effect or 0 for
API level 30 and earlier.
public void
setSize(int width, int height)
Deprecated: Use directly.
Set the size of this edge effect in pixels.
Parameters:
width: Effect width in pixels
height: Effect height in pixels
public boolean
isFinished()
Deprecated: Use directly.
Reports if this EdgeEffectCompat's animation is finished. If this method returns false
after a call to EdgeEffectCompat.draw(Canvas) the host widget should schedule another
drawing pass to continue the animation.
Returns:
true if animation is finished, false if drawing should continue on the next frame.
Deprecated: Use directly.
Immediately finish the current animation.
After this call EdgeEffectCompat.isFinished() will return true.
public boolean
onPull(float deltaDistance)
Deprecated: Use EdgeEffectCompat.onPull(EdgeEffect, 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 View
if this method
returns true and draw the results accordingly.
Parameters:
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.
Returns:
true if the host view should call invalidate, false if it should not.
public boolean
onPull(float deltaDistance, float displacement)
Deprecated: Use directly.
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 View
if this method
returns true and draw the results accordingly.
Views using should favor when
the displacement of the pull point is known.
Parameters:
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.
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.
Returns:
true if the host view should call invalidate, false if it should not.
public static void
onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement)
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 View
after call this method
and draw the results accordingly.
Parameters:
edgeEffect: The EdgeEffect that is attached to the view that is getting pulled away
from an edge by the user.
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.
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.
See also:
public static float
onPullDistance(EdgeEffect edgeEffect, float deltaDistance, float displacement)
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 View
after this
and draw the results accordingly. This works similarly to EdgeEffectCompat.onPull(float, float),
but returns the amount of deltaDistance
that has been consumed.
For API level 31 and above, if the EdgeEffectCompat.getDistance(EdgeEffect) 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:
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.
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.
Returns:
The amount of deltaDistance
that was consumed, a number between
0 and deltaDistance
.
public boolean
onRelease()
Deprecated: Use directly.
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 View
if this method
returns true and thereby draw the results accordingly.
Returns:
true if the host view should invalidate, false if it should not.
public boolean
onAbsorb(int velocity)
Deprecated: Use directly.
Call when the effect absorbs an impact at the given velocity.
Used when a fling reaches the scroll boundary.
When using a or ,
the method getCurrVelocity
will provide a reasonable approximation
to use here.
Parameters:
velocity: Velocity at impact in pixels per second.
Returns:
true if the host view should invalidate, false if it should not.
public boolean
draw(Canvas canvas)
Deprecated: Use directly.
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 to draw into
Returns:
true if drawing should continue beyond this frame to continue the
animation
Source
/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.core.widget;
import static android.os.Build.VERSION.SDK_INT;
import android.content.Context;
import android.graphics.Canvas;
import android.util.AttributeSet;
import android.view.View;
import android.widget.EdgeEffect;
import android.widget.OverScroller;
import android.widget.Scroller;
import androidx.annotation.DoNotInline;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
/**
* Helper for accessing {@link EdgeEffect}.
*
* This class is used to access {@link 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.
*/
public final class EdgeEffectCompat {
private final EdgeEffect mEdgeEffect;
/**
* Construct a new EdgeEffect themed using the given context.
*
* <p>Note: On platform versions that do not support EdgeEffect, all operations
* on the newly constructed object will be mocked/no-ops.</p>
*
* @param context Context to use for theming the effect
*
* @deprecated Use {@link EdgeEffect} constructor directly or
* {@link EdgeEffectCompat#create(Context, AttributeSet)}.
*/
@Deprecated
public EdgeEffectCompat(Context context) {
mEdgeEffect = new EdgeEffect(context);
}
/**
* Constructs and returns a new EdgeEffect themed using the given context, allowing support
* for the view attributes.
*
* @param context Context to use for theming the effect
* @param attrs The attributes of the XML tag that is inflating the view
*/
@NonNull
public static EdgeEffect create(@NonNull Context context, @Nullable AttributeSet attrs) {
if (SDK_INT >= 31) {
return Api31Impl.create(context, attrs);
}
return new EdgeEffect(context);
}
/**
* Returns the pull distance needed to be released to remove the showing effect.
* It is determined by the {@link #onPull(float, float)} <code>deltaDistance</code> and
* any animating values, including from {@link #onAbsorb(int)} and {@link #onRelease()}.
*
* This can be used in conjunction with {@link #onPullDistance(EdgeEffect, float, float)} to
* release the currently showing effect.
*
* On API level 30 and earlier, this will return 0.
*
* @return The pull distance that must be released to remove the showing effect or 0 for
* API level 30 and earlier.
*/
public static float getDistance(@NonNull EdgeEffect edgeEffect) {
if (SDK_INT >= 31) {
return Api31Impl.getDistance(edgeEffect);
}
return 0;
}
/**
* Set the size of this edge effect in pixels.
*
* @param width Effect width in pixels
* @param height Effect height in pixels
*
* @deprecated Use {@link EdgeEffect#setSize(int, int)} directly.
*/
@Deprecated
public void setSize(int width, int height) {
mEdgeEffect.setSize(width, height);
}
/**
* Reports if this EdgeEffectCompat'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.
*
* @deprecated Use {@link EdgeEffect#isFinished()} directly.
*/
@Deprecated
public boolean isFinished() {
return mEdgeEffect.isFinished();
}
/**
* Immediately finish the current animation.
* After this call {@link #isFinished()} will return true.
*
* @deprecated Use {@link EdgeEffect#finish()} directly.
*/
@Deprecated
public void finish() {
mEdgeEffect.finish();
}
/**
* 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 View#invalidate()} if this method
* returns true 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.
* @return true if the host view should call invalidate, false if it should not.
*
* @deprecated Use {@link #onPull(EdgeEffect, float, float)}.
*/
@Deprecated
public boolean onPull(float deltaDistance) {
mEdgeEffect.onPull(deltaDistance);
return true;
}
/**
* 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 View#invalidate()} if this method
* returns true and draw the results accordingly.
*
* Views using {@link EdgeEffect} should favor {@link EdgeEffect#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.
* @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 true if the host view should call invalidate, false if it should not.
*
* @deprecated Use {@link EdgeEffect#onPull(float)} directly.
*/
@Deprecated
public boolean onPull(float deltaDistance, float displacement) {
onPull(mEdgeEffect, deltaDistance, displacement);
return true;
}
/**
* 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 View#invalidate()} after call this method
* and draw the results accordingly.
*
* @param edgeEffect The EdgeEffect that is attached to the view that is getting pulled away
* from an edge by the user.
* @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.
*
* @see EdgeEffect#onPull(float, float)
*/
public static void onPull(@NonNull EdgeEffect edgeEffect, float deltaDistance,
float displacement) {
if (SDK_INT >= 21) {
Api21Impl.onPull(edgeEffect, deltaDistance, displacement);
} else {
edgeEffect.onPull(deltaDistance);
}
}
/**
* 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 View#invalidate()} after this
* and draw the results accordingly. This works similarly to {@link #onPull(float, float)},
* but returns the amount of <code>deltaDistance</code> that has been consumed.
*
* For API level 31 and above, if the {@link #getDistance(EdgeEffect)} is currently 0 and
* <code>deltaDistance</code> 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
* <code>deltaDistance</code>.
*
* This method can be used to reverse the effect from a pull or absorb and partially consume
* some of a motion:
*
* <pre class="prettyprint">
* 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();
* }
* </pre>
*
* @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 <code>deltaDistance</code> that was consumed, a number between
* 0 and <code>deltaDistance</code>.
*/
public static float onPullDistance(
@NonNull EdgeEffect edgeEffect,
float deltaDistance,
float displacement
) {
if (SDK_INT >= 31) {
return Api31Impl.onPullDistance(edgeEffect, deltaDistance, displacement);
}
onPull(edgeEffect, deltaDistance, displacement);
return deltaDistance;
}
/**
* 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 View#invalidate()} if this method
* returns true and thereby draw the results accordingly.
*
* @return true if the host view should invalidate, false if it should not.
*
* @deprecated Use {@link EdgeEffect#onRelease()} directly.
*/
@Deprecated
public boolean onRelease() {
mEdgeEffect.onRelease();
return mEdgeEffect.isFinished();
}
/**
* Call when the effect absorbs an impact at the given velocity.
* Used when a fling reaches the scroll boundary.
*
* <p>When using a {@link Scroller} or {@link OverScroller},
* the method <code>getCurrVelocity</code> will provide a reasonable approximation
* to use here.</p>
*
* @param velocity Velocity at impact in pixels per second.
* @return true if the host view should invalidate, false if it should not.
*
* @deprecated Use {@link EdgeEffect#onAbsorb(int)} directly.
*/
@Deprecated
public boolean onAbsorb(int velocity) {
mEdgeEffect.onAbsorb(velocity);
return true;
}
/**
* 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.
*
* @param canvas Canvas to draw into
* @return true if drawing should continue beyond this frame to continue the
* animation
*
* @deprecated Use {@link EdgeEffect#draw(Canvas)} directly.
*/
@Deprecated
public boolean draw(Canvas canvas) {
return mEdgeEffect.draw(canvas);
}
@RequiresApi(31)
private static class Api31Impl {
private Api31Impl() {}
@DoNotInline
public static EdgeEffect create(Context context, AttributeSet attrs) {
try {
return new EdgeEffect(context, attrs);
} catch (Throwable t) {
return new EdgeEffect(context); // Old preview release
}
}
@DoNotInline
public static float onPullDistance(
EdgeEffect edgeEffect,
float deltaDistance,
float displacement
) {
try {
return edgeEffect.onPullDistance(deltaDistance, displacement);
} catch (Throwable t) {
edgeEffect.onPull(deltaDistance, displacement); // Old preview release
return 0;
}
}
@DoNotInline
public static float getDistance(EdgeEffect edgeEffect) {
try {
return edgeEffect.getDistance();
} catch (Throwable t) {
return 0; // Old preview release
}
}
}
@RequiresApi(21)
static class Api21Impl {
private Api21Impl() {
// This class is not instantiable.
}
@DoNotInline
static void onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement) {
edgeEffect.onPull(deltaDistance, displacement);
}
}
}