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