1/*
2 * Copyright (C) 2012 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 */
16
17package androidx.core.widget;
18
19import android.content.Context;
20import android.view.animation.Interpolator;
21import android.widget.OverScroller;
22
23/**
24 * Provides access to new {@link android.widget.Scroller Scroller} APIs when available.
25 *
26 * <p>This class provides a platform version-independent mechanism for obeying the
27 * current device's preferred scroll physics and fling behavior. It offers a subset of
28 * the APIs from Scroller or OverScroller.</p>
29 *
30 * @deprecated Use {@link OverScroller} directly.
31 */
32@Deprecated
33public final class ScrollerCompat {
34    OverScroller mScroller;
35
36    /**
37     * @deprecated Use {@link OverScroller} constructor directly.
38     */
39    @Deprecated
40    public static ScrollerCompat create(Context context) {
41        return create(context, null);
42    }
43
44    /**
45     * @deprecated Use {@link OverScroller} constructor directly.
46     */
47    @Deprecated
48    public static ScrollerCompat create(Context context, Interpolator interpolator) {
49        return new ScrollerCompat(context, interpolator);
50    }
51
52    /**
53     * Package protected constructor that allows to specify if API version is newer than ICS.
54     * It is useful for unit testing.
55     */
56    ScrollerCompat(Context context, Interpolator interpolator) {
57        mScroller = interpolator != null ?
58                new OverScroller(context, interpolator) : new OverScroller(context);
59    }
60
61    /**
62     * Returns whether the scroller has finished scrolling.
63     *
64     * @return True if the scroller has finished scrolling, false otherwise.
65     *
66     * @deprecated Use {@link OverScroller#isFinished()} directly.
67     */
68    @Deprecated
69    public boolean isFinished() {
70        return mScroller.isFinished();
71    }
72
73    /**
74     * Returns the current X offset in the scroll.
75     *
76     * @return The new X offset as an absolute distance from the origin.
77     *
78     * @deprecated Use {@link OverScroller#getCurrX()} directly.
79     */
80    @Deprecated
81    public int getCurrX() {
82        return mScroller.getCurrX();
83    }
84
85    /**
86     * Returns the current Y offset in the scroll.
87     *
88     * @return The new Y offset as an absolute distance from the origin.
89     *
90     * @deprecated Use {@link OverScroller#getCurrY()} directly.
91     */
92    @Deprecated
93    public int getCurrY() {
94        return mScroller.getCurrY();
95    }
96
97    /**
98     * @return The final X position for the scroll in progress, if known.
99     *
100     * @deprecated Use {@link OverScroller#getFinalX()} directly.
101     */
102    @Deprecated
103    public int getFinalX() {
104        return mScroller.getFinalX();
105    }
106
107    /**
108     * @return The final Y position for the scroll in progress, if known.
109     *
110     * @deprecated Use {@link OverScroller#getFinalY()} directly.
111     */
112    @Deprecated
113    public int getFinalY() {
114        return mScroller.getFinalY();
115    }
116
117    /**
118     * Returns the current velocity on platform versions that support it.
119     *
120     * <p> This method should only be used as input for nonessential visual effects such as
121     * {@link EdgeEffectCompat}.</p>
122     *
123     * @return The original velocity less the deceleration. Result may be
124     * negative.
125     *
126     * @deprecated Use {@link OverScroller#getCurrVelocity()} directly.
127     */
128    @Deprecated
129    public float getCurrVelocity() {
130        return mScroller.getCurrVelocity();
131    }
132
133    /**
134     * Call this when you want to know the new location.  If it returns true,
135     * the animation is not yet finished.  loc will be altered to provide the
136     * new location.
137     *
138     * @deprecated Use {@link OverScroller#computeScrollOffset()} directly.
139     */
140    @Deprecated
141    public boolean computeScrollOffset() {
142        return mScroller.computeScrollOffset();
143    }
144
145    /**
146     * Start scrolling by providing a starting point and the distance to travel.
147     * The scroll will use the default value of 250 milliseconds for the
148     * duration.
149     *
150     * @param startX Starting horizontal scroll offset in pixels. Positive
151     *        numbers will scroll the content to the left.
152     * @param startY Starting vertical scroll offset in pixels. Positive numbers
153     *        will scroll the content up.
154     * @param dx Horizontal distance to travel. Positive numbers will scroll the
155     *        content to the left.
156     * @param dy Vertical distance to travel. Positive numbers will scroll the
157     *        content up.
158     *
159     * @deprecated Use {@link OverScroller#getCurrX()} directly.
160     */
161    @Deprecated
162    public void startScroll(int startX, int startY, int dx, int dy) {
163        mScroller.startScroll(startX, startY, dx, dy);
164    }
165
166    /**
167     * Start scrolling by providing a starting point and the distance to travel.
168     *
169     * @param startX Starting horizontal scroll offset in pixels. Positive
170     *        numbers will scroll the content to the left.
171     * @param startY Starting vertical scroll offset in pixels. Positive numbers
172     *        will scroll the content up.
173     * @param dx Horizontal distance to travel. Positive numbers will scroll the
174     *        content to the left.
175     * @param dy Vertical distance to travel. Positive numbers will scroll the
176     *        content up.
177     * @param duration Duration of the scroll in milliseconds.
178     *
179     * @deprecated Use {@link OverScroller#startScroll(int, int, int, int, int)} directly.
180     */
181    @Deprecated
182    public void startScroll(int startX, int startY, int dx, int dy, int duration) {
183        mScroller.startScroll(startX, startY, dx, dy, duration);
184    }
185
186    /**
187     * Start scrolling based on a fling gesture. The distance travelled will
188     * depend on the initial velocity of the fling.
189     *
190     * @param startX Starting point of the scroll (X)
191     * @param startY Starting point of the scroll (Y)
192     * @param velocityX Initial velocity of the fling (X) measured in pixels per
193     *        second.
194     * @param velocityY Initial velocity of the fling (Y) measured in pixels per
195     *        second
196     * @param minX Minimum X value. The scroller will not scroll past this
197     *        point.
198     * @param maxX Maximum X value. The scroller will not scroll past this
199     *        point.
200     * @param minY Minimum Y value. The scroller will not scroll past this
201     *        point.
202     * @param maxY Maximum Y value. The scroller will not scroll past this
203     *        point.
204     *
205     * @deprecated Use {@link OverScroller#fling(int, int, int, int, int, int, int, int)} directly.
206     */
207    @Deprecated
208    public void fling(int startX, int startY, int velocityX, int velocityY,
209            int minX, int maxX, int minY, int maxY) {
210        mScroller.fling(startX, startY, velocityX, velocityY, minX, maxX, minY, maxY);
211    }
212
213    /**
214     * Start scrolling based on a fling gesture. The distance travelled will
215     * depend on the initial velocity of the fling.
216     *
217     * @param startX Starting point of the scroll (X)
218     * @param startY Starting point of the scroll (Y)
219     * @param velocityX Initial velocity of the fling (X) measured in pixels per
220     *        second.
221     * @param velocityY Initial velocity of the fling (Y) measured in pixels per
222     *        second
223     * @param minX Minimum X value. The scroller will not scroll past this
224     *        point.
225     * @param maxX Maximum X value. The scroller will not scroll past this
226     *        point.
227     * @param minY Minimum Y value. The scroller will not scroll past this
228     *        point.
229     * @param maxY Maximum Y value. The scroller will not scroll past this
230     *        point.
231     * @param overX Overfling range. If > 0, horizontal overfling in either
232     *            direction will be possible.
233     * @param overY Overfling range. If > 0, vertical overfling in either
234     *            direction will be possible.
235     *
236     * @deprecated Use {@link OverScroller#fling(int, int, int, int, int, int, int, int, int, int)}
237     * directly.
238     */
239    @Deprecated
240    public void fling(int startX, int startY, int velocityX, int velocityY,
241            int minX, int maxX, int minY, int maxY, int overX, int overY) {
242        mScroller.fling(startX, startY, velocityX, velocityY,
243                minX, maxX, minY, maxY, overX, overY);
244    }
245
246    /**
247     * Call this when you want to 'spring back' into a valid coordinate range.
248     *
249     * @param startX Starting X coordinate
250     * @param startY Starting Y coordinate
251     * @param minX Minimum valid X value
252     * @param maxX Maximum valid X value
253     * @param minY Minimum valid Y value
254     * @param maxY Maximum valid Y value
255     * @return true if a springback was initiated, false if startX and startY were
256     *          already within the valid range.
257     *
258     * @deprecated Use {@link OverScroller#springBack(int, int, int, int, int, int)} directly.
259     */
260    @Deprecated
261    public boolean springBack(int startX, int startY, int minX, int maxX, int minY, int maxY) {
262        return mScroller.springBack(startX, startY, minX, maxX, minY, maxY);
263    }
264
265    /**
266     * Stops the animation. Aborting the animation causes the scroller to move to the final x and y
267     * position.
268     *
269     * @deprecated Use {@link OverScroller#abortAnimation()} directly.
270     */
271    @Deprecated
272    public void abortAnimation() {
273        mScroller.abortAnimation();
274    }
275
276
277    /**
278     * Notify the scroller that we've reached a horizontal boundary.
279     * Normally the information to handle this will already be known
280     * when the animation is started, such as in a call to one of the
281     * fling functions. However there are cases where this cannot be known
282     * in advance. This function will transition the current motion and
283     * animate from startX to finalX as appropriate.
284     *
285     * @param startX Starting/current X position
286     * @param finalX Desired final X position
287     * @param overX Magnitude of overscroll allowed. This should be the maximum
288     *              desired distance from finalX. Absolute value - must be positive.
289     *
290     * @deprecated Use {@link OverScroller#notifyHorizontalEdgeReached(int, int, int)} directly.
291     */
292    @Deprecated
293    public void notifyHorizontalEdgeReached(int startX, int finalX, int overX) {
294        mScroller.notifyHorizontalEdgeReached(startX, finalX, overX);
295    }
296
297    /**
298     * Notify the scroller that we've reached a vertical boundary.
299     * Normally the information to handle this will already be known
300     * when the animation is started, such as in a call to one of the
301     * fling functions. However there are cases where this cannot be known
302     * in advance. This function will animate a parabolic motion from
303     * startY to finalY.
304     *
305     * @param startY Starting/current Y position
306     * @param finalY Desired final Y position
307     * @param overY Magnitude of overscroll allowed. This should be the maximum
308     *              desired distance from finalY. Absolute value - must be positive.
309     *
310     * @deprecated Use {@link OverScroller#notifyVerticalEdgeReached(int, int, int)} directly.
311     */
312    @Deprecated
313    public void notifyVerticalEdgeReached(int startY, int finalY, int overY) {
314        mScroller.notifyVerticalEdgeReached(startY, finalY, overY);
315    }
316
317    /**
318     * Returns whether the current Scroller is currently returning to a valid position.
319     * Valid bounds were provided by the
320     * {@link #fling(int, int, int, int, int, int, int, int, int, int)} method.
321     *
322     * One should check this value before calling
323     * {@link #startScroll(int, int, int, int)} as the interpolation currently in progress
324     * to restore a valid position will then be stopped. The caller has to take into account
325     * the fact that the started scroll will start from an overscrolled position.
326     *
327     * @return true when the current position is overscrolled and in the process of
328     *         interpolating back to a valid value.
329     *
330     * @deprecated Use {@link OverScroller#isOverScrolled()} directly.
331     */
332    @Deprecated
333    public boolean isOverScrolled() {
334        return mScroller.isOverScrolled();
335    }
336}
337