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 android.content.res.ConstantState; 20 21 import java.util.ArrayList; 22 23 /** 24 * This is the superclass for classes which provide basic support for animations which can be 25 * started, ended, and have <code>AnimatorListeners</code> added to them. 26 */ 27 public abstract class Animator implements Cloneable { 28 29 /** 30 * The set of listeners to be sent events through the life of an animation. 31 */ 32 ArrayList<AnimatorListener> mListeners = null; 33 34 /** 35 * The set of listeners to be sent pause/resume events through the life 36 * of an animation. 37 */ 38 ArrayList<AnimatorPauseListener> mPauseListeners = null; 39 40 /** 41 * Whether this animator is currently in a paused state. 42 */ 43 boolean mPaused = false; 44 45 /** 46 * A set of flags which identify the type of configuration changes that can affect this 47 * Animator. Used by the Animator cache. 48 */ 49 int mChangingConfigurations = 0; 50 51 /** 52 * If this animator is inflated from a constant state, keep a reference to it so that 53 * ConstantState will not be garbage collected until this animator is collected 54 */ 55 private AnimatorConstantState mConstantState; 56 57 /** 58 * Starts this animation. If the animation has a nonzero startDelay, the animation will start 59 * running after that delay elapses. A non-delayed animation will have its initial 60 * value(s) set immediately, followed by calls to 61 * {@link AnimatorListener#onAnimationStart(Animator)} for any listeners of this animator. 62 * 63 * <p>The animation started by calling this method will be run on the thread that called 64 * this method. This thread should have a Looper on it (a runtime exception will be thrown if 65 * this is not the case). Also, if the animation will animate 66 * properties of objects in the view hierarchy, then the calling thread should be the UI 67 * thread for that view hierarchy.</p> 68 * 69 */ 70 public void start() { 71 } 72 73 /** 74 * Cancels the animation. Unlike {@link #end()}, <code>cancel()</code> causes the animation to 75 * stop in its tracks, sending an 76 * {@link android.animation.Animator.AnimatorListener#onAnimationCancel(Animator)} to 77 * its listeners, followed by an 78 * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} message. 79 * 80 * <p>This method must be called on the thread that is running the animation.</p> 81 */ 82 public void cancel() { 83 } 84 85 /** 86 * Ends the animation. This causes the animation to assign the end value of the property being 87 * animated, then calling the 88 * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} method on 89 * its listeners. 90 * 91 * <p>This method must be called on the thread that is running the animation.</p> 92 */ 93 public void end() { 94 } 95 96 /** 97 * Pauses a running animation. This method should only be called on the same thread on 98 * which the animation was started. If the animation has not yet been {@link 99 * #isStarted() started} or has since ended, then the call is ignored. Paused 100 * animations can be resumed by calling {@link #resume()}. 101 * 102 * @see #resume() 103 * @see #isPaused() 104 * @see AnimatorPauseListener 105 */ 106 public void pause() { 107 if (isStarted() && !mPaused) { 108 mPaused = true; 109 if (mPauseListeners != null) { 110 ArrayList<AnimatorPauseListener> tmpListeners = 111 (ArrayList<AnimatorPauseListener>) mPauseListeners.clone(); 112 int numListeners = tmpListeners.size(); 113 for (int i = 0; i < numListeners; ++i) { 114 tmpListeners.get(i).onAnimationPause(this); 115 } 116 } 117 } 118 } 119 120 /** 121 * Resumes a paused animation, causing the animator to pick up where it left off 122 * when it was paused. This method should only be called on the same thread on 123 * which the animation was started. Calls to resume() on an animator that is 124 * not currently paused will be ignored. 125 * 126 * @see #pause() 127 * @see #isPaused() 128 * @see AnimatorPauseListener 129 */ 130 public void resume() { 131 if (mPaused) { 132 mPaused = false; 133 if (mPauseListeners != null) { 134 ArrayList<AnimatorPauseListener> tmpListeners = 135 (ArrayList<AnimatorPauseListener>) mPauseListeners.clone(); 136 int numListeners = tmpListeners.size(); 137 for (int i = 0; i < numListeners; ++i) { 138 tmpListeners.get(i).onAnimationResume(this); 139 } 140 } 141 } 142 } 143 144 /** 145 * Returns whether this animator is currently in a paused state. 146 * 147 * @return True if the animator is currently paused, false otherwise. 148 * 149 * @see #pause() 150 * @see #resume() 151 */ 152 public boolean isPaused() { 153 return mPaused; 154 } 155 156 /** 157 * The amount of time, in milliseconds, to delay processing the animation 158 * after {@link #start()} is called. 159 * 160 * @return the number of milliseconds to delay running the animation 161 */ 162 public abstract long getStartDelay(); 163 164 /** 165 * The amount of time, in milliseconds, to delay processing the animation 166 * after {@link #start()} is called. 167 168 * @param startDelay The amount of the delay, in milliseconds 169 */ 170 public abstract void setStartDelay(long startDelay); 171 172 /** 173 * Sets the duration of the animation. 174 * 175 * @param duration The length of the animation, in milliseconds. 176 */ 177 public abstract Animator setDuration(long duration); 178 179 /** 180 * Gets the duration of the animation. 181 * 182 * @return The length of the animation, in milliseconds. 183 */ 184 public abstract long getDuration(); 185 186 /** 187 * The time interpolator used in calculating the elapsed fraction of the 188 * animation. The interpolator determines whether the animation runs with 189 * linear or non-linear motion, such as acceleration and deceleration. The 190 * default value is {@link android.view.animation.AccelerateDecelerateInterpolator}. 191 * 192 * @param value the interpolator to be used by this animation 193 */ 194 public abstract void setInterpolator(TimeInterpolator value); 195 196 /** 197 * Returns the timing interpolator that this animation uses. 198 * 199 * @return The timing interpolator for this animation. 200 */ 201 public TimeInterpolator getInterpolator() { 202 return null; 203 } 204 205 /** 206 * Returns whether this Animator is currently running (having been started and gone past any 207 * initial startDelay period and not yet ended). 208 * 209 * @return Whether the Animator is running. 210 */ 211 public abstract boolean isRunning(); 212 213 /** 214 * Returns whether this Animator has been started and not yet ended. This state is a superset 215 * of the state of {@link #isRunning()}, because an Animator with a nonzero 216 * {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during the 217 * delay phase, whereas {@link #isRunning()} will return true only after the delay phase 218 * is complete. 219 * 220 * @return Whether the Animator has been started and not yet ended. 221 */ 222 public boolean isStarted() { 223 // Default method returns value for isRunning(). Subclasses should override to return a 224 // real value. 225 return isRunning(); 226 } 227 228 /** 229 * Adds a listener to the set of listeners that are sent events through the life of an 230 * animation, such as start, repeat, and end. 231 * 232 * @param listener the listener to be added to the current set of listeners for this animation. 233 */ 234 public void addListener(AnimatorListener listener) { 235 if (mListeners == null) { 236 mListeners = new ArrayList<AnimatorListener>(); 237 } 238 mListeners.add(listener); 239 } 240 241 /** 242 * Removes a listener from the set listening to this animation. 243 * 244 * @param listener the listener to be removed from the current set of listeners for this 245 * animation. 246 */ 247 public void removeListener(AnimatorListener listener) { 248 if (mListeners == null) { 249 return; 250 } 251 mListeners.remove(listener); 252 if (mListeners.size() == 0) { 253 mListeners = null; 254 } 255 } 256 257 /** 258 * Gets the set of {@link android.animation.Animator.AnimatorListener} objects that are currently 259 * listening for events on this <code>Animator</code> object. 260 * 261 * @return ArrayList<AnimatorListener> The set of listeners. 262 */ 263 public ArrayList<AnimatorListener> getListeners() { 264 return mListeners; 265 } 266 267 /** 268 * Adds a pause listener to this animator. 269 * 270 * @param listener the listener to be added to the current set of pause listeners 271 * for this animation. 272 */ 273 public void addPauseListener(AnimatorPauseListener listener) { 274 if (mPauseListeners == null) { 275 mPauseListeners = new ArrayList<AnimatorPauseListener>(); 276 } 277 mPauseListeners.add(listener); 278 } 279 280 /** 281 * Removes a pause listener from the set listening to this animation. 282 * 283 * @param listener the listener to be removed from the current set of pause 284 * listeners for this animation. 285 */ 286 public void removePauseListener(AnimatorPauseListener listener) { 287 if (mPauseListeners == null) { 288 return; 289 } 290 mPauseListeners.remove(listener); 291 if (mPauseListeners.size() == 0) { 292 mPauseListeners = null; 293 } 294 } 295 296 /** 297 * Removes all {@link #addListener(android.animation.Animator.AnimatorListener) listeners} 298 * and {@link #addPauseListener(android.animation.Animator.AnimatorPauseListener) 299 * pauseListeners} from this object. 300 */ 301 public void removeAllListeners() { 302 if (mListeners != null) { 303 mListeners.clear(); 304 mListeners = null; 305 } 306 if (mPauseListeners != null) { 307 mPauseListeners.clear(); 308 mPauseListeners = null; 309 } 310 } 311 312 /** 313 * Return a mask of the configuration parameters for which this animator may change, requiring 314 * that it should be re-created from Resources. The default implementation returns whatever 315 * value was provided through setChangingConfigurations(int) or 0 by default. 316 * 317 * @return Returns a mask of the changing configuration parameters, as defined by 318 * {@link android.content.pm.ActivityInfo}. 319 * @see android.content.pm.ActivityInfo 320 * @hide 321 */ 322 public int getChangingConfigurations() { 323 return mChangingConfigurations; 324 } 325 326 /** 327 * Set a mask of the configuration parameters for which this animator may change, requiring 328 * that it be re-created from resource. 329 * 330 * @param configs A mask of the changing configuration parameters, as 331 * defined by {@link android.content.pm.ActivityInfo}. 332 * 333 * @see android.content.pm.ActivityInfo 334 * @hide 335 */ 336 public void setChangingConfigurations(int configs) { 337 mChangingConfigurations = configs; 338 } 339 340 /** 341 * Sets the changing configurations value to the union of the current changing configurations 342 * and the provided configs. 343 * This method is called while loading the animator. 344 * @hide 345 */ 346 public void appendChangingConfigurations(int configs) { 347 mChangingConfigurations |= configs; 348 } 349 350 /** 351 * Return a {@link android.content.res.ConstantState} instance that holds the shared state of 352 * this Animator. 353 * <p> 354 * This constant state is used to create new instances of this animator when needed, instead 355 * of re-loading it from resources. Default implementation creates a new 356 * {@link AnimatorConstantState}. You can override this method to provide your custom logic or 357 * return null if you don't want this animator to be cached. 358 * 359 * @return The ConfigurationBoundResourceCache.BaseConstantState associated to this Animator. 360 * @see android.content.res.ConstantState 361 * @see #clone() 362 * @hide 363 */ 364 public ConstantState<Animator> createConstantState() { 365 return new AnimatorConstantState(this); 366 } 367 368 @Override 369 public Animator clone() { 370 try { 371 final Animator anim = (Animator) super.clone(); 372 if (mListeners != null) { 373 anim.mListeners = new ArrayList<AnimatorListener>(mListeners); 374 } 375 if (mPauseListeners != null) { 376 anim.mPauseListeners = new ArrayList<AnimatorPauseListener>(mPauseListeners); 377 } 378 return anim; 379 } catch (CloneNotSupportedException e) { 380 throw new AssertionError(); 381 } 382 } 383 384 /** 385 * This method tells the object to use appropriate information to extract 386 * starting values for the animation. For example, a AnimatorSet object will pass 387 * this call to its child objects to tell them to set up the values. A 388 * ObjectAnimator object will use the information it has about its target object 389 * and PropertyValuesHolder objects to get the start values for its properties. 390 * A ValueAnimator object will ignore the request since it does not have enough 391 * information (such as a target object) to gather these values. 392 */ 393 public void setupStartValues() { 394 } 395 396 /** 397 * This method tells the object to use appropriate information to extract 398 * ending values for the animation. For example, a AnimatorSet object will pass 399 * this call to its child objects to tell them to set up the values. A 400 * ObjectAnimator object will use the information it has about its target object 401 * and PropertyValuesHolder objects to get the start values for its properties. 402 * A ValueAnimator object will ignore the request since it does not have enough 403 * information (such as a target object) to gather these values. 404 */ 405 public void setupEndValues() { 406 } 407 408 /** 409 * Sets the target object whose property will be animated by this animation. Not all subclasses 410 * operate on target objects (for example, {@link ValueAnimator}, but this method 411 * is on the superclass for the convenience of dealing generically with those subclasses 412 * that do handle targets. 413 * 414 * @param target The object being animated 415 */ 416 public void setTarget(Object target) { 417 } 418 419 // Hide reverse() and canReverse() for now since reverse() only work for simple 420 // cases, like we don't support sequential, neither startDelay. 421 // TODO: make reverse() works for all the Animators. 422 /** 423 * @hide 424 */ 425 public boolean canReverse() { 426 return false; 427 } 428 429 /** 430 * @hide 431 */ 432 public void reverse() { 433 throw new IllegalStateException("Reverse is not supported"); 434 } 435 436 /** 437 * <p>An animation listener receives notifications from an animation. 438 * Notifications indicate animation related events, such as the end or the 439 * repetition of the animation.</p> 440 */ 441 public static interface AnimatorListener { 442 /** 443 * <p>Notifies the start of the animation.</p> 444 * 445 * @param animation The started animation. 446 */ 447 void onAnimationStart(Animator animation); 448 449 /** 450 * <p>Notifies the end of the animation. This callback is not invoked 451 * for animations with repeat count set to INFINITE.</p> 452 * 453 * @param animation The animation which reached its end. 454 */ 455 void onAnimationEnd(Animator animation); 456 457 /** 458 * <p>Notifies the cancellation of the animation. This callback is not invoked 459 * for animations with repeat count set to INFINITE.</p> 460 * 461 * @param animation The animation which was canceled. 462 */ 463 void onAnimationCancel(Animator animation); 464 465 /** 466 * <p>Notifies the repetition of the animation.</p> 467 * 468 * @param animation The animation which was repeated. 469 */ 470 void onAnimationRepeat(Animator animation); 471 } 472 473 /** 474 * A pause listener receives notifications from an animation when the 475 * animation is {@link #pause() paused} or {@link #resume() resumed}. 476 * 477 * @see #addPauseListener(AnimatorPauseListener) 478 */ 479 public static interface AnimatorPauseListener { 480 /** 481 * <p>Notifies that the animation was paused.</p> 482 * 483 * @param animation The animaton being paused. 484 * @see #pause() 485 */ 486 void onAnimationPause(Animator animation); 487 488 /** 489 * <p>Notifies that the animation was resumed, after being 490 * previously paused.</p> 491 * 492 * @param animation The animation being resumed. 493 * @see #resume() 494 */ 495 void onAnimationResume(Animator animation); 496 } 497 498 /** 499 * <p>Whether or not the Animator is allowed to run asynchronously off of 500 * the UI thread. This is a hint that informs the Animator that it is 501 * OK to run the animation off-thread, however the Animator may decide 502 * that it must run the animation on the UI thread anyway. 503 * 504 * <p>Regardless of whether or not the animation runs asynchronously, all 505 * listener callbacks will be called on the UI thread.</p> 506 * 507 * <p>To be able to use this hint the following must be true:</p> 508 * <ol> 509 * <li>The animator is immutable while {@link #isStarted()} is true. Requests 510 * to change duration, delay, etc... may be ignored.</li> 511 * <li>Lifecycle callback events may be asynchronous. Events such as 512 * {@link Animator.AnimatorListener#onAnimationEnd(Animator)} or 513 * {@link Animator.AnimatorListener#onAnimationRepeat(Animator)} may end up delayed 514 * as they must be posted back to the UI thread, and any actions performed 515 * by those callbacks (such as starting new animations) will not happen 516 * in the same frame.</li> 517 * <li>State change requests ({@link #cancel()}, {@link #end()}, {@link #reverse()}, etc...) 518 * may be asynchronous. It is guaranteed that all state changes that are 519 * performed on the UI thread in the same frame will be applied as a single 520 * atomic update, however that frame may be the current frame, 521 * the next frame, or some future frame. This will also impact the observed 522 * state of the Animator. For example, {@link #isStarted()} may still return true 523 * after a call to {@link #end()}. Using the lifecycle callbacks is preferred over 524 * queries to {@link #isStarted()}, {@link #isRunning()}, and {@link #isPaused()} 525 * for this reason.</li> 526 * </ol> 527 * @hide 528 */ 529 public void setAllowRunningAsynchronously(boolean mayRunAsync) { 530 // It is up to subclasses to support this, if they can. 531 } 532 533 /** 534 * Creates a {@link ConstantState} which holds changing configurations information associated 535 * with the given Animator. 536 * <p> 537 * When {@link #newInstance()} is called, default implementation clones the Animator. 538 */ 539 private static class AnimatorConstantState extends ConstantState<Animator> { 540 541 final Animator mAnimator; 542 int mChangingConf; 543 544 public AnimatorConstantState(Animator animator) { 545 mAnimator = animator; 546 // ensure a reference back to here so that constante state is not gc'ed. 547 mAnimator.mConstantState = this; 548 mChangingConf = mAnimator.getChangingConfigurations(); 549 } 550 551 @Override 552 public int getChangingConfigurations() { 553 return mChangingConf; 554 } 555 556 @Override 557 public Animator newInstance() { 558 final Animator clone = mAnimator.clone(); 559 clone.mConstantState = this; 560 return clone; 561 } 562 } 563 } 564