Create a custom transition animation

A custom transition enables you to create an animation that is not available from any of
the built-in transition classes. For example, you can define a custom transition that turns
the foreground color of text and input fields to gray to indicate that the fields are disabled
in the new screen. This type of change helps users see the fields you disabled.

A custom transition, like one of the built-in transition types, applies animations to
child views of both the starting and ending scenes. Unlike built-in transition types,
however, you have to provide the code that captures property values and generates animations.
You may also want to define a subset of target views for your animation.

This page teaches you to capture property values and generate animations to create
custom transitions.

Extend the Transition class

To create a custom transition, add a class to your project that extends the Transition class and override the functions shown in the following snippet:

Capture view property values

Transition animations use the property animation system described in
Property animation. Property
animations change a view property between a starting and ending value over a specified
period of time, so the framework needs to have both the starting and ending value of
the property to construct the animation.

However, a property animation usually needs only a small subset of all the view's property
values. For example, a color animation needs color property values, while a movement
animation needs position property values. Since the property values needed for an animation
are specific to a transition, the transitions framework does not provide every property value
to a transition. Instead, the framework invokes callback functions that allow a transition to
capture only the property values it needs and store them in the framework.

Capture starting values

To pass the starting view values to the framework, implement the
captureStartValues(transitionValues)
function. The framework calls this function for every view in the starting scene. The function
argument is a TransitionValues object that contains a reference
to the view and a Map instance in which you can store the view values you
want. In your implementation, retrieve these property values and pass them back to the
framework by storing them in the map.

To ensure that the key for a property value does not conflict with other TransitionValues keys, use the following naming scheme:

Java

In this example, both the captureStartValues() and captureEndValues()
functions invoke captureValues() to retrieve and store values. The view property
that captureValues() retrieves is the same, but it has different values in the
starting and ending scenes. The framework maintains separate maps for the starting and ending
states of a view.

Create a custom animator

To animate the changes to a view between its state in the starting scene and its state in
the ending scene, you provide an animator by overriding the createAnimator() function. When the
framework calls this function, it passes in the scene root view and the TransitionValues objects that contain the starting and ending values
you captured.

The number of times the framework calls the createAnimator() function depends on the changes that
occur between the starting and ending scenes. For example, consider a fade out/fade in animation
implemented as a custom transition. If the starting scene has five targets of which two are
removed from the ending scene, and the ending scene has the three targets from the starting
scene plus a new target, then the framework calls createAnimator() six times: three of the calls
animate the fading out and fading in of the targets that stay in both scene objects; two more calls
animate the fading out of the targets removed from the ending scene; and one call
animates the fading in of the new target in the ending scene.

For target views that exist on both the starting and ending scenes, the framework provides
a TransitionValues object for both the startValues and
endValues arguments. For target views that only exist in the starting or the
ending scene, the framework provides a TransitionValues object
for the corresponding argument and null for the other.