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 17 package android.animation; 18 19 import 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 */ 25 public 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
