ValueAnimator.java revision 66d48566537bd2d037e1eff919542731b93fa85c
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 android.annotation.CallSuper; 20import android.os.Looper; 21import android.os.Trace; 22import android.util.AndroidRuntimeException; 23import android.util.Log; 24import android.view.animation.AccelerateDecelerateInterpolator; 25import android.view.animation.AnimationUtils; 26import android.view.animation.LinearInterpolator; 27 28import java.util.ArrayList; 29import java.util.HashMap; 30 31/** 32 * This class provides a simple timing engine for running animations 33 * which calculate animated values and set them on target objects. 34 * 35 * <p>There is a single timing pulse that all animations use. It runs in a 36 * custom handler to ensure that property changes happen on the UI thread.</p> 37 * 38 * <p>By default, ValueAnimator uses non-linear time interpolation, via the 39 * {@link AccelerateDecelerateInterpolator} class, which accelerates into and decelerates 40 * out of an animation. This behavior can be changed by calling 41 * {@link ValueAnimator#setInterpolator(TimeInterpolator)}.</p> 42 * 43 * <p>Animators can be created from either code or resource files. Here is an example 44 * of a ValueAnimator resource file:</p> 45 * 46 * {@sample development/samples/ApiDemos/res/anim/animator.xml ValueAnimatorResources} 47 * 48 * <p>It is also possible to use a combination of {@link PropertyValuesHolder} and 49 * {@link Keyframe} resource tags to create a multi-step animation. 50 * Note that you can specify explicit fractional values (from 0 to 1) for 51 * each keyframe to determine when, in the overall duration, the animation should arrive at that 52 * value. Alternatively, you can leave the fractions off and the keyframes will be equally 53 * distributed within the total duration:</p> 54 * 55 * {@sample development/samples/ApiDemos/res/anim/value_animator_pvh_kf.xml 56 * ValueAnimatorKeyframeResources} 57 * 58 * <div class="special reference"> 59 * <h3>Developer Guides</h3> 60 * <p>For more information about animating with {@code ValueAnimator}, read the 61 * <a href="{@docRoot}guide/topics/graphics/prop-animation.html#value-animator">Property 62 * Animation</a> developer guide.</p> 63 * </div> 64 */ 65@SuppressWarnings("unchecked") 66public class ValueAnimator extends Animator implements AnimationHandler.AnimationFrameCallback { 67 private static final String TAG = "ValueAnimator"; 68 private static final boolean DEBUG = false; 69 70 /** 71 * Internal constants 72 */ 73 private static float sDurationScale = 1.0f; 74 75 /** 76 * Internal variables 77 * NOTE: This object implements the clone() method, making a deep copy of any referenced 78 * objects. As other non-trivial fields are added to this class, make sure to add logic 79 * to clone() to make deep copies of them. 80 */ 81 82 /** 83 * The first time that the animation's animateFrame() method is called. This time is used to 84 * determine elapsed time (and therefore the elapsed fraction) in subsequent calls 85 * to animateFrame(). 86 * 87 * Whenever mStartTime is set, you must also update mStartTimeCommitted. 88 */ 89 long mStartTime; 90 91 /** 92 * When true, the start time has been firmly committed as a chosen reference point in 93 * time by which the progress of the animation will be evaluated. When false, the 94 * start time may be updated when the first animation frame is committed so as 95 * to compensate for jank that may have occurred between when the start time was 96 * initialized and when the frame was actually drawn. 97 * 98 * This flag is generally set to false during the first frame of the animation 99 * when the animation playing state transitions from STOPPED to RUNNING or 100 * resumes after having been paused. This flag is set to true when the start time 101 * is firmly committed and should not be further compensated for jank. 102 */ 103 boolean mStartTimeCommitted; 104 105 /** 106 * Set when setCurrentPlayTime() is called. If negative, animation is not currently seeked 107 * to a value. 108 */ 109 float mSeekFraction = -1; 110 111 /** 112 * Set on the next frame after pause() is called, used to calculate a new startTime 113 * or delayStartTime which allows the animator to continue from the point at which 114 * it was paused. If negative, has not yet been set. 115 */ 116 private long mPauseTime; 117 118 /** 119 * Set when an animator is resumed. This triggers logic in the next frame which 120 * actually resumes the animator. 121 */ 122 private boolean mResumed = false; 123 124 // The time interpolator to be used if none is set on the animation 125 private static final TimeInterpolator sDefaultInterpolator = 126 new AccelerateDecelerateInterpolator(); 127 128 /** 129 * Flag to indicate whether this animator is playing in reverse mode, specifically 130 * by being started or interrupted by a call to reverse(). This flag is different than 131 * mPlayingBackwards, which indicates merely whether the current iteration of the 132 * animator is playing in reverse. It is used in corner cases to determine proper end 133 * behavior. 134 */ 135 private boolean mReversing; 136 137 /** 138 * Tracks the overall fraction of the animation, ranging from 0 to mRepeatCount + 1 139 */ 140 private float mOverallFraction = 0f; 141 142 /** 143 * Tracks current elapsed/eased fraction, for querying in getAnimatedFraction(). 144 * This is calculated by interpolating the fraction (range: [0, 1]) in the current iteration. 145 */ 146 private float mCurrentFraction = 0f; 147 148 /** 149 * Tracks the time (in milliseconds) when the last frame arrived. 150 */ 151 private long mLastFrameTime = 0; 152 153 /** 154 * Additional playing state to indicate whether an animator has been start()'d. There is 155 * some lag between a call to start() and the first animation frame. We should still note 156 * that the animation has been started, even if it's first animation frame has not yet 157 * happened, and reflect that state in isRunning(). 158 * Note that delayed animations are different: they are not started until their first 159 * animation frame, which occurs after their delay elapses. 160 */ 161 private boolean mRunning = false; 162 163 /** 164 * Additional playing state to indicate whether an animator has been start()'d, whether or 165 * not there is a nonzero startDelay. 166 */ 167 private boolean mStarted = false; 168 169 /** 170 * Tracks whether we've notified listeners of the onAnimationStart() event. This can be 171 * complex to keep track of since we notify listeners at different times depending on 172 * startDelay and whether start() was called before end(). 173 */ 174 private boolean mStartListenersCalled = false; 175 176 /** 177 * Flag that denotes whether the animation is set up and ready to go. Used to 178 * set up animation that has not yet been started. 179 */ 180 boolean mInitialized = false; 181 182 /** 183 * Flag that tracks whether animation has been requested to end. 184 */ 185 private boolean mAnimationEndRequested = false; 186 187 // 188 // Backing variables 189 // 190 191 // How long the animation should last in ms 192 private long mDuration = 300; 193 194 // The amount of time in ms to delay starting the animation after start() is called. Note 195 // that this start delay is unscaled. When there is a duration scale set on the animator, the 196 // scaling factor will be applied to this delay. 197 private long mStartDelay = 0; 198 199 // The number of times the animation will repeat. The default is 0, which means the animation 200 // will play only once 201 private int mRepeatCount = 0; 202 203 /** 204 * The type of repetition that will occur when repeatMode is nonzero. RESTART means the 205 * animation will start from the beginning on every new cycle. REVERSE means the animation 206 * will reverse directions on each iteration. 207 */ 208 private int mRepeatMode = RESTART; 209 210 /** 211 * The time interpolator to be used. The elapsed fraction of the animation will be passed 212 * through this interpolator to calculate the interpolated fraction, which is then used to 213 * calculate the animated values. 214 */ 215 private TimeInterpolator mInterpolator = sDefaultInterpolator; 216 217 /** 218 * The set of listeners to be sent events through the life of an animation. 219 */ 220 ArrayList<AnimatorUpdateListener> mUpdateListeners = null; 221 222 /** 223 * The property/value sets being animated. 224 */ 225 PropertyValuesHolder[] mValues; 226 227 /** 228 * A hashmap of the PropertyValuesHolder objects. This map is used to lookup animated values 229 * by property name during calls to getAnimatedValue(String). 230 */ 231 HashMap<String, PropertyValuesHolder> mValuesMap; 232 233 /** 234 * Public constants 235 */ 236 237 /** 238 * When the animation reaches the end and <code>repeatCount</code> is INFINITE 239 * or a positive value, the animation restarts from the beginning. 240 */ 241 public static final int RESTART = 1; 242 /** 243 * When the animation reaches the end and <code>repeatCount</code> is INFINITE 244 * or a positive value, the animation reverses direction on every iteration. 245 */ 246 public static final int REVERSE = 2; 247 /** 248 * This value used used with the {@link #setRepeatCount(int)} property to repeat 249 * the animation indefinitely. 250 */ 251 public static final int INFINITE = -1; 252 253 /** 254 * @hide 255 */ 256 public static void setDurationScale(float durationScale) { 257 sDurationScale = durationScale; 258 } 259 260 /** 261 * @hide 262 */ 263 public static float getDurationScale() { 264 return sDurationScale; 265 } 266 267 /** 268 * Creates a new ValueAnimator object. This default constructor is primarily for 269 * use internally; the factory methods which take parameters are more generally 270 * useful. 271 */ 272 public ValueAnimator() { 273 } 274 275 /** 276 * Constructs and returns a ValueAnimator that animates between int values. A single 277 * value implies that that value is the one being animated to. However, this is not typically 278 * useful in a ValueAnimator object because there is no way for the object to determine the 279 * starting value for the animation (unlike ObjectAnimator, which can derive that value 280 * from the target object and property being animated). Therefore, there should typically 281 * be two or more values. 282 * 283 * @param values A set of values that the animation will animate between over time. 284 * @return A ValueAnimator object that is set up to animate between the given values. 285 */ 286 public static ValueAnimator ofInt(int... values) { 287 ValueAnimator anim = new ValueAnimator(); 288 anim.setIntValues(values); 289 return anim; 290 } 291 292 /** 293 * Constructs and returns a ValueAnimator that animates between color values. A single 294 * value implies that that value is the one being animated to. However, this is not typically 295 * useful in a ValueAnimator object because there is no way for the object to determine the 296 * starting value for the animation (unlike ObjectAnimator, which can derive that value 297 * from the target object and property being animated). Therefore, there should typically 298 * be two or more values. 299 * 300 * @param values A set of values that the animation will animate between over time. 301 * @return A ValueAnimator object that is set up to animate between the given values. 302 */ 303 public static ValueAnimator ofArgb(int... values) { 304 ValueAnimator anim = new ValueAnimator(); 305 anim.setIntValues(values); 306 anim.setEvaluator(ArgbEvaluator.getInstance()); 307 return anim; 308 } 309 310 /** 311 * Constructs and returns a ValueAnimator that animates between float values. A single 312 * value implies that that value is the one being animated to. However, this is not typically 313 * useful in a ValueAnimator object because there is no way for the object to determine the 314 * starting value for the animation (unlike ObjectAnimator, which can derive that value 315 * from the target object and property being animated). Therefore, there should typically 316 * be two or more values. 317 * 318 * @param values A set of values that the animation will animate between over time. 319 * @return A ValueAnimator object that is set up to animate between the given values. 320 */ 321 public static ValueAnimator ofFloat(float... values) { 322 ValueAnimator anim = new ValueAnimator(); 323 anim.setFloatValues(values); 324 return anim; 325 } 326 327 /** 328 * Constructs and returns a ValueAnimator that animates between the values 329 * specified in the PropertyValuesHolder objects. 330 * 331 * @param values A set of PropertyValuesHolder objects whose values will be animated 332 * between over time. 333 * @return A ValueAnimator object that is set up to animate between the given values. 334 */ 335 public static ValueAnimator ofPropertyValuesHolder(PropertyValuesHolder... values) { 336 ValueAnimator anim = new ValueAnimator(); 337 anim.setValues(values); 338 return anim; 339 } 340 /** 341 * Constructs and returns a ValueAnimator that animates between Object values. A single 342 * value implies that that value is the one being animated to. However, this is not typically 343 * useful in a ValueAnimator object because there is no way for the object to determine the 344 * starting value for the animation (unlike ObjectAnimator, which can derive that value 345 * from the target object and property being animated). Therefore, there should typically 346 * be two or more values. 347 * 348 * <p>Since ValueAnimator does not know how to animate between arbitrary Objects, this 349 * factory method also takes a TypeEvaluator object that the ValueAnimator will use 350 * to perform that interpolation. 351 * 352 * @param evaluator A TypeEvaluator that will be called on each animation frame to 353 * provide the ncessry interpolation between the Object values to derive the animated 354 * value. 355 * @param values A set of values that the animation will animate between over time. 356 * @return A ValueAnimator object that is set up to animate between the given values. 357 */ 358 public static ValueAnimator ofObject(TypeEvaluator evaluator, Object... values) { 359 ValueAnimator anim = new ValueAnimator(); 360 anim.setObjectValues(values); 361 anim.setEvaluator(evaluator); 362 return anim; 363 } 364 365 /** 366 * Sets int values that will be animated between. A single 367 * value implies that that value is the one being animated to. However, this is not typically 368 * useful in a ValueAnimator object because there is no way for the object to determine the 369 * starting value for the animation (unlike ObjectAnimator, which can derive that value 370 * from the target object and property being animated). Therefore, there should typically 371 * be two or more values. 372 * 373 * <p>If there are already multiple sets of values defined for this ValueAnimator via more 374 * than one PropertyValuesHolder object, this method will set the values for the first 375 * of those objects.</p> 376 * 377 * @param values A set of values that the animation will animate between over time. 378 */ 379 public void setIntValues(int... values) { 380 if (values == null || values.length == 0) { 381 return; 382 } 383 if (mValues == null || mValues.length == 0) { 384 setValues(PropertyValuesHolder.ofInt("", values)); 385 } else { 386 PropertyValuesHolder valuesHolder = mValues[0]; 387 valuesHolder.setIntValues(values); 388 } 389 // New property/values/target should cause re-initialization prior to starting 390 mInitialized = false; 391 } 392 393 /** 394 * Sets float values that will be animated between. A single 395 * value implies that that value is the one being animated to. However, this is not typically 396 * useful in a ValueAnimator object because there is no way for the object to determine the 397 * starting value for the animation (unlike ObjectAnimator, which can derive that value 398 * from the target object and property being animated). Therefore, there should typically 399 * be two or more values. 400 * 401 * <p>If there are already multiple sets of values defined for this ValueAnimator via more 402 * than one PropertyValuesHolder object, this method will set the values for the first 403 * of those objects.</p> 404 * 405 * @param values A set of values that the animation will animate between over time. 406 */ 407 public void setFloatValues(float... values) { 408 if (values == null || values.length == 0) { 409 return; 410 } 411 if (mValues == null || mValues.length == 0) { 412 setValues(PropertyValuesHolder.ofFloat("", values)); 413 } else { 414 PropertyValuesHolder valuesHolder = mValues[0]; 415 valuesHolder.setFloatValues(values); 416 } 417 // New property/values/target should cause re-initialization prior to starting 418 mInitialized = false; 419 } 420 421 /** 422 * Sets the values to animate between for this animation. A single 423 * value implies that that value is the one being animated to. However, this is not typically 424 * useful in a ValueAnimator object because there is no way for the object to determine the 425 * starting value for the animation (unlike ObjectAnimator, which can derive that value 426 * from the target object and property being animated). Therefore, there should typically 427 * be two or more values. 428 * 429 * <p>If there are already multiple sets of values defined for this ValueAnimator via more 430 * than one PropertyValuesHolder object, this method will set the values for the first 431 * of those objects.</p> 432 * 433 * <p>There should be a TypeEvaluator set on the ValueAnimator that knows how to interpolate 434 * between these value objects. ValueAnimator only knows how to interpolate between the 435 * primitive types specified in the other setValues() methods.</p> 436 * 437 * @param values The set of values to animate between. 438 */ 439 public void setObjectValues(Object... values) { 440 if (values == null || values.length == 0) { 441 return; 442 } 443 if (mValues == null || mValues.length == 0) { 444 setValues(PropertyValuesHolder.ofObject("", null, values)); 445 } else { 446 PropertyValuesHolder valuesHolder = mValues[0]; 447 valuesHolder.setObjectValues(values); 448 } 449 // New property/values/target should cause re-initialization prior to starting 450 mInitialized = false; 451 } 452 453 /** 454 * Sets the values, per property, being animated between. This function is called internally 455 * by the constructors of ValueAnimator that take a list of values. But a ValueAnimator can 456 * be constructed without values and this method can be called to set the values manually 457 * instead. 458 * 459 * @param values The set of values, per property, being animated between. 460 */ 461 public void setValues(PropertyValuesHolder... values) { 462 int numValues = values.length; 463 mValues = values; 464 mValuesMap = new HashMap<String, PropertyValuesHolder>(numValues); 465 for (int i = 0; i < numValues; ++i) { 466 PropertyValuesHolder valuesHolder = values[i]; 467 mValuesMap.put(valuesHolder.getPropertyName(), valuesHolder); 468 } 469 // New property/values/target should cause re-initialization prior to starting 470 mInitialized = false; 471 } 472 473 /** 474 * Returns the values that this ValueAnimator animates between. These values are stored in 475 * PropertyValuesHolder objects, even if the ValueAnimator was created with a simple list 476 * of value objects instead. 477 * 478 * @return PropertyValuesHolder[] An array of PropertyValuesHolder objects which hold the 479 * values, per property, that define the animation. 480 */ 481 public PropertyValuesHolder[] getValues() { 482 return mValues; 483 } 484 485 /** 486 * This function is called immediately before processing the first animation 487 * frame of an animation. If there is a nonzero <code>startDelay</code>, the 488 * function is called after that delay ends. 489 * It takes care of the final initialization steps for the 490 * animation. 491 * 492 * <p>Overrides of this method should call the superclass method to ensure 493 * that internal mechanisms for the animation are set up correctly.</p> 494 */ 495 @CallSuper 496 void initAnimation() { 497 if (!mInitialized) { 498 int numValues = mValues.length; 499 for (int i = 0; i < numValues; ++i) { 500 mValues[i].init(); 501 } 502 mInitialized = true; 503 } 504 } 505 506 /** 507 * Sets the length of the animation. The default duration is 300 milliseconds. 508 * 509 * @param duration The length of the animation, in milliseconds. This value cannot 510 * be negative. 511 * @return ValueAnimator The object called with setDuration(). This return 512 * value makes it easier to compose statements together that construct and then set the 513 * duration, as in <code>ValueAnimator.ofInt(0, 10).setDuration(500).start()</code>. 514 */ 515 @Override 516 public ValueAnimator setDuration(long duration) { 517 if (duration < 0) { 518 throw new IllegalArgumentException("Animators cannot have negative duration: " + 519 duration); 520 } 521 mDuration = duration; 522 return this; 523 } 524 525 private long getScaledDuration() { 526 return (long)(mDuration * sDurationScale); 527 } 528 529 /** 530 * Gets the length of the animation. The default duration is 300 milliseconds. 531 * 532 * @return The length of the animation, in milliseconds. 533 */ 534 @Override 535 public long getDuration() { 536 return mDuration; 537 } 538 539 @Override 540 public long getTotalDuration() { 541 if (mRepeatCount == INFINITE) { 542 return DURATION_INFINITE; 543 } else { 544 return mStartDelay + (mDuration * (mRepeatCount + 1)); 545 } 546 } 547 548 /** 549 * Sets the position of the animation to the specified point in time. This time should 550 * be between 0 and the total duration of the animation, including any repetition. If 551 * the animation has not yet been started, then it will not advance forward after it is 552 * set to this time; it will simply set the time to this value and perform any appropriate 553 * actions based on that time. If the animation is already running, then setCurrentPlayTime() 554 * will set the current playing time to this value and continue playing from that point. 555 * 556 * @param playTime The time, in milliseconds, to which the animation is advanced or rewound. 557 */ 558 public void setCurrentPlayTime(long playTime) { 559 float fraction = mDuration > 0 ? (float) playTime / mDuration : 1; 560 setCurrentFraction(fraction); 561 } 562 563 /** 564 * Sets the position of the animation to the specified fraction. This fraction should 565 * be between 0 and the total fraction of the animation, including any repetition. That is, 566 * a fraction of 0 will position the animation at the beginning, a value of 1 at the end, 567 * and a value of 2 at the end of a reversing animator that repeats once. If 568 * the animation has not yet been started, then it will not advance forward after it is 569 * set to this fraction; it will simply set the fraction to this value and perform any 570 * appropriate actions based on that fraction. If the animation is already running, then 571 * setCurrentFraction() will set the current fraction to this value and continue 572 * playing from that point. {@link Animator.AnimatorListener} events are not called 573 * due to changing the fraction; those events are only processed while the animation 574 * is running. 575 * 576 * @param fraction The fraction to which the animation is advanced or rewound. Values 577 * outside the range of 0 to the maximum fraction for the animator will be clamped to 578 * the correct range. 579 */ 580 public void setCurrentFraction(float fraction) { 581 initAnimation(); 582 fraction = clampFraction(fraction); 583 long seekTime = (long) (getScaledDuration() * fraction); 584 long currentTime = AnimationUtils.currentAnimationTimeMillis(); 585 mStartTime = currentTime - seekTime; 586 mStartTimeCommitted = true; // do not allow start time to be compensated for jank 587 if (!mRunning) { 588 mSeekFraction = fraction; 589 } 590 mOverallFraction = fraction; 591 final float currentIterationFraction = getCurrentIterationFraction(fraction); 592 animateValue(currentIterationFraction); 593 } 594 595 /** 596 * Calculates current iteration based on the overall fraction. The overall fraction will be 597 * in the range of [0, mRepeatCount + 1]. Both current iteration and fraction in the current 598 * iteration can be derived from it. 599 */ 600 private int getCurrentIteration(float fraction) { 601 fraction = clampFraction(fraction); 602 // If the overall fraction is a positive integer, we consider the current iteration to be 603 // complete. In other words, the fraction for the current iteration would be 1, and the 604 // current iteration would be overall fraction - 1. 605 double iteration = Math.floor(fraction); 606 if (fraction == iteration && fraction > 0) { 607 iteration--; 608 } 609 return (int) iteration; 610 } 611 612 /** 613 * Calculates the fraction of the current iteration, taking into account whether the animation 614 * should be played backwards. E.g. When the animation is played backwards in an iteration, 615 * the fraction for that iteration will go from 1f to 0f. 616 */ 617 private float getCurrentIterationFraction(float fraction) { 618 fraction = clampFraction(fraction); 619 int iteration = getCurrentIteration(fraction); 620 float currentFraction = fraction - iteration; 621 return shouldPlayBackward(iteration) ? 1f - currentFraction : currentFraction; 622 } 623 624 /** 625 * Clamps fraction into the correct range: [0, mRepeatCount + 1]. If repeat count is infinite, 626 * no upper bound will be set for the fraction. 627 * 628 * @param fraction fraction to be clamped 629 * @return fraction clamped into the range of [0, mRepeatCount + 1] 630 */ 631 private float clampFraction(float fraction) { 632 if (fraction < 0) { 633 fraction = 0; 634 } else if (mRepeatCount != INFINITE) { 635 fraction = Math.min(fraction, mRepeatCount + 1); 636 } 637 return fraction; 638 } 639 640 /** 641 * Calculates the direction of animation playing (i.e. forward or backward), based on 1) 642 * whether the entire animation is being reversed, 2) repeat mode applied to the current 643 * iteration. 644 */ 645 private boolean shouldPlayBackward(int iteration) { 646 if (iteration > 0 && mRepeatMode == REVERSE && 647 (iteration < (mRepeatCount + 1) || mRepeatCount == INFINITE)) { 648 // if we were seeked to some other iteration in a reversing animator, 649 // figure out the correct direction to start playing based on the iteration 650 if (mReversing) { 651 return (iteration % 2) == 0; 652 } else { 653 return (iteration % 2) != 0; 654 } 655 } else { 656 return mReversing; 657 } 658 } 659 660 /** 661 * Gets the current position of the animation in time, which is equal to the current 662 * time minus the time that the animation started. An animation that is not yet started will 663 * return a value of zero, unless the animation has has its play time set via 664 * {@link #setCurrentPlayTime(long)} or {@link #setCurrentFraction(float)}, in which case 665 * it will return the time that was set. 666 * 667 * @return The current position in time of the animation. 668 */ 669 public long getCurrentPlayTime() { 670 if (!mInitialized || (!mStarted && mSeekFraction < 0)) { 671 return 0; 672 } 673 if (mSeekFraction >= 0) { 674 return (long) (mDuration * mSeekFraction); 675 } 676 float durationScale = sDurationScale == 0 ? 1 : sDurationScale; 677 return (long) ((AnimationUtils.currentAnimationTimeMillis() - mStartTime) / durationScale); 678 } 679 680 /** 681 * The amount of time, in milliseconds, to delay starting the animation after 682 * {@link #start()} is called. 683 * 684 * @return the number of milliseconds to delay running the animation 685 */ 686 @Override 687 public long getStartDelay() { 688 return mStartDelay; 689 } 690 691 /** 692 * The amount of time, in milliseconds, to delay starting the animation after 693 * {@link #start()} is called. 694 695 * @param startDelay The amount of the delay, in milliseconds 696 */ 697 @Override 698 public void setStartDelay(long startDelay) { 699 mStartDelay = startDelay; 700 } 701 702 /** 703 * The amount of time, in milliseconds, between each frame of the animation. This is a 704 * requested time that the animation will attempt to honor, but the actual delay between 705 * frames may be different, depending on system load and capabilities. This is a static 706 * function because the same delay will be applied to all animations, since they are all 707 * run off of a single timing loop. 708 * 709 * The frame delay may be ignored when the animation system uses an external timing 710 * source, such as the display refresh rate (vsync), to govern animations. 711 * 712 * Note that this method should be called from the same thread that {@link #start()} is 713 * called in order to check the frame delay for that animation. A runtime exception will be 714 * thrown if the calling thread does not have a Looper. 715 * 716 * @return the requested time between frames, in milliseconds 717 */ 718 public static long getFrameDelay() { 719 return AnimationHandler.getInstance().getFrameDelay(); 720 } 721 722 /** 723 * The amount of time, in milliseconds, between each frame of the animation. This is a 724 * requested time that the animation will attempt to honor, but the actual delay between 725 * frames may be different, depending on system load and capabilities. This is a static 726 * function because the same delay will be applied to all animations, since they are all 727 * run off of a single timing loop. 728 * 729 * The frame delay may be ignored when the animation system uses an external timing 730 * source, such as the display refresh rate (vsync), to govern animations. 731 * 732 * Note that this method should be called from the same thread that {@link #start()} is 733 * called in order to have the new frame delay take effect on that animation. A runtime 734 * exception will be thrown if the calling thread does not have a Looper. 735 * 736 * @param frameDelay the requested time between frames, in milliseconds 737 */ 738 public static void setFrameDelay(long frameDelay) { 739 AnimationHandler.getInstance().setFrameDelay(frameDelay); 740 } 741 742 /** 743 * The most recent value calculated by this <code>ValueAnimator</code> when there is just one 744 * property being animated. This value is only sensible while the animation is running. The main 745 * purpose for this read-only property is to retrieve the value from the <code>ValueAnimator</code> 746 * during a call to {@link AnimatorUpdateListener#onAnimationUpdate(ValueAnimator)}, which 747 * is called during each animation frame, immediately after the value is calculated. 748 * 749 * @return animatedValue The value most recently calculated by this <code>ValueAnimator</code> for 750 * the single property being animated. If there are several properties being animated 751 * (specified by several PropertyValuesHolder objects in the constructor), this function 752 * returns the animated value for the first of those objects. 753 */ 754 public Object getAnimatedValue() { 755 if (mValues != null && mValues.length > 0) { 756 return mValues[0].getAnimatedValue(); 757 } 758 // Shouldn't get here; should always have values unless ValueAnimator was set up wrong 759 return null; 760 } 761 762 /** 763 * The most recent value calculated by this <code>ValueAnimator</code> for <code>propertyName</code>. 764 * The main purpose for this read-only property is to retrieve the value from the 765 * <code>ValueAnimator</code> during a call to 766 * {@link AnimatorUpdateListener#onAnimationUpdate(ValueAnimator)}, which 767 * is called during each animation frame, immediately after the value is calculated. 768 * 769 * @return animatedValue The value most recently calculated for the named property 770 * by this <code>ValueAnimator</code>. 771 */ 772 public Object getAnimatedValue(String propertyName) { 773 PropertyValuesHolder valuesHolder = mValuesMap.get(propertyName); 774 if (valuesHolder != null) { 775 return valuesHolder.getAnimatedValue(); 776 } else { 777 // At least avoid crashing if called with bogus propertyName 778 return null; 779 } 780 } 781 782 /** 783 * Sets how many times the animation should be repeated. If the repeat 784 * count is 0, the animation is never repeated. If the repeat count is 785 * greater than 0 or {@link #INFINITE}, the repeat mode will be taken 786 * into account. The repeat count is 0 by default. 787 * 788 * @param value the number of times the animation should be repeated 789 */ 790 public void setRepeatCount(int value) { 791 mRepeatCount = value; 792 } 793 /** 794 * Defines how many times the animation should repeat. The default value 795 * is 0. 796 * 797 * @return the number of times the animation should repeat, or {@link #INFINITE} 798 */ 799 public int getRepeatCount() { 800 return mRepeatCount; 801 } 802 803 /** 804 * Defines what this animation should do when it reaches the end. This 805 * setting is applied only when the repeat count is either greater than 806 * 0 or {@link #INFINITE}. Defaults to {@link #RESTART}. 807 * 808 * @param value {@link #RESTART} or {@link #REVERSE} 809 */ 810 public void setRepeatMode(int value) { 811 mRepeatMode = value; 812 } 813 814 /** 815 * Defines what this animation should do when it reaches the end. 816 * 817 * @return either one of {@link #REVERSE} or {@link #RESTART} 818 */ 819 public int getRepeatMode() { 820 return mRepeatMode; 821 } 822 823 /** 824 * Adds a listener to the set of listeners that are sent update events through the life of 825 * an animation. This method is called on all listeners for every frame of the animation, 826 * after the values for the animation have been calculated. 827 * 828 * @param listener the listener to be added to the current set of listeners for this animation. 829 */ 830 public void addUpdateListener(AnimatorUpdateListener listener) { 831 if (mUpdateListeners == null) { 832 mUpdateListeners = new ArrayList<AnimatorUpdateListener>(); 833 } 834 mUpdateListeners.add(listener); 835 } 836 837 /** 838 * Removes all listeners from the set listening to frame updates for this animation. 839 */ 840 public void removeAllUpdateListeners() { 841 if (mUpdateListeners == null) { 842 return; 843 } 844 mUpdateListeners.clear(); 845 mUpdateListeners = null; 846 } 847 848 /** 849 * Removes a listener from the set listening to frame updates for this animation. 850 * 851 * @param listener the listener to be removed from the current set of update listeners 852 * for this animation. 853 */ 854 public void removeUpdateListener(AnimatorUpdateListener listener) { 855 if (mUpdateListeners == null) { 856 return; 857 } 858 mUpdateListeners.remove(listener); 859 if (mUpdateListeners.size() == 0) { 860 mUpdateListeners = null; 861 } 862 } 863 864 865 /** 866 * The time interpolator used in calculating the elapsed fraction of this animation. The 867 * interpolator determines whether the animation runs with linear or non-linear motion, 868 * such as acceleration and deceleration. The default value is 869 * {@link android.view.animation.AccelerateDecelerateInterpolator} 870 * 871 * @param value the interpolator to be used by this animation. A value of <code>null</code> 872 * will result in linear interpolation. 873 */ 874 @Override 875 public void setInterpolator(TimeInterpolator value) { 876 if (value != null) { 877 mInterpolator = value; 878 } else { 879 mInterpolator = new LinearInterpolator(); 880 } 881 } 882 883 /** 884 * Returns the timing interpolator that this ValueAnimator uses. 885 * 886 * @return The timing interpolator for this ValueAnimator. 887 */ 888 @Override 889 public TimeInterpolator getInterpolator() { 890 return mInterpolator; 891 } 892 893 /** 894 * The type evaluator to be used when calculating the animated values of this animation. 895 * The system will automatically assign a float or int evaluator based on the type 896 * of <code>startValue</code> and <code>endValue</code> in the constructor. But if these values 897 * are not one of these primitive types, or if different evaluation is desired (such as is 898 * necessary with int values that represent colors), a custom evaluator needs to be assigned. 899 * For example, when running an animation on color values, the {@link ArgbEvaluator} 900 * should be used to get correct RGB color interpolation. 901 * 902 * <p>If this ValueAnimator has only one set of values being animated between, this evaluator 903 * will be used for that set. If there are several sets of values being animated, which is 904 * the case if PropertyValuesHolder objects were set on the ValueAnimator, then the evaluator 905 * is assigned just to the first PropertyValuesHolder object.</p> 906 * 907 * @param value the evaluator to be used this animation 908 */ 909 public void setEvaluator(TypeEvaluator value) { 910 if (value != null && mValues != null && mValues.length > 0) { 911 mValues[0].setEvaluator(value); 912 } 913 } 914 915 private void notifyStartListeners() { 916 if (mListeners != null && !mStartListenersCalled) { 917 ArrayList<AnimatorListener> tmpListeners = 918 (ArrayList<AnimatorListener>) mListeners.clone(); 919 int numListeners = tmpListeners.size(); 920 for (int i = 0; i < numListeners; ++i) { 921 tmpListeners.get(i).onAnimationStart(this); 922 } 923 } 924 mStartListenersCalled = true; 925 } 926 927 /** 928 * Start the animation playing. This version of start() takes a boolean flag that indicates 929 * whether the animation should play in reverse. The flag is usually false, but may be set 930 * to true if called from the reverse() method. 931 * 932 * <p>The animation started by calling this method will be run on the thread that called 933 * this method. This thread should have a Looper on it (a runtime exception will be thrown if 934 * this is not the case). Also, if the animation will animate 935 * properties of objects in the view hierarchy, then the calling thread should be the UI 936 * thread for that view hierarchy.</p> 937 * 938 * @param playBackwards Whether the ValueAnimator should start playing in reverse. 939 */ 940 private void start(boolean playBackwards) { 941 if (Looper.myLooper() == null) { 942 throw new AndroidRuntimeException("Animators may only be run on Looper threads"); 943 } 944 mReversing = playBackwards; 945 // Special case: reversing from seek-to-0 should act as if not seeked at all. 946 if (playBackwards && mSeekFraction != -1 && mSeekFraction != 0) { 947 if (mRepeatCount == INFINITE) { 948 // Calculate the fraction of the current iteration. 949 float fraction = (float) (mSeekFraction - Math.floor(mSeekFraction)); 950 mSeekFraction = 1 - fraction; 951 } else { 952 mSeekFraction = 1 + mRepeatCount - mSeekFraction; 953 } 954 } 955 mStarted = true; 956 mPaused = false; 957 mRunning = false; 958 AnimationHandler animationHandler = AnimationHandler.getInstance(); 959 animationHandler.addAnimationFrameCallback(this, (long) (mStartDelay * sDurationScale)); 960 961 if (mStartDelay == 0) { 962 // If there's no start delay, init the animation and notify start listeners right away 963 // to be consistent with the previous behavior. Otherwise, postpone this until the first 964 // frame after the start delay. 965 startAnimation(); 966 setCurrentFraction(mSeekFraction == -1 ? 0 : mSeekFraction); 967 } 968 } 969 970 @Override 971 public void start() { 972 start(false); 973 } 974 975 @Override 976 public void cancel() { 977 if (Looper.myLooper() == null) { 978 throw new AndroidRuntimeException("Animators may only be run on Looper threads"); 979 } 980 981 // If end has already been requested, through a previous end() or cancel() call, no-op 982 // until animation starts again. 983 if (mAnimationEndRequested) { 984 return; 985 } 986 987 // Only cancel if the animation is actually running or has been started and is about 988 // to run 989 // Only notify listeners if the animator has actually started 990 if ((mStarted || mRunning) && mListeners != null) { 991 if (!mRunning) { 992 // If it's not yet running, then start listeners weren't called. Call them now. 993 notifyStartListeners(); 994 } 995 ArrayList<AnimatorListener> tmpListeners = 996 (ArrayList<AnimatorListener>) mListeners.clone(); 997 for (AnimatorListener listener : tmpListeners) { 998 listener.onAnimationCancel(this); 999 } 1000 } 1001 endAnimation(); 1002 1003 } 1004 1005 @Override 1006 public void end() { 1007 if (Looper.myLooper() == null) { 1008 throw new AndroidRuntimeException("Animators may only be run on Looper threads"); 1009 } 1010 if (!mRunning) { 1011 // Special case if the animation has not yet started; get it ready for ending 1012 startAnimation(); 1013 mStarted = true; 1014 } else if (!mInitialized) { 1015 initAnimation(); 1016 } 1017 animateValue(shouldPlayBackward(mRepeatCount) ? 0f : 1f); 1018 endAnimation(); 1019 } 1020 1021 @Override 1022 public void resume() { 1023 if (mPaused) { 1024 mResumed = true; 1025 } 1026 super.resume(); 1027 } 1028 1029 @Override 1030 public void pause() { 1031 boolean previouslyPaused = mPaused; 1032 super.pause(); 1033 if (!previouslyPaused && mPaused) { 1034 mPauseTime = -1; 1035 mResumed = false; 1036 } 1037 } 1038 1039 @Override 1040 public boolean isRunning() { 1041 return mRunning; 1042 } 1043 1044 @Override 1045 public boolean isStarted() { 1046 return mStarted; 1047 } 1048 1049 /** 1050 * Plays the ValueAnimator in reverse. If the animation is already running, 1051 * it will stop itself and play backwards from the point reached when reverse was called. 1052 * If the animation is not currently running, then it will start from the end and 1053 * play backwards. This behavior is only set for the current animation; future playing 1054 * of the animation will use the default behavior of playing forward. 1055 */ 1056 @Override 1057 public void reverse() { 1058 if (mRunning) { 1059 long currentTime = AnimationUtils.currentAnimationTimeMillis(); 1060 long currentPlayTime = currentTime - mStartTime; 1061 long timeLeft = getScaledDuration() - currentPlayTime; 1062 mStartTime = currentTime - timeLeft; 1063 mStartTimeCommitted = true; // do not allow start time to be compensated for jank 1064 mReversing = !mReversing; 1065 } else if (mStarted) { 1066 end(); 1067 } else { 1068 start(true); 1069 } 1070 } 1071 1072 /** 1073 * @hide 1074 */ 1075 @Override 1076 public boolean canReverse() { 1077 return true; 1078 } 1079 1080 /** 1081 * Called internally to end an animation by removing it from the animations list. Must be 1082 * called on the UI thread. 1083 */ 1084 private void endAnimation() { 1085 if (mAnimationEndRequested) { 1086 return; 1087 } 1088 AnimationHandler handler = AnimationHandler.getInstance(); 1089 handler.removeCallback(this); 1090 1091 mAnimationEndRequested = true; 1092 mPaused = false; 1093 if ((mStarted || mRunning) && mListeners != null) { 1094 if (!mRunning) { 1095 // If it's not yet running, then start listeners weren't called. Call them now. 1096 notifyStartListeners(); 1097 } 1098 ArrayList<AnimatorListener> tmpListeners = 1099 (ArrayList<AnimatorListener>) mListeners.clone(); 1100 int numListeners = tmpListeners.size(); 1101 for (int i = 0; i < numListeners; ++i) { 1102 tmpListeners.get(i).onAnimationEnd(this); 1103 } 1104 } 1105 mRunning = false; 1106 mStarted = false; 1107 mStartListenersCalled = false; 1108 mReversing = false; 1109 mLastFrameTime = 0; 1110 if (Trace.isTagEnabled(Trace.TRACE_TAG_VIEW)) { 1111 Trace.asyncTraceEnd(Trace.TRACE_TAG_VIEW, getNameForTrace(), 1112 System.identityHashCode(this)); 1113 } 1114 } 1115 1116 /** 1117 * Called internally to start an animation by adding it to the active animations list. Must be 1118 * called on the UI thread. 1119 */ 1120 private void startAnimation() { 1121 if (Trace.isTagEnabled(Trace.TRACE_TAG_VIEW)) { 1122 Trace.asyncTraceBegin(Trace.TRACE_TAG_VIEW, getNameForTrace(), 1123 System.identityHashCode(this)); 1124 } 1125 1126 mAnimationEndRequested = false; 1127 initAnimation(); 1128 mRunning = true; 1129 if (mSeekFraction >= 0) { 1130 mOverallFraction = mSeekFraction; 1131 } else { 1132 mOverallFraction = 0f; 1133 } 1134 if (mListeners != null) { 1135 notifyStartListeners(); 1136 } 1137 } 1138 1139 /** 1140 * Returns the name of this animator for debugging purposes. 1141 */ 1142 String getNameForTrace() { 1143 return "animator"; 1144 } 1145 1146 /** 1147 * Applies an adjustment to the animation to compensate for jank between when 1148 * the animation first ran and when the frame was drawn. 1149 * @hide 1150 */ 1151 public void commitAnimationFrame(long frameTime) { 1152 if (!mStartTimeCommitted) { 1153 mStartTimeCommitted = true; 1154 long adjustment = frameTime - mLastFrameTime; 1155 if (adjustment > 0) { 1156 mStartTime += adjustment; 1157 if (DEBUG) { 1158 Log.d(TAG, "Adjusted start time by " + adjustment + " ms: " + toString()); 1159 } 1160 } 1161 } 1162 } 1163 1164 /** 1165 * This internal function processes a single animation frame for a given animation. The 1166 * currentTime parameter is the timing pulse sent by the handler, used to calculate the 1167 * elapsed duration, and therefore 1168 * the elapsed fraction, of the animation. The return value indicates whether the animation 1169 * should be ended (which happens when the elapsed time of the animation exceeds the 1170 * animation's duration, including the repeatCount). 1171 * 1172 * @param currentTime The current time, as tracked by the static timing handler 1173 * @return true if the animation's duration, including any repetitions due to 1174 * <code>repeatCount</code> has been exceeded and the animation should be ended. 1175 */ 1176 boolean animateBasedOnTime(long currentTime) { 1177 boolean done = false; 1178 if (mRunning) { 1179 final float fraction = getScaledDuration() > 0 ? 1180 (float)(currentTime - mStartTime) / getScaledDuration() : 1f; 1181 final float lastFraction = mOverallFraction; 1182 final boolean newIteration = (int) fraction > (int) lastFraction; 1183 final boolean lastIterationFinished = (fraction >= mRepeatCount + 1) && 1184 (mRepeatCount != INFINITE); 1185 if (newIteration && !lastIterationFinished) { 1186 // Time to repeat 1187 if (mListeners != null) { 1188 int numListeners = mListeners.size(); 1189 for (int i = 0; i < numListeners; ++i) { 1190 mListeners.get(i).onAnimationRepeat(this); 1191 } 1192 } 1193 } else if (lastIterationFinished) { 1194 done = true; 1195 } 1196 mOverallFraction = clampFraction(fraction); 1197 float currentIterationFraction = getCurrentIterationFraction(mOverallFraction); 1198 animateValue(currentIterationFraction); 1199 } 1200 return done; 1201 } 1202 1203 /** 1204 * Processes a frame of the animation, adjusting the start time if needed. 1205 * 1206 * @param frameTime The frame time. 1207 * @return true if the animation has ended. 1208 * @hide 1209 */ 1210 public final void doAnimationFrame(long frameTime) { 1211 AnimationHandler handler = AnimationHandler.getInstance(); 1212 if (mLastFrameTime == 0) { 1213 // First frame 1214 handler.addOneShotCommitCallback(this); 1215 if (mStartDelay > 0) { 1216 startAnimation(); 1217 } 1218 if (mSeekFraction < 0) { 1219 mStartTime = frameTime; 1220 } else { 1221 long seekTime = (long) (getScaledDuration() * mSeekFraction); 1222 mStartTime = frameTime - seekTime; 1223 mSeekFraction = -1; 1224 } 1225 mStartTimeCommitted = false; // allow start time to be compensated for jank 1226 } 1227 mLastFrameTime = frameTime; 1228 if (mPaused) { 1229 if (mPauseTime < 0) { 1230 mPauseTime = frameTime; 1231 } 1232 return; 1233 } else if (mResumed) { 1234 mResumed = false; 1235 if (mPauseTime > 0) { 1236 // Offset by the duration that the animation was paused 1237 mStartTime += (frameTime - mPauseTime); 1238 mStartTimeCommitted = false; // allow start time to be compensated for jank 1239 } 1240 handler.addOneShotCommitCallback(this); 1241 } 1242 // The frame time might be before the start time during the first frame of 1243 // an animation. The "current time" must always be on or after the start 1244 // time to avoid animating frames at negative time intervals. In practice, this 1245 // is very rare and only happens when seeking backwards. 1246 final long currentTime = Math.max(frameTime, mStartTime); 1247 boolean finished = animateBasedOnTime(currentTime); 1248 1249 if (finished) { 1250 endAnimation(); 1251 } 1252 } 1253 1254 /** 1255 * Returns the current animation fraction, which is the elapsed/interpolated fraction used in 1256 * the most recent frame update on the animation. 1257 * 1258 * @return Elapsed/interpolated fraction of the animation. 1259 */ 1260 public float getAnimatedFraction() { 1261 return mCurrentFraction; 1262 } 1263 1264 /** 1265 * This method is called with the elapsed fraction of the animation during every 1266 * animation frame. This function turns the elapsed fraction into an interpolated fraction 1267 * and then into an animated value (from the evaluator. The function is called mostly during 1268 * animation updates, but it is also called when the <code>end()</code> 1269 * function is called, to set the final value on the property. 1270 * 1271 * <p>Overrides of this method must call the superclass to perform the calculation 1272 * of the animated value.</p> 1273 * 1274 * @param fraction The elapsed fraction of the animation. 1275 */ 1276 @CallSuper 1277 void animateValue(float fraction) { 1278 fraction = mInterpolator.getInterpolation(fraction); 1279 mCurrentFraction = fraction; 1280 int numValues = mValues.length; 1281 for (int i = 0; i < numValues; ++i) { 1282 mValues[i].calculateValue(fraction); 1283 } 1284 if (mUpdateListeners != null) { 1285 int numListeners = mUpdateListeners.size(); 1286 for (int i = 0; i < numListeners; ++i) { 1287 mUpdateListeners.get(i).onAnimationUpdate(this); 1288 } 1289 } 1290 } 1291 1292 @Override 1293 public ValueAnimator clone() { 1294 final ValueAnimator anim = (ValueAnimator) super.clone(); 1295 if (mUpdateListeners != null) { 1296 anim.mUpdateListeners = new ArrayList<AnimatorUpdateListener>(mUpdateListeners); 1297 } 1298 anim.mSeekFraction = -1; 1299 anim.mReversing = false; 1300 anim.mInitialized = false; 1301 anim.mStarted = false; 1302 anim.mRunning = false; 1303 anim.mPaused = false; 1304 anim.mResumed = false; 1305 anim.mStartListenersCalled = false; 1306 anim.mStartTime = 0; 1307 anim.mStartTimeCommitted = false; 1308 anim.mAnimationEndRequested = false; 1309 anim.mPauseTime = 0; 1310 anim.mLastFrameTime = 0; 1311 anim.mOverallFraction = 0; 1312 anim.mCurrentFraction = 0; 1313 1314 PropertyValuesHolder[] oldValues = mValues; 1315 if (oldValues != null) { 1316 int numValues = oldValues.length; 1317 anim.mValues = new PropertyValuesHolder[numValues]; 1318 anim.mValuesMap = new HashMap<String, PropertyValuesHolder>(numValues); 1319 for (int i = 0; i < numValues; ++i) { 1320 PropertyValuesHolder newValuesHolder = oldValues[i].clone(); 1321 anim.mValues[i] = newValuesHolder; 1322 anim.mValuesMap.put(newValuesHolder.getPropertyName(), newValuesHolder); 1323 } 1324 } 1325 return anim; 1326 } 1327 1328 /** 1329 * Implementors of this interface can add themselves as update listeners 1330 * to an <code>ValueAnimator</code> instance to receive callbacks on every animation 1331 * frame, after the current frame's values have been calculated for that 1332 * <code>ValueAnimator</code>. 1333 */ 1334 public static interface AnimatorUpdateListener { 1335 /** 1336 * <p>Notifies the occurrence of another frame of the animation.</p> 1337 * 1338 * @param animation The animation which was repeated. 1339 */ 1340 void onAnimationUpdate(ValueAnimator animation); 1341 1342 } 1343 1344 /** 1345 * Return the number of animations currently running. 1346 * 1347 * Used by StrictMode internally to annotate violations. 1348 * May be called on arbitrary threads! 1349 * 1350 * @hide 1351 */ 1352 public static int getCurrentAnimationsCount() { 1353 return AnimationHandler.getAnimationCount(); 1354 } 1355 1356 @Override 1357 public String toString() { 1358 String returnVal = "ValueAnimator@" + Integer.toHexString(hashCode()); 1359 if (mValues != null) { 1360 for (int i = 0; i < mValues.length; ++i) { 1361 returnVal += "\n " + mValues[i].toString(); 1362 } 1363 } 1364 return returnVal; 1365 } 1366 1367 /** 1368 * <p>Whether or not the ValueAnimator is allowed to run asynchronously off of 1369 * the UI thread. This is a hint that informs the ValueAnimator that it is 1370 * OK to run the animation off-thread, however ValueAnimator may decide 1371 * that it must run the animation on the UI thread anyway. For example if there 1372 * is an {@link AnimatorUpdateListener} the animation will run on the UI thread, 1373 * regardless of the value of this hint.</p> 1374 * 1375 * <p>Regardless of whether or not the animation runs asynchronously, all 1376 * listener callbacks will be called on the UI thread.</p> 1377 * 1378 * <p>To be able to use this hint the following must be true:</p> 1379 * <ol> 1380 * <li>{@link #getAnimatedFraction()} is not needed (it will return undefined values).</li> 1381 * <li>The animator is immutable while {@link #isStarted()} is true. Requests 1382 * to change values, duration, delay, etc... may be ignored.</li> 1383 * <li>Lifecycle callback events may be asynchronous. Events such as 1384 * {@link Animator.AnimatorListener#onAnimationEnd(Animator)} or 1385 * {@link Animator.AnimatorListener#onAnimationRepeat(Animator)} may end up delayed 1386 * as they must be posted back to the UI thread, and any actions performed 1387 * by those callbacks (such as starting new animations) will not happen 1388 * in the same frame.</li> 1389 * <li>State change requests ({@link #cancel()}, {@link #end()}, {@link #reverse()}, etc...) 1390 * may be asynchronous. It is guaranteed that all state changes that are 1391 * performed on the UI thread in the same frame will be applied as a single 1392 * atomic update, however that frame may be the current frame, 1393 * the next frame, or some future frame. This will also impact the observed 1394 * state of the Animator. For example, {@link #isStarted()} may still return true 1395 * after a call to {@link #end()}. Using the lifecycle callbacks is preferred over 1396 * queries to {@link #isStarted()}, {@link #isRunning()}, and {@link #isPaused()} 1397 * for this reason.</li> 1398 * </ol> 1399 * @hide 1400 */ 1401 @Override 1402 public void setAllowRunningAsynchronously(boolean mayRunAsync) { 1403 // It is up to subclasses to support this, if they can. 1404 } 1405} 1406