1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package android.support.v4.widget;
17
18import android.content.Context;
19import android.graphics.Canvas;
20import android.os.Build;
21import android.support.annotation.RequiresApi;
22import android.widget.EdgeEffect;
23
24/**
25 * Helper for accessing {@link android.widget.EdgeEffect} in a backwards compatible fashion.
26 *
27 * This class is used to access {@link android.widget.EdgeEffect} on platform versions
28 * that support it. When running on older platforms it will result in no-ops. It should
29 * be used by views that wish to use the standard Android visual effects at the edges
30 * of scrolling containers.
31 */
32public final class EdgeEffectCompat {
33    private EdgeEffect mEdgeEffect;
34
35    private static final EdgeEffectBaseImpl IMPL;
36
37    static {
38        if (Build.VERSION.SDK_INT >= 21) {
39            IMPL = new EdgeEffectApi21Impl();
40        } else {
41            IMPL = new EdgeEffectBaseImpl();
42        }
43    }
44
45    static class EdgeEffectBaseImpl {
46        public void onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement) {
47            edgeEffect.onPull(deltaDistance);
48        }
49    }
50
51    @RequiresApi(21)
52    static class EdgeEffectApi21Impl extends EdgeEffectBaseImpl {
53        @Override
54        public void onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement) {
55            edgeEffect.onPull(deltaDistance, displacement);
56        }
57    }
58
59    /**
60     * Construct a new EdgeEffect themed using the given context.
61     *
62     * <p>Note: On platform versions that do not support EdgeEffect, all operations
63     * on the newly constructed object will be mocked/no-ops.</p>
64     *
65     * @param context Context to use for theming the effect
66     *
67     * @deprecated Use {@link EdgeEffect} constructor directly.
68     */
69    @Deprecated
70    public EdgeEffectCompat(Context context) {
71        mEdgeEffect = new EdgeEffect(context);
72    }
73
74    /**
75     * Set the size of this edge effect in pixels.
76     *
77     * @param width Effect width in pixels
78     * @param height Effect height in pixels
79     *
80     * @deprecated Use {@link EdgeEffect#setSize(int, int)} directly.
81     */
82    @Deprecated
83    public void setSize(int width, int height) {
84        mEdgeEffect.setSize(width, height);
85    }
86
87    /**
88     * Reports if this EdgeEffectCompat's animation is finished. If this method returns false
89     * after a call to {@link #draw(Canvas)} the host widget should schedule another
90     * drawing pass to continue the animation.
91     *
92     * @return true if animation is finished, false if drawing should continue on the next frame.
93     *
94     * @deprecated Use {@link EdgeEffect#isFinished()} directly.
95     */
96    @Deprecated
97    public boolean isFinished() {
98        return mEdgeEffect.isFinished();
99    }
100
101    /**
102     * Immediately finish the current animation.
103     * After this call {@link #isFinished()} will return true.
104     *
105     * @deprecated Use {@link EdgeEffect#finish()} directly.
106     */
107    @Deprecated
108    public void finish() {
109        mEdgeEffect.finish();
110    }
111
112    /**
113     * A view should call this when content is pulled away from an edge by the user.
114     * This will update the state of the current visual effect and its associated animation.
115     * The host view should always {@link android.view.View#invalidate()} if this method
116     * returns true and draw the results accordingly.
117     *
118     * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to
119     *                      1.f (full length of the view) or negative values to express change
120     *                      back toward the edge reached to initiate the effect.
121     * @return true if the host view should call invalidate, false if it should not.
122     *
123     * @deprecated Use {@link #onPull(EdgeEffect, float, float)}.
124     */
125    @Deprecated
126    public boolean onPull(float deltaDistance) {
127        mEdgeEffect.onPull(deltaDistance);
128        return true;
129    }
130
131    /**
132     * A view should call this when content is pulled away from an edge by the user.
133     * This will update the state of the current visual effect and its associated animation.
134     * The host view should always {@link android.view.View#invalidate()} if this method
135     * returns true and draw the results accordingly.
136     *
137     * Views using {@link EdgeEffect} should favor {@link EdgeEffect#onPull(float, float)} when
138     * the displacement of the pull point is known.
139     *
140     * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to
141     *                      1.f (full length of the view) or negative values to express change
142     *                      back toward the edge reached to initiate the effect.
143     * @param displacement The displacement from the starting side of the effect of the point
144     *                     initiating the pull. In the case of touch this is the finger position.
145     *                     Values may be from 0-1.
146     * @return true if the host view should call invalidate, false if it should not.
147     *
148     * @deprecated Use {@link EdgeEffect#onPull(float)} directly.
149     */
150    @Deprecated
151    public boolean onPull(float deltaDistance, float displacement) {
152        IMPL.onPull(mEdgeEffect, deltaDistance, displacement);
153        return true;
154    }
155
156    /**
157     * A view should call this when content is pulled away from an edge by the user.
158     * This will update the state of the current visual effect and its associated animation.
159     * The host view should always {@link android.view.View#invalidate()} after call this method
160     * and draw the results accordingly.
161     *
162     * @param edgeEffect The EdgeEffect that is attached to the view that is getting pulled away
163     *                   from an edge by the user.
164     * @param deltaDistance Change in distance since the last call. Values may be 0 (no change) to
165     *                      1.f (full length of the view) or negative values to express change
166     *                      back toward the edge reached to initiate the effect.
167     * @param displacement The displacement from the starting side of the effect of the point
168     *                     initiating the pull. In the case of touch this is the finger position.
169     *                     Values may be from 0-1.
170     *
171     * @see {@link EdgeEffect#onPull(float, float)}
172     */
173    public static void onPull(EdgeEffect edgeEffect, float deltaDistance, float displacement) {
174        IMPL.onPull(edgeEffect, deltaDistance, displacement);
175    }
176
177    /**
178     * Call when the object is released after being pulled.
179     * This will begin the "decay" phase of the effect. After calling this method
180     * the host view should {@link android.view.View#invalidate()} if this method
181     * returns true and thereby draw the results accordingly.
182     *
183     * @return true if the host view should invalidate, false if it should not.
184     *
185     * @deprecated Use {@link EdgeEffect#onRelease()} directly.
186     */
187    @Deprecated
188    public boolean onRelease() {
189        mEdgeEffect.onRelease();
190        return mEdgeEffect.isFinished();
191    }
192
193    /**
194     * Call when the effect absorbs an impact at the given velocity.
195     * Used when a fling reaches the scroll boundary.
196     *
197     * <p>When using a {@link android.widget.Scroller} or {@link android.widget.OverScroller},
198     * the method <code>getCurrVelocity</code> will provide a reasonable approximation
199     * to use here.</p>
200     *
201     * @param velocity Velocity at impact in pixels per second.
202     * @return true if the host view should invalidate, false if it should not.
203     *
204     * @deprecated Use {@link EdgeEffect#onAbsorb(int)} directly.
205     */
206    @Deprecated
207    public boolean onAbsorb(int velocity) {
208        mEdgeEffect.onAbsorb(velocity);
209        return true;
210    }
211
212    /**
213     * Draw into the provided canvas. Assumes that the canvas has been rotated
214     * accordingly and the size has been set. The effect will be drawn the full
215     * width of X=0 to X=width, beginning from Y=0 and extending to some factor <
216     * 1.f of height.
217     *
218     * @param canvas Canvas to draw into
219     * @return true if drawing should continue beyond this frame to continue the
220     *         animation
221     *
222     * @deprecated Use {@link EdgeEffect#draw(Canvas)} directly.
223     */
224    @Deprecated
225    public boolean draw(Canvas canvas) {
226        return mEdgeEffect.draw(canvas);
227    }
228}
229