Merge "Make EdgeEffect public API."
diff --git a/api/current.txt b/api/current.txt
index c899c85..4f50bf3 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -25787,6 +25787,17 @@
ctor public DigitalClock(android.content.Context, android.util.AttributeSet);
}
+ public class EdgeEffect {
+ ctor public EdgeEffect(android.content.Context);
+ method public boolean draw(android.graphics.Canvas);
+ method public void finish();
+ method public boolean isFinished();
+ method public void onAbsorb(int);
+ method public void onPull(float);
+ method public void onRelease();
+ method public void setSize(int, int);
+ }
+
public class EditText extends android.widget.TextView {
ctor public EditText(android.content.Context);
ctor public EditText(android.content.Context, android.util.AttributeSet);
@@ -26372,6 +26383,7 @@
method public void fling(int, int, int, int, int, int, int, int);
method public void fling(int, int, int, int, int, int, int, int, int, int);
method public final void forceFinished(boolean);
+ method public float getCurrVelocity();
method public final int getCurrX();
method public final int getCurrY();
method public final int getFinalX();
@@ -26714,6 +26726,7 @@
method public void extendDuration(int);
method public void fling(int, int, int, int, int, int, int, int);
method public final void forceFinished(boolean);
+ method public float getCurrVelocity();
method public final int getCurrX();
method public final int getCurrY();
method public final int getDuration();
diff --git a/core/java/android/webkit/OverScrollGlow.java b/core/java/android/webkit/OverScrollGlow.java
index ff5b30b..e906f7f 100644
--- a/core/java/android/webkit/OverScrollGlow.java
+++ b/core/java/android/webkit/OverScrollGlow.java
@@ -22,7 +22,7 @@
import android.graphics.Canvas;
import android.graphics.drawable.Drawable;
import android.view.View;
-import android.widget.EdgeGlow;
+import android.widget.EdgeEffect;
/**
* This class manages the edge glow effect when a WebView is flung or pulled beyond the edges.
@@ -31,10 +31,10 @@
public class OverScrollGlow {
private WebView mHostView;
- private EdgeGlow mEdgeGlowTop;
- private EdgeGlow mEdgeGlowBottom;
- private EdgeGlow mEdgeGlowLeft;
- private EdgeGlow mEdgeGlowRight;
+ private EdgeEffect mEdgeGlowTop;
+ private EdgeEffect mEdgeGlowBottom;
+ private EdgeEffect mEdgeGlowLeft;
+ private EdgeEffect mEdgeGlowRight;
private int mOverScrollDeltaX;
private int mOverScrollDeltaY;
@@ -42,13 +42,10 @@
public OverScrollGlow(WebView host) {
mHostView = host;
Context context = host.getContext();
- final Resources res = context.getResources();
- final Drawable edge = res.getDrawable(R.drawable.overscroll_edge);
- final Drawable glow = res.getDrawable(R.drawable.overscroll_glow);
- mEdgeGlowTop = new EdgeGlow(context, edge, glow);
- mEdgeGlowBottom = new EdgeGlow(context, edge, glow);
- mEdgeGlowLeft = new EdgeGlow(context, edge, glow);
- mEdgeGlowRight = new EdgeGlow(context, edge, glow);
+ mEdgeGlowTop = new EdgeEffect(context);
+ mEdgeGlowBottom = new EdgeEffect(context);
+ mEdgeGlowLeft = new EdgeEffect(context);
+ mEdgeGlowRight = new EdgeEffect(context);
}
/**
diff --git a/core/java/android/widget/AbsListView.java b/core/java/android/widget/AbsListView.java
index 80cbbfb..05d4f05 100644
--- a/core/java/android/widget/AbsListView.java
+++ b/core/java/android/widget/AbsListView.java
@@ -594,12 +594,12 @@
/**
* Tracks the state of the top edge glow.
*/
- private EdgeGlow mEdgeGlowTop;
+ private EdgeEffect mEdgeGlowTop;
/**
* Tracks the state of the bottom edge glow.
*/
- private EdgeGlow mEdgeGlowBottom;
+ private EdgeEffect mEdgeGlowBottom;
/**
* An estimate of how many pixels are between the top of the list and
@@ -788,11 +788,8 @@
if (mode != OVER_SCROLL_NEVER) {
if (mEdgeGlowTop == null) {
Context context = getContext();
- final Resources res = context.getResources();
- final Drawable edge = res.getDrawable(R.drawable.overscroll_edge);
- final Drawable glow = res.getDrawable(R.drawable.overscroll_glow);
- mEdgeGlowTop = new EdgeGlow(context, edge, glow);
- mEdgeGlowBottom = new EdgeGlow(context, edge, glow);
+ mEdgeGlowTop = new EdgeEffect(context);
+ mEdgeGlowBottom = new EdgeEffect(context);
}
} else {
mEdgeGlowTop = null;
diff --git a/core/java/android/widget/EdgeGlow.java b/core/java/android/widget/EdgeEffect.java
similarity index 77%
rename from core/java/android/widget/EdgeGlow.java
rename to core/java/android/widget/EdgeEffect.java
index 75cef38..fd2abc2 100644
--- a/core/java/android/widget/EdgeGlow.java
+++ b/core/java/android/widget/EdgeEffect.java
@@ -16,7 +16,10 @@
package android.widget;
+import com.android.internal.R;
+
import android.content.Context;
+import android.content.res.Resources;
import android.graphics.Canvas;
import android.graphics.drawable.Drawable;
import android.view.animation.AnimationUtils;
@@ -24,19 +27,33 @@
import android.view.animation.Interpolator;
/**
- * This class performs the glow effect used at the edges of scrollable widgets.
- * @hide
+ * This class performs the graphical effect used at the edges of scrollable widgets
+ * when the user scrolls beyond the content bounds in 2D space.
+ *
+ * <p>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.</p>
+ *
+ * <p>When drawing, widgets should draw their main content and child views first,
+ * usually by invoking <code>super.draw(canvas)</code> from an overridden <code>draw</code>
+ * 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.</p>
*/
-public class EdgeGlow {
- private static final String TAG = "EdgeGlow";
+public class EdgeEffect {
+ private static final String TAG = "EdgeEffect";
// Time it will take the effect to fully recede in ms
private static final int RECEDE_TIME = 1000;
- // Time it will take before a pulled glow begins receding
+ // Time it will take before a pulled glow begins receding in ms
private static final int PULL_TIME = 167;
- // Time it will take for a pulled glow to decay to partial strength before release
+ // Time it will take in ms for a pulled glow to decay to partial strength before release
private static final int PULL_DECAY_TIME = 1000;
private static final float MAX_ALPHA = 0.8f;
@@ -103,31 +120,58 @@
private float mPullDistance;
- public EdgeGlow(Context context, Drawable edge, Drawable glow) {
- mEdge = edge;
- mGlow = glow;
+ /**
+ * 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) {
+ final Resources res = context.getResources();
+ mEdge = res.getDrawable(R.drawable.overscroll_edge);
+ mGlow = res.getDrawable(R.drawable.overscroll_glow);
mMinWidth = (int) (context.getResources().getDisplayMetrics().density * MIN_WIDTH + 0.5f);
mInterpolator = new DecelerateInterpolator();
}
+ /**
+ * 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) {
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;
}
/**
- * Call when the object is pulled by the user.
+ * 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
+ * @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) {
final long now = AnimationUtils.currentAnimationTimeMillis();
@@ -173,6 +217,9 @@
/**
* 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;
@@ -198,6 +245,11 @@
/**
* Call when the effect absorbs an impact at the given velocity.
+ * Used when a fling reaches the scroll boundary.
+ *
+ * <p>When using a {@link android.widget.Scroller} or {@link android.widget.OverScroller},
+ * the method <code>getCurrVelocity</code> will provide a reasonable approximation
+ * to use here.</p>
*
* @param velocity Velocity at impact in pixels per second.
*/
@@ -238,7 +290,7 @@
/**
* 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, emitting from Y=0 and extending to some factor <
+ * 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
diff --git a/core/java/android/widget/HorizontalScrollView.java b/core/java/android/widget/HorizontalScrollView.java
index d638732..a7a05be 100644
--- a/core/java/android/widget/HorizontalScrollView.java
+++ b/core/java/android/widget/HorizontalScrollView.java
@@ -75,8 +75,8 @@
private final Rect mTempRect = new Rect();
private OverScroller mScroller;
- private EdgeGlow mEdgeGlowLeft;
- private EdgeGlow mEdgeGlowRight;
+ private EdgeEffect mEdgeGlowLeft;
+ private EdgeEffect mEdgeGlowRight;
/**
* Position of the last motion event.
@@ -1477,11 +1477,8 @@
if (mode != OVER_SCROLL_NEVER) {
if (mEdgeGlowLeft == null) {
Context context = getContext();
- final Resources res = context.getResources();
- final Drawable edge = res.getDrawable(R.drawable.overscroll_edge);
- final Drawable glow = res.getDrawable(R.drawable.overscroll_glow);
- mEdgeGlowLeft = new EdgeGlow(context, edge, glow);
- mEdgeGlowRight = new EdgeGlow(context, edge, glow);
+ mEdgeGlowLeft = new EdgeEffect(context);
+ mEdgeGlowRight = new EdgeEffect(context);
}
} else {
mEdgeGlowLeft = null;
diff --git a/core/java/android/widget/OverScroller.java b/core/java/android/widget/OverScroller.java
index 0ba7889..542a1ef 100644
--- a/core/java/android/widget/OverScroller.java
+++ b/core/java/android/widget/OverScroller.java
@@ -166,7 +166,6 @@
}
/**
- * @hide
* Returns the absolute value of the current velocity.
*
* @return The original velocity less the deceleration, norm of the X and Y velocity vector.
diff --git a/core/java/android/widget/ScrollView.java b/core/java/android/widget/ScrollView.java
index 09c875b..6a6bc23 100644
--- a/core/java/android/widget/ScrollView.java
+++ b/core/java/android/widget/ScrollView.java
@@ -69,8 +69,8 @@
private final Rect mTempRect = new Rect();
private OverScroller mScroller;
- private EdgeGlow mEdgeGlowTop;
- private EdgeGlow mEdgeGlowBottom;
+ private EdgeEffect mEdgeGlowTop;
+ private EdgeEffect mEdgeGlowBottom;
/**
* Position of the last motion event.
@@ -1511,11 +1511,8 @@
if (mode != OVER_SCROLL_NEVER) {
if (mEdgeGlowTop == null) {
Context context = getContext();
- final Resources res = context.getResources();
- final Drawable edge = res.getDrawable(R.drawable.overscroll_edge);
- final Drawable glow = res.getDrawable(R.drawable.overscroll_glow);
- mEdgeGlowTop = new EdgeGlow(context, edge, glow);
- mEdgeGlowBottom = new EdgeGlow(context, edge, glow);
+ mEdgeGlowTop = new EdgeEffect(context);
+ mEdgeGlowBottom = new EdgeEffect(context);
}
} else {
mEdgeGlowTop = null;
diff --git a/core/java/android/widget/Scroller.java b/core/java/android/widget/Scroller.java
index f00640e..a6e83f0 100644
--- a/core/java/android/widget/Scroller.java
+++ b/core/java/android/widget/Scroller.java
@@ -196,7 +196,6 @@
}
/**
- * @hide
* Returns the current velocity.
*
* @return The original velocity less the deceleration. Result may be