1page.title=Creating Custom Transitions 2 3@jd:body 4 5<div id="tb-wrapper"> 6<div id="tb"> 7<h2>This lesson teaches you to</h2> 8<ol> 9 <li><a href="#Extend">Extend the Transition Class</a></li> 10 <li><a href="#CaptureProperties">Capture View Property Values</a></li> 11 <li><a href="#CreateAnimator">Create a Custom Animator</a></li> 12 <li><a href="#Apply">Apply a Custom Transition</a></li> 13</ol> 14</div> 15</div> 16 17<p>A custom transition enables you to create an animation that is not available from any of 18the built-in transition classes. For example, you can define a custom transition that turns 19the foreground color of text and input fields to gray to indicate that the fields are disabled 20in the new screen. This type of change helps users see the fields you disabled.</p> 21 22<p>A custom transition, like one of the built-in transition types, applies animations to 23child views of both the starting and ending scenes. Unlike built-in transition types, 24however, you have to provide the code that captures property values and generates animations. 25You may also want to define a subset of target views for your animation.</p> 26 27<p>This lesson teaches you to capture property values and generate animations to create 28custom transitions.</p> 29 30 31 32<h2 id="Extend">Extend the Transition Class</h2> 33 34<p>To create a custom transition, add a class to your project that extends the {@link 35android.transition.Transition} class and override the methods shown in the following snippet:</p> 36 37<pre> 38public class CustomTransition extends Transition { 39 40 @Override 41 public void captureStartValues(TransitionValues values) {} 42 43 @Override 44 public void captureEndValues(TransitionValues values) {} 45 46 @Override 47 public Animator createAnimator(ViewGroup sceneRoot, 48 TransitionValues startValues, 49 TransitionValues endValues) {} 50} 51</pre> 52 53<p>The following sections explain how to override these methods.</p> 54 55 56 57<h2 id="CaptureProperties">Capture View Property Values</h2> 58 59<p>Transition animations use the property animation system described in 60<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>. Property 61animations change a view property between a starting and ending value over a specified 62period of time, so the framework needs to have both the starting and ending value of 63the property to construct the animation.</p> 64 65<p>However, a property animation usually needs only a small subset of all the view's property 66values. For example, a color animation needs color property values, while a movement 67animation needs position property values. Since the property values needed for an animation 68are specific to a transition, the transitions framework does not provide every property value 69to a transition. Instead, the framework invokes callback methods that allow a transition to 70capture only the property values it needs and store them in the framework.</p> 71 72 73<h3 id="StartingValues">Capturing Starting Values</h3> 74 75<p>To pass the starting view values to the framework, implement the 76{@link android.transition.Transition#captureStartValues captureStartValues(transitionValues)} 77method. The framework calls this method for every view in the starting scene. The method 78argument is a {@link android.transition.TransitionValues} object that contains a reference 79to the view and a {@link java.util.Map} instance in which you can store the view values you 80want. In your implementation, retrieve these property values and pass them back to the 81framework by storing them in the map.</p> 82 83<p>To ensure that the key for a property value does not conflict with other {@link 84android.transition.TransitionValues} keys, use the following naming scheme:</p> 85 86<pre> 87package_name:transition_name:property_name 88</pre> 89 90<p>The following snippet shows an implementation of the {@link 91android.transition.Transition#captureStartValues captureStartValues()} method:</p> 92 93<pre> 94public class CustomTransition extends Transition { 95 96 // Define a key for storing a property value in 97 // TransitionValues.values with the syntax 98 // package_name:transition_class:property_name to avoid collisions 99 private static final String PROPNAME_BACKGROUND = 100 "com.example.android.customtransition:CustomTransition:background"; 101 102 @Override 103 public void captureStartValues(TransitionValues transitionValues) { 104 // Call the convenience method captureValues 105 captureValues(transitionValues); 106 } 107 108 109 // For the view in transitionValues.view, get the values you 110 // want and put them in transitionValues.values 111 private void captureValues(TransitionValues transitionValues) { 112 // Get a reference to the view 113 View view = transitionValues.view; 114 // Store its background property in the values map 115 transitionValues.values.put(PROPNAME_BACKGROUND, view.getBackground()); 116 } 117 ... 118} 119</pre> 120 121 122<h3 id="EndingValues">Capture Ending Values</h3> 123 124<p>The framework calls the {@link android.transition.Transition#captureEndValues} method 125once for every target view in the ending scene. In all other respects, {@link 126android.transition.Transition#captureEndValues captureEndValues()} works the same as {@link 127android.transition.Transition#captureStartValues captureStartValues()}.</p> 128 129<p>The following code snippet shows an implementation of the {@link 130android.transition.Transition#captureEndValues captureEndValues()} method:</p> 131 132<pre> 133@Override 134public void captureEndValues(TransitionValues transitionValues) { 135 captureValues(transitionValues); 136} 137</pre> 138 139<p>In this example, both the {@link android.transition.Transition#captureStartValues 140captureStartValues()} and {@link android.transition.Transition#captureEndValues captureEndValues()} 141methods invoke <code>captureValues()</code> to retrieve and store values. The view property 142that <code>captureValues()</code> retrieves is the same, but it has different values in the 143starting and ending scenes. The framework maintains separate maps for the starting and ending 144states of a view.</p> 145 146 147 148<h2 id="CreateAnimator">Create a Custom Animator</h2> 149 150<p>To animate the changes to a view between its state in the starting scene and its state in 151the ending scene, you provide an animator by overriding the {@link 152android.transition.Transition#createAnimator createAnimator()} method. When the 153framework calls this method, it passes in the scene root view and the {@link 154android.transition.TransitionValues} objects that contain the starting and ending values 155you captured.</p> 156 157<p>The number of times the framework calls the {@link 158android.transition.Transition#createAnimator createAnimator()} method depends on the changes that 159occur between the starting and ending scenes. For example, consider a fade out/fade in animation 160implemented as a custom transition. If the starting scene has five targets of which two are 161removed from the ending scene, and the ending scene has the three targets from the starting 162scene plus a new target, then the framework calls {@link 163android.transition.Transition#createAnimator createAnimator()} six times: three of the calls 164animate the fading out and fading in of the targets that stay in both scene objects; two more calls 165animate the fading out of the targets removed from the ending scene; and one call 166animates the fading in of the new target in the ending scene.</p> 167 168<p>For target views that exist on both the starting and ending scenes, the framework provides 169a {@link android.transition.TransitionValues} object for both the <code>startValues</code> and 170<code>endValues</code> arguments. For target views that only exist in the starting or the 171ending scene, the framework provides a {@link android.transition.TransitionValues} object 172for the corresponding argument and <code>null</code> for the other.</p> 173 174<p>To implement the {@link android.transition.Transition#createAnimator} method when you create 175a custom transition, use the view property values you captured to create an {@link 176android.animation.Animator} object and return it to the framework. For an example implementation, 177see the <a 178href="{@docRoot}samples/CustomTransition/src/com.example.android.customtransition/ChangeColor.html"> 179<code>ChangeColor</code></a> class in the <a href="{@docRoot}samples/CustomTransition/index.html"> 180CustomTransition</a> sample. For more information about property animators, see 181<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>.</p> 182 183 184 185<h2 id="Apply">Apply a Custom Transition</h2> 186 187<p>Custom transitions work the same as built-in transitions. You can apply a custom transition 188using a transition manager, as described in <a 189href="{@docRoot}training/transitions/transitions.html#Apply">Applying a Transition</a>.</p> 190