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