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