1/*
2 * Copyright (C) 2010 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 android.animation;
18
19import java.util.ArrayList;
20
21/**
22 * This is the superclass for classes which provide basic support for animations which can be
23 * started, ended, and have <code>AnimatorListeners</code> added to them.
24 */
25public abstract class Animator implements Cloneable {
26
27
28    /**
29     * The set of listeners to be sent events through the life of an animation.
30     */
31    ArrayList<AnimatorListener> mListeners = null;
32
33    /**
34     * Starts this animation. If the animation has a nonzero startDelay, the animation will start
35     * running after that delay elapses. A non-delayed animation will have its initial
36     * value(s) set immediately, followed by calls to
37     * {@link AnimatorListener#onAnimationStart(Animator)} for any listeners of this animator.
38     *
39     * <p>The animation started by calling this method will be run on the thread that called
40     * this method. This thread should have a Looper on it (a runtime exception will be thrown if
41     * this is not the case). Also, if the animation will animate
42     * properties of objects in the view hierarchy, then the calling thread should be the UI
43     * thread for that view hierarchy.</p>
44     *
45     */
46    public void start() {
47    }
48
49    /**
50     * Cancels the animation. Unlike {@link #end()}, <code>cancel()</code> causes the animation to
51     * stop in its tracks, sending an
52     * {@link android.animation.Animator.AnimatorListener#onAnimationCancel(Animator)} to
53     * its listeners, followed by an
54     * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} message.
55     *
56     * <p>This method must be called on the thread that is running the animation.</p>
57     */
58    public void cancel() {
59    }
60
61    /**
62     * Ends the animation. This causes the animation to assign the end value of the property being
63     * animated, then calling the
64     * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} method on
65     * its listeners.
66     *
67     * <p>This method must be called on the thread that is running the animation.</p>
68     */
69    public void end() {
70    }
71
72    /**
73     * The amount of time, in milliseconds, to delay starting the animation after
74     * {@link #start()} is called.
75     *
76     * @return the number of milliseconds to delay running the animation
77     */
78    public abstract long getStartDelay();
79
80    /**
81     * The amount of time, in milliseconds, to delay starting the animation after
82     * {@link #start()} is called.
83
84     * @param startDelay The amount of the delay, in milliseconds
85     */
86    public abstract void setStartDelay(long startDelay);
87
88
89    /**
90     * Sets the length of the animation.
91     *
92     * @param duration The length of the animation, in milliseconds.
93     */
94    public abstract Animator setDuration(long duration);
95
96    /**
97     * Gets the length of the animation.
98     *
99     * @return The length of the animation, in milliseconds.
100     */
101    public abstract long getDuration();
102
103    /**
104     * The time interpolator used in calculating the elapsed fraction of this animation. The
105     * interpolator determines whether the animation runs with linear or non-linear motion,
106     * such as acceleration and deceleration. The default value is
107     * {@link android.view.animation.AccelerateDecelerateInterpolator}
108     *
109     * @param value the interpolator to be used by this animation
110     */
111    public abstract void setInterpolator(TimeInterpolator value);
112
113    /**
114     * Returns whether this Animator is currently running (having been started and gone past any
115     * initial startDelay period and not yet ended).
116     *
117     * @return Whether the Animator is running.
118     */
119    public abstract boolean isRunning();
120
121    /**
122     * Returns whether this Animator has been started and not yet ended. This state is a superset
123     * of the state of {@link #isRunning()}, because an Animator with a nonzero
124     * {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during the
125     * delay phase, whereas {@link #isRunning()} will return true only after the delay phase
126     * is complete.
127     *
128     * @return Whether the Animator has been started and not yet ended.
129     */
130    public boolean isStarted() {
131        // Default method returns value for isRunning(). Subclasses should override to return a
132        // real value.
133        return isRunning();
134    }
135
136    /**
137     * Adds a listener to the set of listeners that are sent events through the life of an
138     * animation, such as start, repeat, and end.
139     *
140     * @param listener the listener to be added to the current set of listeners for this animation.
141     */
142    public void addListener(AnimatorListener listener) {
143        if (mListeners == null) {
144            mListeners = new ArrayList<AnimatorListener>();
145        }
146        mListeners.add(listener);
147    }
148
149    /**
150     * Removes a listener from the set listening to this animation.
151     *
152     * @param listener the listener to be removed from the current set of listeners for this
153     *                 animation.
154     */
155    public void removeListener(AnimatorListener listener) {
156        if (mListeners == null) {
157            return;
158        }
159        mListeners.remove(listener);
160        if (mListeners.size() == 0) {
161            mListeners = null;
162        }
163    }
164
165    /**
166     * Gets the set of {@link android.animation.Animator.AnimatorListener} objects that are currently
167     * listening for events on this <code>Animator</code> object.
168     *
169     * @return ArrayList<AnimatorListener> The set of listeners.
170     */
171    public ArrayList<AnimatorListener> getListeners() {
172        return mListeners;
173    }
174
175    /**
176     * Removes all listeners from this object. This is equivalent to calling
177     * <code>getListeners()</code> followed by calling <code>clear()</code> on the
178     * returned list of listeners.
179     */
180    public void removeAllListeners() {
181        if (mListeners != null) {
182            mListeners.clear();
183            mListeners = null;
184        }
185    }
186
187    @Override
188    public Animator clone() {
189        try {
190            final Animator anim = (Animator) super.clone();
191            if (mListeners != null) {
192                ArrayList<AnimatorListener> oldListeners = mListeners;
193                anim.mListeners = new ArrayList<AnimatorListener>();
194                int numListeners = oldListeners.size();
195                for (int i = 0; i < numListeners; ++i) {
196                    anim.mListeners.add(oldListeners.get(i));
197                }
198            }
199            return anim;
200        } catch (CloneNotSupportedException e) {
201           throw new AssertionError();
202        }
203    }
204
205    /**
206     * This method tells the object to use appropriate information to extract
207     * starting values for the animation. For example, a AnimatorSet object will pass
208     * this call to its child objects to tell them to set up the values. A
209     * ObjectAnimator object will use the information it has about its target object
210     * and PropertyValuesHolder objects to get the start values for its properties.
211     * A ValueAnimator object will ignore the request since it does not have enough
212     * information (such as a target object) to gather these values.
213     */
214    public void setupStartValues() {
215    }
216
217    /**
218     * This method tells the object to use appropriate information to extract
219     * ending values for the animation. For example, a AnimatorSet object will pass
220     * this call to its child objects to tell them to set up the values. A
221     * ObjectAnimator object will use the information it has about its target object
222     * and PropertyValuesHolder objects to get the start values for its properties.
223     * A ValueAnimator object will ignore the request since it does not have enough
224     * information (such as a target object) to gather these values.
225     */
226    public void setupEndValues() {
227    }
228
229    /**
230     * Sets the target object whose property will be animated by this animation. Not all subclasses
231     * operate on target objects (for example, {@link ValueAnimator}, but this method
232     * is on the superclass for the convenience of dealing generically with those subclasses
233     * that do handle targets.
234     *
235     * @param target The object being animated
236     */
237    public void setTarget(Object target) {
238    }
239
240    /**
241     * <p>An animation listener receives notifications from an animation.
242     * Notifications indicate animation related events, such as the end or the
243     * repetition of the animation.</p>
244     */
245    public static interface AnimatorListener {
246        /**
247         * <p>Notifies the start of the animation.</p>
248         *
249         * @param animation The started animation.
250         */
251        void onAnimationStart(Animator animation);
252
253        /**
254         * <p>Notifies the end of the animation. This callback is not invoked
255         * for animations with repeat count set to INFINITE.</p>
256         *
257         * @param animation The animation which reached its end.
258         */
259        void onAnimationEnd(Animator animation);
260
261        /**
262         * <p>Notifies the cancellation of the animation. This callback is not invoked
263         * for animations with repeat count set to INFINITE.</p>
264         *
265         * @param animation The animation which was canceled.
266         */
267        void onAnimationCancel(Animator animation);
268
269        /**
270         * <p>Notifies the repetition of the animation.</p>
271         *
272         * @param animation The animation which was repeated.
273         */
274        void onAnimationRepeat(Animator animation);
275    }
276}
277