1page.title=Property Animation 2parent.title=Animation 3parent.link=animation.html 4@jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 10 <ol> 11 <li><a href="#how">How Property Animation Works</a></li> 12 13 <li><a href="#value-animator">Animating with ValueAnimator</a></li> 14 15 <li><a href="#object-animator">Animating with ObjectAnimator</a></li> 16 17 <li><a href="#choreography">Choreographing Multiple Animations with 18 AnimatorSet</a></li> 19 20 <li><a href="#listeners">Animation Listeners</a></li> 21 22 <li><a href="#type-evaluator">Using a TypeEvaluator</a></li> 23 24 <li><a href="#interpolators">Using Interpolators</a></li> 25 26 <li><a href="#keyframes">Specifying Keyframes</a></li> 27 28 <li><a href="#layout">Animating Layout Changes to ViewGroups</a></li> 29 30 <li><a href="#views">Animating Views</a> 31 <ol> 32 <li><a href="#view-prop-animator">ViewPropertyAnimator</a></li> 33 </ol> 34 </li> 35 36 <li><a href="#declaring-xml">Declaring Animations in XML</a></li> 37 </ol> 38 39 <h2>Key classes</h2> 40 41 <ol> 42 <li><code><a href= 43 "/reference/android/animation/ValueAnimator.html">ValueAnimator</a></code></li> 44 45 <li><code><a href= 46 "/reference/android/animation/ObjectAnimator.html">ObjectAnimator</a></code></li> 47 48 <li><code><a href= 49 "/reference/android/animation/TypeEvaluator.html">TypeEvaluator</a></code></li> 50 </ol> 51 52 <h2>Related samples</h2> 53 54 <ol> 55 <li><a href= 56 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API 57 Demos</a></li> 58 </ol> 59 </div> 60 </div> 61 <p>The property animation system is a robust framework that allows you 62 to animate almost anything. You can define an animation to change any object property over time, 63 regardless of whether it draws to the screen or not. A property animation changes a property's 64 (a field in an object) value over a specified length of time. To animate something, you specify the 65 object property that you want to animate, such as an object's position on the screen, how long 66 you want to animate it for, and what values you want to animate between. </p> 67 68 <p>The property animation system lets you define the following characteristics of an 69 animation:</p> 70 71 <ul> 72 <li>Duration: You can specify the duration of an animation. The default length is 300 ms.</li> 73 74 <li>Time interpolation: You can specify how the values for the property are calculated as a 75 function of the animation's current elapsed time.</li> 76 77 <li>Repeat count and behavior: You can specify whether or not to have an animation repeat when 78 it reaches the end of a duration and how many times to repeat the animation. You can also 79 specify whether you want the animation to play back in reverse. Setting it to reverse plays 80 the animation forwards then backwards repeatedly, until the number of repeats is reached.</li> 81 82 <li>Animator sets: You can group animations into logical sets that play together or 83 sequentially or after specified delays.</li> 84 85 <li>Frame refresh delay: You can specify how often to refresh frames of your animation. The 86 default is set to refresh every 10 ms, but the speed in which your application can refresh frames is 87 ultimately dependent on how busy the system is overall and how fast the system can service the underlying timer.</li> 88 </ul> 89 90 91 <h2 id="how">How Property Animation Works</h2> 92 93 <p>First, let's go over how an animation works with a simple example. Figure 1 depicts a 94 hypothetical object that is animated with its <code>x</code> property, which represents its 95 horizontal location on a screen. The duration of the animation is set to 40 ms and the distance 96 to travel is 40 pixels. Every 10 ms, which is the default frame refresh rate, the object moves 97 horizontally by 10 pixels. At the end of 40ms, the animation stops, and the object ends at 98 horizontal position 40. This is an example of an animation with linear interpolation, meaning the 99 object moves at a constant speed.</p><img src="{@docRoot}images/animation/animation-linear.png"> 100 101 <p class="img-caption"><strong>Figure 1.</strong> Example of a linear animation</p> 102 103 <p>You can also specify animations to have a non-linear interpolation. Figure 2 illustrates a 104 hypothetical object that accelerates at the beginning of the animation, and decelerates at the 105 end of the animation. The object still moves 40 pixels in 40 ms, but non-linearly. In the 106 beginning, this animation accelerates up to the halfway point then decelerates from the 107 halfway point until the end of the animation. As Figure 2 shows, the distance traveled 108 at the beginning and end of the animation is less than in the middle.</p><img src= 109 "{@docRoot}images/animation/animation-nonlinear.png"> 110 111 <p class="img-caption"><strong>Figure 2.</strong> Example of a non-linear animation</p> 112 113 <p>Let's take a detailed look at how the important components of the property animation system 114 would calculate animations like the ones illustrated above. Figure 3 depicts how the main classes 115 work with one another.</p><img src="{@docRoot}images/animation/valueanimator.png"> 116 117 <p class="img-caption"><strong>Figure 3.</strong> How animations are calculated</p> 118 119 <p>The {@link android.animation.ValueAnimator} object keeps track of your animation's timing, 120 such as how long the animation has been running, and the current value of the property that it is 121 animating.</p> 122 123 <p>The {@link android.animation.ValueAnimator} encapsulates a {@link 124 android.animation.TimeInterpolator}, which defines animation interpolation, and a {@link 125 android.animation.TypeEvaluator}, which defines how to calculate values for the property being 126 animated. For example, in Figure 2, the {@link android.animation.TimeInterpolator} used would be 127 {@link android.view.animation.AccelerateDecelerateInterpolator} and the {@link 128 android.animation.TypeEvaluator} would be {@link android.animation.IntEvaluator}.</p> 129 130 <p>To start an animation, create a {@link android.animation.ValueAnimator} and give it the 131 starting and ending values for the property that you want to animate, along with the duration of 132 the animation. When you call {@link android.animation.ValueAnimator#start start()} the animation 133 begins. During the whole animation, the {@link android.animation.ValueAnimator} calculates an <em>elapsed fraction</em> 134 between 0 and 1, based on the duration of the animation and how much time has elapsed. The 135 elapsed fraction represents the percentage of time that the animation has completed, 0 meaning 0% 136 and 1 meaning 100%. For example, in Figure 1, the elapsed fraction at t = 10 ms would be .25 137 because the total duration is t = 40 ms.</p> 138 139 <p>When the {@link android.animation.ValueAnimator} is done calculating an elapsed fraction, it 140 calls the {@link android.animation.TimeInterpolator} that is currently set, to calculate an 141 <em>interpolated fraction</em>. An interpolated fraction maps the elapsed fraction to a new 142 fraction that takes into account the time interpolation that is set. For example, in Figure 2, 143 because the animation slowly accelerates, the interpolated fraction, about .15, is less than the 144 elapsed fraction, .25, at t = 10 ms. In Figure 1, the interpolated fraction is always the same as 145 the elapsed fraction.</p> 146 147 <p>When the interpolated fraction is calculated, {@link android.animation.ValueAnimator} calls 148 the appropriate {@link android.animation.TypeEvaluator}, to calculate the value of the 149 property that you are animating, based on the interpolated fraction, the starting value, and the 150 ending value of the animation. For example, in Figure 2, the interpolated fraction was .15 at t = 151 10 ms, so the value for the property at that time would be .15 X (40 - 0), or 6.</p> 152 153 <!-- <p>When the final value is calculated, the {@link android.animation.ValueAnimator} calls the 154 {@link android.animation.ValueAnimator.AnimatorUpdateListener#onAnimationUpdate 155 onAnimationUpdate()} method. Implement this callback to obtain the property value by 156 calling {@link android.animation.ValueAnimator#getAnimatedValue getAnimatedValue()} and set the 157 value for the property in the object that you are animating. Setting the property doesn't redraw 158 the object on the screen, so you need to call {@link 159 android.view.View#invalidate invalidate()} to refresh the View that the object 160 resides in. If the object is actually a View object, then the system calls {@link 161 android.view.View#invalidate invalidate()} when the property is changed. 162 The system redraws the window and the {@link android.animation.ValueAnimator} 163 repeats the process.</p>--> 164 165 <p>The <code>com.example.android.apis.animation</code> package in the <a href= 166 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API 167 Demos</a> sample project provides many examples on how to use the property 168 animation system.</p> 169 170 <h2 id="property-vs-view">How Property Animation Differs from View Animation</h2> 171 172 <p>The view animation system provides the capability to only animate {@link android.view.View} 173 objects, so if you wanted to animate non-{@link android.view.View} objects, you have to implement 174 your own code to do so. The view animation system is also constrained in the fact that it only 175 exposes a few aspects of a {@link android.view.View} object to animate, such as the scaling and 176 rotation of a View but not the background color, for instance.</p> 177 178 <p>Another disadvantage of the view animation system is that it only modified where the 179 View was drawn, and not the actual View itself. For instance, if you animated a button to move 180 across the screen, the button draws correctly, but the actual location where you can click the 181 button does not change, so you have to implement your own logic to handle this.</p> 182 183 <p>With the property animation system, these constraints are completely removed, and you can animate 184 any property of any object (Views and non-Views) and the object itself is actually modified. 185 The property animation system is also more robust in the way it carries out animation. At 186 a high level, you assign animators to the properties that you want to animate, such as color, 187 position, or size and can define aspects of the animation such as interpolation and 188 synchronization of multiple animators.</p> 189 190 <p>The view animation system, however, takes less time to setup and requires less code to write. 191 If view animation accomplishes everything that you need to do, or if your existing code already 192 works the way you want, there is no need to use the property animation system. It also might 193 make sense to use both animation systems for different situations if the use case arises.</p> 194 195 <h2>API Overview</h2> 196 197 <p>You can find most of the property animation system's APIs in {@link android.animation 198 android.animation}. Because the view animation system already 199 defines many interpolators in {@link android.view.animation android.view.animation}, you can use 200 those interpolators in the property animation system as well. The following tables describe the main 201 components of the property animation system.</p> 202 203 <p>The {@link android.animation.Animator} class provides the basic structure for creating 204 animations. You normally do not use this class directly as it only provides minimal 205 functionality that must be extended to fully support animating values. The following 206 subclasses extend {@link android.animation.Animator}: 207 </p> 208 <p class="table-caption"><strong>Table 1.</strong> Animators</p> 209 <table> 210 <tr> 211 <th>Class</th> 212 213 <th>Description</th> 214 </tr> 215 216 <tr> 217 <td>{@link android.animation.ValueAnimator}</td> 218 219 <td>The main timing engine for property animation that also computes the values for the 220 property to be animated. It has all of the core functionality that calculates animation 221 values and contains the timing details of each animation, information about whether an 222 animation repeats, listeners that receive update events, and the ability to set custom 223 types to evaluate. There are two pieces to animating properties: calculating the animated 224 values and setting those values on the object and property that is being animated. {@link 225 android.animation.ValueAnimator} does not carry out the second piece, so you must listen 226 for updates to values calculated by the {@link android.animation.ValueAnimator} and 227 modify the objects that you want to animate with your own logic. See the section about 228 <a href="#value-animator">Animating with ValueAnimator</a> for more information.</td> 229 </tr> 230 231 <tr> 232 <td>{@link android.animation.ObjectAnimator}</td> 233 234 <td>A subclass of {@link android.animation.ValueAnimator} that allows you to set a target 235 object and object property to animate. This class updates the property accordingly when 236 it computes a new value for the animation. You want to use 237 {@link android.animation.ObjectAnimator} most of the time, 238 because it makes the process of animating values on target objects much easier. However, 239 you sometimes want to use {@link android.animation.ValueAnimator} directly because {@link 240 android.animation.ObjectAnimator} has a few more restrictions, such as requiring specific 241 acessor methods to be present on the target object.</td> 242 </tr> 243 244 <tr> 245 <td>{@link android.animation.AnimatorSet}</td> 246 247 <td>Provides a mechanism to group animations together so that they run in 248 relation to one another. You can set animations to play together, sequentially, or after 249 a specified delay. See the section about <a href="#choreography">Choreographing multiple 250 animations with Animator Sets</a> for more information.</td> 251 </tr> 252 </table> 253 254 255 <p>Evaluators tell the property animation system how to calculate values for a given 256 property. They take the timing data that is provided by an {@link android.animation.Animator} 257 class, the animation's start and end value, and calculate the animated values of the property 258 based on this data. The property animation system provides the following evaluators:</p> 259 <p class="table-caption"><strong>Table 2.</strong> Evaluators</p> 260 <table> 261 <tr> 262 <th>Class/Interface</th> 263 264 <th>Description</th> 265 </tr> 266 267 <tr> 268 <td>{@link android.animation.IntEvaluator}</td> 269 270 <td>The default evaluator to calculate values for <code>int</code> properties.</td> 271 </tr> 272 273 <tr> 274 <td>{@link android.animation.FloatEvaluator}</td> 275 276 <td>The default evaluator to calculate values for <code>float</code> properties.</td> 277 </tr> 278 279 <tr> 280 <td>{@link android.animation.ArgbEvaluator}</td> 281 282 <td>The default evaluator to calculate values for color properties that are represented 283 as hexidecimal values.</td> 284 </tr> 285 286 <tr> 287 <td>{@link android.animation.TypeEvaluator}</td> 288 289 <td>An interface that allows you to create your own evaluator. If you are animating an 290 object property that is <em>not</em> an <code>int</code>, <code>float</code>, or color, 291 you must implement the {@link android.animation.TypeEvaluator} interface to specify how 292 to compute the object property's animated values. You can also specify a custom {@link 293 android.animation.TypeEvaluator} for <code>int</code>, <code>float</code>, and color 294 values as well, if you want to process those types differently than the default behavior. 295 See the section about <a href="#type-evaluator">Using a TypeEvaluator</a> for more 296 information on how to write a custom evaluator.</td> 297 </tr> 298 </table> 299 300 301 302 303 <p>A time interpolator defines how specific values in an animation are calculated as a 304 function of time. For example, you can specify animations to happen linearly across the whole 305 animation, meaning the animation moves evenly the entire time, or you can specify animations 306 to use non-linear time, for example, accelerating at the beginning and decelerating at the 307 end of the animation. Table 3 describes the interpolators that are contained in {@link 308 android.view.animation android.view.animation}. If none of the provided interpolators suits 309 your needs, implement the {@link android.animation.TimeInterpolator} interface and create your own. See <a href= 310 "#interpolators">Using interpolators</a> for more information on how to write a custom 311 interpolator.</p> 312 <p class="table-caption"><strong>Table 3.</strong> Interpolators</p> 313 <table> 314 <tr> 315 <th>Class/Interface</th> 316 317 <th>Description</th> 318 </tr> 319 320 <tr> 321 <td>{@link android.view.animation.AccelerateDecelerateInterpolator}</td> 322 323 <td>An interpolator whose rate of change starts and ends slowly but accelerates 324 through the middle.</td> 325 </tr> 326 327 <tr> 328 <td>{@link android.view.animation.AccelerateInterpolator}</td> 329 330 <td>An interpolator whose rate of change starts out slowly and then 331 accelerates.</td> 332 </tr> 333 334 <tr> 335 <td>{@link android.view.animation.AnticipateInterpolator}</td> 336 337 <td>An interpolator whose change starts backward then flings forward.</td> 338 </tr> 339 340 <tr> 341 <td>{@link android.view.animation.AnticipateOvershootInterpolator}</td> 342 343 <td>An interpolator whose change starts backward, flings forward and overshoots 344 the target value, then finally goes back to the final value.</td> 345 </tr> 346 347 <tr> 348 <td>{@link android.view.animation.BounceInterpolator}</td> 349 350 <td>An interpolator whose change bounces at the end.</td> 351 </tr> 352 353 <tr> 354 <td>{@link android.view.animation.CycleInterpolator}</td> 355 356 <td>An interpolator whose animation repeats for a specified number of cycles.</td> 357 </tr> 358 359 <tr> 360 <td>{@link android.view.animation.DecelerateInterpolator}</td> 361 362 <td>An interpolator whose rate of change starts out quickly and and then 363 decelerates.</td> 364 </tr> 365 366 <tr> 367 <td>{@link android.view.animation.LinearInterpolator}</td> 368 369 <td>An interpolator whose rate of change is constant.</td> 370 </tr> 371 372 <tr> 373 <td>{@link android.view.animation.OvershootInterpolator}</td> 374 375 <td>An interpolator whose change flings forward and overshoots the last value then 376 comes back.</td> 377 </tr> 378 379 <tr> 380 <td>{@link android.animation.TimeInterpolator}</td> 381 382 <td>An interface that allows you to implement your own interpolator.</td> 383 </tr> 384 </table> 385 386 <h2 id="value-animator">Animating with ValueAnimator</h2> 387 388 <p>The {@link android.animation.ValueAnimator} class lets you animate values of some type for the 389 duration of an animation by specifying a set of <code>int</code>, <code>float</code>, or color 390 values to animate through. You obtain a {@link android.animation.ValueAnimator} by calling one of 391 its factory methods: {@link android.animation.ValueAnimator#ofInt ofInt()}, {@link 392 android.animation.ValueAnimator#ofFloat ofFloat()}, or {@link 393 android.animation.ValueAnimator#ofObject ofObject()}. For example:</p> 394 <pre> 395ValueAnimator animation = ValueAnimator.ofFloat(0f, 1f); 396animation.setDuration(1000); 397animation.start(); 398</pre> 399 400 <p>In this code, the {@link android.animation.ValueAnimator} starts calculating the values of the 401 animation, between 0 and 1, for a duration of 1000 ms, when the <code>start()</code> method 402 runs.</p> 403 404 <p>You can also specify a custom type to animate by doing the following:</p> 405 <pre> 406ValueAnimator animation = ValueAnimator.ofObject(new MyTypeEvaluator(), startPropertyValue, endPropertyValue); 407animation.setDuration(1000); 408animation.start(); 409</pre> 410 411 <p>In this code, the {@link android.animation.ValueAnimator} starts calculating the values of the 412 animation, between <code>startPropertyValue</code> and <code>endPropertyValue</code> using the 413 logic supplied by <code>MyTypeEvaluator</code> for a duration of 1000 ms, when the {@link 414 android.animation.ValueAnimator#start start()} method runs.</p> 415 416 <p>The previous code snippets, however, has no real effect on an object, because the {@link 417 android.animation.ValueAnimator} does not operate on objects or properties directly. The most likely thing 418 that you want to do is modify the objects that you want to animate with these calculated values. You do 419 this by defining listeners in the {@link android.animation.ValueAnimator} to appropriately handle important events 420 during the animation's lifespan, such as frame updates. When implementing the listeners, you can 421 obtain the calculated value for that specific frame refresh by calling {@link 422 android.animation.ValueAnimator#getAnimatedValue getAnimatedValue()}. For more information on listeners, 423 see the section about <a href="#listeners">Animation Listeners</a>. 424 425 <h2 id="object-animator">Animating with ObjectAnimator</h2> 426 427 <p>The {@link android.animation.ObjectAnimator} is a subclass of the {@link 428 android.animation.ValueAnimator} (discussed in the previous section) and combines the timing 429 engine and value computation of {@link android.animation.ValueAnimator} with the ability to 430 animate a named property of a target object. This makes animating any object much easier, as you 431 no longer need to implement the {@link android.animation.ValueAnimator.AnimatorUpdateListener}, 432 because the animated property updates automatically.</p> 433 434 <p>Instantiating an {@link android.animation.ObjectAnimator} is similar to a {@link 435 android.animation.ValueAnimator}, but you also specify the object and the name of that object's property (as 436 a String) along with the values to animate between:</p> 437 <pre> 438ObjectAnimator anim = ObjectAnimator.ofFloat(foo, "alpha", 0f, 1f); 439anim.setDuration(1000); 440anim.start(); 441</pre> 442 443 <p>To have the {@link android.animation.ObjectAnimator} update properties correctly, you must do 444 the following:</p> 445 446 <ul> 447 <li>The object property that you are animating must have a setter function (in camel case) in the form of 448 <code>set<propertyName>()</code>. Because the {@link android.animation.ObjectAnimator} 449 automatically updates the property during animation, it must be able to access the property 450 with this setter method. For example, if the property name is <code>foo</code>, you need to 451 have a <code>setFoo()</code> method. If this setter method does not exist, you have three 452 options: 453 454 <ul> 455 <li>Add the setter method to the class if you have the rights to do so.</li> 456 457 <li>Use a wrapper class that you have rights to change and have that wrapper receive the 458 value with a valid setter method and forward it to the original object.</li> 459 460 <li>Use {@link android.animation.ValueAnimator} instead.</li> 461 </ul> 462 </li> 463 464 <li>If you specify only one value for the <code>values...</code> parameter in one of the {@link 465 android.animation.ObjectAnimator} factory methods, it is assumed to be the ending value of the 466 animation. Therefore, the object property that you are animating must have a getter function 467 that is used to obtain the starting value of the animation. The getter function must be in the 468 form of <code>get<propertyName>()</code>. For example, if the property name is 469 <code>foo</code>, you need to have a <code>getFoo()</code> method.</li> 470 471 <li>The getter (if needed) and setter methods of the property that you are animating must 472 operate on the same type as the starting and ending values that you specify to {@link 473 android.animation.ObjectAnimator}. For example, you must have 474 <code>targetObject.setPropName(float)</code> and <code>targetObject.getPropName(float)</code> 475 if you construct the following {@link android.animation.ObjectAnimator}: 476 <pre> 477ObjectAnimator.ofFloat(targetObject, "propName", 1f) 478</pre> 479 </li> 480 481 <li>Depending on what property or object you are animating, you might need to call the {@link 482 android.view.View#invalidate invalidate()} method on a View force the screen to redraw itself with the 483 updated animated values. You do this in the 484 {@link android.animation.ValueAnimator.AnimatorUpdateListener#onAnimationUpdate onAnimationUpdate()} 485 callback. For example, animating the color property of a Drawable object only cause updates to the 486 screen when that object redraws itself. All of the property setters on View, such as 487 {@link android.view.View#setAlpha setAlpha()} and {@link android.view.View#setTranslationX setTranslationX()} 488 invalidate the View properly, so you do not need to invalidate the View when calling these 489 methods with new values. For more information on listeners, see the section about <a href="#listeners">Animation Listeners</a>. 490 </li> 491 </ul> 492 493 <h2 id="choreography">Choreographing Multiple Animations with AnimatorSet</h2> 494 495 <p>In many cases, you want to play an animation that depends on when another animation starts or 496 finishes. The Android system lets you bundle animations together into an {@link 497 android.animation.AnimatorSet}, so that you can specify whether to start animations 498 simultaneously, sequentially, or after a specified delay. You can also nest {@link 499 android.animation.AnimatorSet} objects within each other.</p> 500 501 <p>The following sample code taken from the <a href= 502 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/BouncingBalls.html">Bouncing 503 Balls</a> sample (modified for simplicity) plays the following {@link android.animation.Animator} 504 objects in the following manner:</p> 505 506 <ol> 507 <li>Plays <code>bounceAnim</code>.</li> 508 509 <li>Plays <code>squashAnim1</code>, <code>squashAnim2</code>, <code>stretchAnim1</code>, and 510 <code>stretchAnim2</code> at the same time.</li> 511 512 <li>Plays <code>bounceBackAnim</code>.</li> 513 514 <li>Plays <code>fadeAnim</code>.</li> 515 </ol> 516 <pre> 517AnimatorSet bouncer = new AnimatorSet(); 518bouncer.play(bounceAnim).before(squashAnim1); 519bouncer.play(squashAnim1).with(squashAnim2); 520bouncer.play(squashAnim1).with(stretchAnim1); 521bouncer.play(squashAnim1).with(stretchAnim2); 522bouncer.play(bounceBackAnim).after(stretchAnim2); 523ValueAnimator fadeAnim = ObjectAnimator.ofFloat(newBall, "alpha", 1f, 0f); 524fadeAnim.setDuration(250); 525AnimatorSet animatorSet = new AnimatorSet(); 526animatorSet.play(bouncer).before(fadeAnim); 527animatorSet.start(); 528</pre> 529 530 <p>For a more complete example on how to use animator sets, see the <a href= 531 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/BouncingBalls.html">Bouncing 532 Balls</a> sample in APIDemos.</p> 533 534<h2 id="listeners">Animation Listeners</h2> 535<p> 536You can listen for important events during an animation's duration with the listeners described below. 537</p> 538 539 <ul> 540 <li>{@link android.animation.Animator.AnimatorListener} 541 542 <ul> 543 <li>{@link android.animation.Animator.AnimatorListener#onAnimationStart onAnimationStart()} 544 - Called when the animation starts.</li> 545 546 <li>{@link android.animation.Animator.AnimatorListener#onAnimationEnd onAnimationEnd()} - 547 Called when the animation ends.</li> 548 549 <li>{@link android.animation.Animator.AnimatorListener#onAnimationRepeat 550 onAnimationRepeat()} - Called when the animation repeats itself.</li> 551 552 <li>{@link android.animation.Animator.AnimatorListener#onAnimationCancel 553 onAnimationCancel()} - Called when the animation is canceled. A cancelled animation 554 also calls {@link android.animation.Animator.AnimatorListener#onAnimationEnd onAnimationEnd()}, 555 regardless of how they were ended.</li> 556 </ul> 557 </li> 558 559 <li>{@link android.animation.ValueAnimator.AnimatorUpdateListener} 560 561 <ul> 562 <li> 563 <p>{@link android.animation.ValueAnimator.AnimatorUpdateListener#onAnimationUpdate 564 onAnimationUpdate()} - called on every frame of the animation. Listen to this event to 565 use the calculated values generated by {@link android.animation.ValueAnimator} during an 566 animation. To use the value, query the {@link android.animation.ValueAnimator} object 567 passed into the event to get the current animated value with the {@link 568 android.animation.ValueAnimator#getAnimatedValue getAnimatedValue()} method. Implementing this 569 listener is required if you use {@link android.animation.ValueAnimator}. </p> 570 571 <p> 572 Depending on what property or object you are animating, you might need to call 573 {@link android.view.View#invalidate invalidate()} on a View to force that area of the 574 screen to redraw itself with the new animated values. For example, animating the 575 color property of a Drawable object only cause updates to the screen when that object 576 redraws itself. All of the property setters on View, 577 such as {@link android.view.View#setAlpha setAlpha()} and 578 {@link android.view.View#setTranslationX setTranslationX()} invalidate the View 579 properly, so you do not need to invalidate the View when calling these methods with new values. 580 </p> 581 582 </li> 583 </ul> 584 </li> 585 </ul> 586 587<p>You can extend the {@link android.animation.AnimatorListenerAdapter} class instead of 588implementing the {@link android.animation.Animator.AnimatorListener} interface, if you do not 589want to implement all of the methods of the {@link android.animation.Animator.AnimatorListener} 590interface. The {@link android.animation.AnimatorListenerAdapter} class provides empty 591implementations of the methods that you can choose to override.</p> 592 <p>For example, the <a href= 593 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/BouncingBalls.html">Bouncing 594 Balls</a> sample in the API demos creates an {@link android.animation.AnimatorListenerAdapter} 595 for just the {@link android.animation.Animator.AnimatorListener#onAnimationEnd onAnimationEnd()} 596 callback:</p> 597 <pre> 598ValueAnimatorAnimator fadeAnim = ObjectAnimator.ofFloat(newBall, "alpha", 1f, 0f); 599fadeAnim.setDuration(250); 600fadeAnim.addListener(new AnimatorListenerAdapter() { 601public void onAnimationEnd(Animator animation) { 602 balls.remove(((ObjectAnimator)animation).getTarget()); 603} 604</pre> 605 606 607 <h2 id="layout">Animating Layout Changes to ViewGroups</h2> 608 609 <p>The property animation system provides the capability to animate changes to ViewGroup objects 610 as well as provide an easy way to animate View objects themselves.</p> 611 612 <p>You can animate layout changes within a ViewGroup with the {@link 613 android.animation.LayoutTransition} class. Views inside a ViewGroup can go through an appearing 614 and disappearing animation when you add them to or remove them from a ViewGroup or when you call 615 a View's {@link android.view.View#setVisibility setVisibility()} method with {@link 616 android.view.View#VISIBLE}, android.view.View#INVISIBLE}, or {@link android.view.View#GONE}. The remaining Views in the 617 ViewGroup can also animate into their new positions when you add or remove Views. You can define 618 the following animations in a {@link android.animation.LayoutTransition} object by calling {@link 619 android.animation.LayoutTransition#setAnimator setAnimator()} and passing in an {@link 620 android.animation.Animator} object with one of the following {@link 621 android.animation.LayoutTransition} constants:</p> 622 623 <ul> 624 <li><code>APPEARING</code> - A flag indicating the animation that runs on items that are 625 appearing in the container.</li> 626 627 <li><code>CHANGE_APPEARING</code> - A flag indicating the animation that runs on items that are 628 changing due to a new item appearing in the container.</li> 629 630 <li><code>DISAPPEARING</code> - A flag indicating the animation that runs on items that are 631 disappearing from the container.</li> 632 633 <li><code>CHANGE_DISAPPEARING</code> - A flag indicating the animation that runs on items that 634 are changing due to an item disappearing from the container.</li> 635 </ul> 636 637 <p>You can define your own custom animations for these four types of events to customize the look 638 of your layout transitions or just tell the animation system to use the default animations.</p> 639 640 <p>The <a href= 641 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/LayoutAnimations.html"> 642 LayoutAnimations</a> sample in API Demos shows you how to define animations for layout 643 transitions and then set the animations on the View objects that you want to animate.</p> 644 645 <p>The <a href= 646 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/LayoutAnimationsByDefault.html"> 647 LayoutAnimationsByDefault</a> and its corresponding <a href= 648 "{@docRoot}resources/samples/ApiDemos/res/layout/layout_animations_by_default.html">layout_animations_by_default.xml</a> 649 layout resource file show you how to enable the default layout transitions for ViewGroups in XML. 650 The only thing that you need to do is to set the <code>android:animateLayoutchanges</code> 651 attribute to <code>true</code> for the ViewGroup. For example:</p> 652 <pre> 653<LinearLayout 654 android:orientation="vertical" 655 android:layout_width="wrap_content" 656 android:layout_height="match_parent" 657 android:id="@+id/verticalContainer" 658 android:animateLayoutChanges="true" /> 659</pre> 660 661 <p>Setting this attribute to true automatically animates Views that are added or removed from the 662 ViewGroup as well as the remaining Views in the ViewGroup.</p> 663 664 <h2 id="type-evaluator">Using a TypeEvaluator</h2> 665 666 <p>If you want to animate a type that is unknown to the Android system, you can create your own 667 evaluator by implementing the {@link android.animation.TypeEvaluator} interface. The types that 668 are known by the Android system are <code>int</code>, <code>float</code>, or a color, which are 669 supported by the {@link android.animation.IntEvaluator}, {@link 670 android.animation.FloatEvaluator}, and {@link android.animation.ArgbEvaluator} type 671 evaluators.</p> 672 673 <p>There is only one method to implement in the {@link android.animation.TypeEvaluator} 674 interface, the {@link android.animation.TypeEvaluator#evaluate evaluate()} method. This allows 675 the animator that you are using to return an appropriate value for your animated property at the 676 current point of the animation. The {@link android.animation.FloatEvaluator} class demonstrates 677 how to do this:</p> 678 <pre> 679public class FloatEvaluator implements TypeEvaluator { 680 681 public Object evaluate(float fraction, Object startValue, Object endValue) { 682 float startFloat = ((Number) startValue).floatValue(); 683 return startFloat + fraction * (((Number) endValue).floatValue() - startFloat); 684 } 685} 686</pre> 687 688 <p class="note"><strong>Note:</strong> When {@link android.animation.ValueAnimator} (or {@link 689 android.animation.ObjectAnimator}) runs, it calculates a current elapsed fraction of the 690 animation (a value between 0 and 1) and then calculates an interpolated version of that depending 691 on what interpolator that you are using. The interpolated fraction is what your {@link 692 android.animation.TypeEvaluator} receives through the <code>fraction</code> parameter, so you do 693 not have to take into account the interpolator when calculating animated values.</p> 694 695 <h2 id="interpolators">Using Interpolators</h2> 696 697 <p>An interpolator define how specific values in an animation are calculated as a function of 698 time. For example, you can specify animations to happen linearly across the whole animation, 699 meaning the animation moves evenly the entire time, or you can specify animations to use 700 non-linear time, for example, using acceleration or deceleration at the beginning or end of the 701 animation.</p> 702 703 <p>Interpolators in the animation system receive a fraction from Animators that represent the 704 elapsed time of the animation. Interpolators modify this fraction to coincide with the type of 705 animation that it aims to provide. The Android system provides a set of common interpolators in 706 the {@link android.view.animation android.view.animation package}. If none of these suit your 707 needs, you can implement the {@link android.animation.TimeInterpolator} interface and create your 708 own.</p> 709 710 <p>As an example, how the default interpolator {@link 711 android.view.animation.AccelerateDecelerateInterpolator} and the {@link 712 android.view.animation.LinearInterpolator} calculate interpolated fractions are compared below. 713 The {@link android.view.animation.LinearInterpolator} has no effect on the elapsed fraction. The {@link 714 android.view.animation.AccelerateDecelerateInterpolator} accelerates into the animation and 715 decelerates out of it. The following methods define the logic for these interpolators:</p> 716 717 <p><strong>AccelerateDecelerateInterpolator</strong></p> 718 <pre> 719public float getInterpolation(float input) { 720 return (float)(Math.cos((input + 1) * Math.PI) / 2.0f) + 0.5f; 721} 722</pre> 723 724 <p><strong>LinearInterpolator</strong></p> 725 <pre> 726public float getInterpolation(float input) { 727 return input; 728} 729</pre> 730 731 <p>The following table represents the approximate values that are calculated by these 732 interpolators for an animation that lasts 1000ms:</p> 733 734 <table> 735 <tr> 736 <th>ms elapsed</th> 737 738 <th>Elapsed fraction/Interpolated fraction (Linear)</th> 739 740 <th>Interpolated fraction (Accelerate/Decelerate)</th> 741 </tr> 742 743 <tr> 744 <td>0</td> 745 746 <td>0</td> 747 748 <td>0</td> 749 </tr> 750 751 <tr> 752 <td>200</td> 753 754 <td>.2</td> 755 756 <td>.1</td> 757 </tr> 758 759 <tr> 760 <td>400</td> 761 762 <td>.4</td> 763 764 <td>.345</td> 765 </tr> 766 767 <tr> 768 <td>600</td> 769 770 <td>.6</td> 771 772 <td>.8</td> 773 </tr> 774 775 <tr> 776 <td>800</td> 777 778 <td>.8</td> 779 780 <td>.9</td> 781 </tr> 782 783 <tr> 784 <td>1000</td> 785 786 <td>1</td> 787 788 <td>1</td> 789 </tr> 790 </table> 791 792 <p>As the table shows, the {@link android.view.animation.LinearInterpolator} changes the values 793 at the same speed, .2 for every 200ms that passes. The {@link 794 android.view.animation.AccelerateDecelerateInterpolator} changes the values faster than {@link 795 android.view.animation.LinearInterpolator} between 200ms and 600ms and slower between 600ms and 796 1000ms.</p> 797 798 <h2 id="keyframes">Specifying Keyframes</h2> 799 800 <p>A {@link android.animation.Keyframe} object consists of a time/value pair that lets you define 801 a specific state at a specific time of an animation. Each keyframe can also have its own 802 interpolator to control the behavior of the animation in the interval between the previous 803 keyframe's time and the time of this keyframe.</p> 804 805 <p>To instantiate a {@link android.animation.Keyframe} object, you must use one of the factory 806 methods, {@link android.animation.Keyframe#ofInt ofInt()}, {@link 807 android.animation.Keyframe#ofFloat ofFloat()}, or {@link android.animation.Keyframe#ofObject 808 ofObject()} to obtain the appropriate type of {@link android.animation.Keyframe}. You then call 809 the {@link android.animation.PropertyValuesHolder#ofKeyframe ofKeyframe()} factory method to 810 obtain a {@link android.animation.PropertyValuesHolder} object. Once you have the object, you can 811 obtain an animator by passing in the {@link android.animation.PropertyValuesHolder} object and 812 the object to animate. The following code snippet demonstrates how to do this:</p> 813 <pre> 814Keyframe kf0 = Keyframe.ofFloat(0f, 0f); 815Keyframe kf1 = Keyframe.ofFloat(.5f, 360f); 816Keyframe kf2 = Keyframe.ofFloat(1f, 0f); 817PropertyValuesHolder pvhRotation = PropertyValuesHolder.ofKeyframe("rotation", kf0, kf1, kf2); 818ObjectAnimator rotationAnim = ObjectAnimator.ofPropertyValuesHolder(target, pvhRotation) 819rotationAnim.setDuration(5000ms); 820</pre> 821 822 <p>For a more complete example on how to use keyframes, see the <a href= 823 "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/MultiPropertyAnimation.html"> 824 MultiPropertyAnimation</a> sample in APIDemos.</p> 825 826 <h2 id="views">Animating Views</h2> 827 828 <p>The property animation system allow streamlined animation of View objects and offerse 829 a few advantages over the view animation system. The view 830 animation system transformed View objects by changing the way that they were drawn. This was 831 handled in the container of each View, because the View itself had no properties to manipulate. 832 This resulted in the View being animated, but caused no change in the View object itself. This 833 led to behavior such as an object still existing in its original location, even though it was 834 drawn on a different location on the screen. In Android 3.0, new properties and the corresponding 835 getter and setter methods were added to eliminate this drawback.</p> 836 <p>The property animation system 837 can animate Views on the screen by changing the actual properties in the View objects. In 838 addition, Views also automatically call the {@link android.view.View#invalidate invalidate()} 839 method to refresh the screen whenever its properties are changed. The new properties in the {@link 840 android.view.View} class that facilitate property animations are:</p> 841 842 <ul> 843 <li><code>translationX</code> and <code>translationY</code>: These properties control where the 844 View is located as a delta from its left and top coordinates which are set by its layout 845 container.</li> 846 847 <li><code>rotation</code>, <code>rotationX</code>, and <code>rotationY</code>: These properties 848 control the rotation in 2D (<code>rotation</code> property) and 3D around the pivot point.</li> 849 850 <li><code>scaleX</code> and <code>scaleY</code>: These properties control the 2D scaling of a 851 View around its pivot point.</li> 852 853 <li><code>pivotX</code> and <code>pivotY</code>: These properties control the location of the 854 pivot point, around which the rotation and scaling transforms occur. By default, the pivot 855 point is located at the center of the object.</li> 856 857 <li><code>x</code> and <code>y</code>: These are simple utility properties to describe the 858 final location of the View in its container, as a sum of the left and top values and 859 translationX and translationY values.</li> 860 861 <li><code>alpha</code>: Represents the alpha transparency on the View. This value is 1 (opaque) 862 by default, with a value of 0 representing full transparency (not visible).</li> 863 </ul> 864 865 <p>To animate a property of a View object, such as its color or rotation value, all you need to 866 do is create a property animator and specify the View property that you want to 867 animate. For example:</p> 868 <pre> 869ObjectAnimator.ofFloat(myView, "rotation", 0f, 360f); 870</pre> 871 872<p>For more information on creating animators, see the sections on animating with 873<a href="#value-animator">ValueAnimator</a> and <a href="#object-animator">ObjectAnimator</a>. 874</p> 875 876<h3 id="view-prop-animator">Animating with ViewPropertyAnimator</h3> 877<p>The {@link android.view.ViewPropertyAnimator} provides a simple way to animate several 878properties of a {@link android.view.View} in parallel, using a single underlying {@link 879android.animation.Animator} 880object. It behaves much like an {@link android.animation.ObjectAnimator}, because it modifies the 881actual values of the view's properties, but is more efficient when animating many properties at 882once. In addition, the code for using the {@link android.view.ViewPropertyAnimator} is much 883more concise and easier to read. The following code snippets show the differences in using multiple 884{@link android.animation.ObjectAnimator} objects, a single 885{@link android.animation.ObjectAnimator}, and the {@link android.view.ViewPropertyAnimator} when 886simultaneously animating the <code>x</code> and <code>y</code> property of a view.</p> 887 888<p><strong>Multiple ObjectAnimator objects</strong></p> 889<pre> 890ObjectAnimator animX = ObjectAnimator.ofFloat(myView, "x", 50f); 891ObjectAnimator animY = ObjectAnimator.ofFloat(myView, "y", 100f); 892AnimatorSet animSetXY = new AnimatorSet(); 893animSetXY.playTogether(animX, animY); 894animSetXY.start(); 895</pre> 896 897<p><strong>One ObjectAnimator</strong></p> 898<pre> 899PropertyValuesHolder pvhX = PropertyValuesHolder.ofFloat("x", 50f); 900PropertyValuesHolder pvhY = PropertyValuesHolder.ofFloat("y", 100f); 901ObjectAnimator.ofPropertyValuesHolder(myView, pvhX, pvyY).start(); 902</pre> 903 904<p><strong>ViewPropertyAnimator</strong></p> 905<pre> 906myView.animate().x(50f).y(100f); 907</pre> 908 909<p> 910For more detailed information about {@link 911android.view.ViewPropertyAnimator}, see the corresponding Android Developers 912<a href="http://android-developers.blogspot.com/2011/05/introducing-viewpropertyanimator.html">blog 913post</a>.</p> 914 915<h2 id="declaring-xml">Declaring Animations in XML</h2> 916 917 <p>The property animation system lets you declare property animations with XML instead of doing 918 it programmatically. By defining your animations in XML, you can easily reuse your animations 919in multiple activities and more easily edit the animation sequence.</p> 920 921<p>To distinguish animation files that use the new property animation APIs from those that use the 922legacy <a href="{@docRoot}guide/topics/graphics/view-animation.html">view animation</a> framework, 923starting with Android 3.1, you should save the XML files for property animations in the {@code 924res/animator/} directory (instead of {@code res/anim/}). Using the {@code animator} directory name 925is optional, but necessary if you want to use the layout editor tools in the Eclipse ADT plugin (ADT 92611.0.0+), because ADT only searches the {@code res/animator/} directory for property animation 927resources.</p> 928 929<p>The following property animation classes have XML declaration support with the 930 following XML tags:</p> 931 932 <ul> 933 <li>{@link android.animation.ValueAnimator} - <code><animator></code></li> 934 935 <li>{@link android.animation.ObjectAnimator} - <code><objectAnimator></code></li> 936 937 <li>{@link android.animation.AnimatorSet} - <code><set></code></li> 938 </ul> 939 940<p>The following example plays the two sets of object animations sequentially, with the first nested 941set playing two object animations together:</p> 942 943<pre> 944<set android:ordering="sequentially"> 945 <set> 946 <objectAnimator 947 android:propertyName="x" 948 android:duration="500" 949 android:valueTo="400" 950 android:valueType="intType"/> 951 <objectAnimator 952 android:propertyName="y" 953 android:duration="500" 954 android:valueTo="300" 955 android:valueType="intType"/> 956 </set> 957 <objectAnimator 958 android:propertyName="alpha" 959 android:duration="500" 960 android:valueTo="1f"/> 961</set> 962</pre> 963 <p>In order to run this animation, you must inflate the XML resources in your code to an {@link 964 android.animation.AnimatorSet} object, and then set the target objects for all of the animations 965 before starting the animation set. Calling {@link android.animation.AnimatorSet#setTarget 966 setTarget()} sets a single target object for all children of the {@link 967 android.animation.AnimatorSet} as a convenience. The following code shows how to do this:</p> 968 969<pre> 970AnimatorSet set = (AnimatorSet) AnimatorInflater.loadAnimator(myContext, 971 R.anim.property_animator); 972set.setTarget(myObject); 973set.start(); 974</pre> 975 976<p>For information about the XML syntax for defining property animations, see <a 977href="{@docRoot}guide/topics/resources/animation-resource.html#Property">Animation Resources</a>. 978 979