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