Home | History | Annotate | Download | only in transitions 
      1 page.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
     18 the built-in transition classes. For example, you can define a custom transition that turns
     19 the foreground color of text and input fields to gray to indicate that the fields are disabled
     20 in 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
     23 child views of both the starting and ending scenes. Unlike built-in transition types,
     24 however, you have to provide the code that captures property values and generates animations.
     25 You 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
     28 custom 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
     35 android.transition.Transition} class and override the methods shown in the following snippet:</p>
     36 
     37 <pre>
     38 public class CustomTransition extends Transition {
     39 
     40     &#64;Override
     41     public void captureStartValues(TransitionValues values) {}
     42 
     43     &#64;Override
     44     public void captureEndValues(TransitionValues values) {}
     45 
     46     &#64;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
     61 animations change a view property between a starting and ending value over a specified
     62 period of time, so the framework needs to have both the starting and ending value of
     63 the 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
     66 values. For example, a color animation needs color property values, while a movement
     67 animation needs position property values. Since the property values needed for an animation
     68 are specific to a transition, the transitions framework does not provide every property value
     69 to a transition. Instead, the framework invokes callback methods that allow a transition to
     70 capture 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)}
     77 method. The framework calls this method for every view in the starting scene. The method
     78 argument is a {@link android.transition.TransitionValues} object that contains a reference
     79 to the view and a {@link java.util.Map} instance in which you can store the view values you
     80 want. In your implementation, retrieve these property values and pass them back to the
     81 framework 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
     84 android.transition.TransitionValues} keys, use the following naming scheme:</p>
     85 
     86 <pre>
     87 package_name:transition_name:property_name
     88 </pre>
     89 
     90 <p>The following snippet shows an implementation of the {@link
     91 android.transition.Transition#captureStartValues captureStartValues()} method:</p>
     92 
     93 <pre>
     94 public 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     &#64;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
    125 once for every target view in the ending scene. In all other respects, {@link
    126 android.transition.Transition#captureEndValues captureEndValues()} works the same as {@link
    127 android.transition.Transition#captureStartValues captureStartValues()}.</p>
    128 
    129 <p>The following code snippet shows an implementation of the {@link
    130 android.transition.Transition#captureEndValues captureEndValues()} method:</p>
    131 
    132 <pre>
    133 &#64;Override
    134 public void captureEndValues(TransitionValues transitionValues) {
    135     captureValues(transitionValues);
    136 }
    137 </pre>
    138 
    139 <p>In this example, both the {@link android.transition.Transition#captureStartValues
    140 captureStartValues()} and {@link android.transition.Transition#captureEndValues captureEndValues()}
    141 methods invoke <code>captureValues()</code> to retrieve and store values. The view property
    142 that <code>captureValues()</code> retrieves is the same, but it has different values in the
    143 starting and ending scenes. The framework maintains separate maps for the starting and ending
    144 states 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
    151 the ending scene, you provide an animator by overriding the {@link
    152 android.transition.Transition#createAnimator createAnimator()} method. When the
    153 framework calls this method, it passes in the scene root view and the {@link
    154 android.transition.TransitionValues} objects that contain the starting and ending values
    155 you captured.</p>
    156 
    157 <p>The number of times the framework calls the {@link
    158 android.transition.Transition#createAnimator createAnimator()} method depends on the changes that
    159 occur between the starting and ending scenes. For example, consider a fade out/fade in animation
    160 implemented as a custom transition. If the starting scene has five targets of which two are
    161 removed from the ending scene, and the ending scene has the three targets from the starting
    162 scene plus a new target, then the framework calls {@link
    163 android.transition.Transition#createAnimator createAnimator()} six times: three of the calls
    164 animate the fading out and fading in of the targets that stay in both scene objects; two more calls
    165 animate the fading out of the targets removed from the ending scene; and one call
    166 animates 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
    169 a {@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
    171 ending scene, the framework provides a {@link android.transition.TransitionValues} object
    172 for 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
    175 a custom transition, use the view property values you captured to create an {@link
    176 android.animation.Animator} object and return it to the framework. For an example implementation,
    177 see the <a
    178 href="{@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">
    180 CustomTransition</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
    188 using a transition manager, as described in <a
    189 href="{@docRoot}training/transitions/transitions.html#Apply">Applying a Transition</a>.</p>
    190