Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am be3731f0: am f5386a9a: am 8ec3eb4e: am de113066: docs: Transitions training class.

Browse Source 
* commit 'be3731f028cf815d51e7c49b7415d7d1e8ac3639':
  docs: Transitions training class.
This commit is contained in:
Ricardo Cervera
2015-01-27 21:34:45 +00:00
committed by Android Git Automerger
parent 604a9e280e be3731f028
commit 8ff85c5ecb
10 changed files with 989 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/transitions/transition_sample_video.mp4 Normal file
View File

Binary file not shown.

BIN
docs/html/images/transitions/transition_sample_video.ogv Normal file
View File

Binary file not shown.

BIN
docs/html/images/transitions/transition_sample_video.webm Normal file
View File

Binary file not shown.

BIN
docs/html/images/transitions/transitions_diagram.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

29
docs/html/training/training_toc.cs
View File

@@ -437,6 +437,35 @@ include the action bar on devices running Android 2.1 or higher."
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot?>training/transitions/index.html"
description=
"How to animate state changes in a view hierarchy using transitions."
>Animating Views Using Scenes and Transitions</a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>training/transitions/overview.html">
The Transitions Framework
</a>
</li>
<li><a href="<?cs var:toroot ?>training/transitions/scenes.html">
Creating a Scene
</a>
</li>
<li><a href="<?cs var:toroot ?>training/transitions/transitions.html">
Applying a Transition
</a>
</li>
<li><a href="<?cs var:toroot ?>training/transitions/custom-transitions.html">
Creating Custom Transitions
</a>
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>training/animation/index.html"
description=

189
docs/html/training/transitions/custom-transitions.jd Normal file
View File

@@ -0,0 +1,189 @@
page.title=Creating Custom Transitions
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#Extend">Extend the Transition Class</a></li>
<li><a href="#CaptureProperties">Capture View Property Values</a></li>
<li><a href="#CreateAnimator">Create a Custom Animator</a></li>
<li><a href="#Apply">Apply a Custom Transition</a></li>
</ol>
</div>
</div>
<p>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.</p>
<p>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.</p>
<p>This lesson teaches you to capture property values and generate animations to create
custom transitions.</p>
<h2 id="Extend">Extend the Transition Class</h2>
<p>To create a custom transition, add a class to your project that extends the {@link
android.transition.Transition} class and override the methods shown in the following snippet:</p>
<pre>
public class CustomTransition extends Transition {
&#64;Override
public void captureStartValues(TransitionValues values) {}
&#64;Override
public void captureEndValues(TransitionValues values) {}
&#64;Override
public Animator createAnimator(ViewGroup sceneRoot,
TransitionValues startValues,
TransitionValues endValues) {}
}
</pre>
<p>The following sections explain how to override these methods.</p>
<h2 id="CaptureProperties">Capture View Property Values</h2>
<p>Transition animations use the property animation system described in
<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>. 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.</p>
<p>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 methods that allow a transition to
capture only the property values it needs and store them in the framework.</p>
<h3 id="StartingValues">Capturing Starting Values</h3>
<p>To pass the starting view values to the framework, implement the
{@link android.transition.Transition#captureStartValues captureStartValues(transitionValues)}
method. The framework calls this method for every view in the starting scene. The method
argument is a {@link android.transition.TransitionValues} object that contains a reference
to the view and a {@link java.util.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.</p>
<p>To ensure that the key for a property value does not conflict with other {@link
android.transition.TransitionValues} keys, use the following naming scheme:</p>
<pre>
package_name:transition_name:property_name
</pre>
<p>The following snippet shows an implementation of the {@link
android.transition.Transition#captureStartValues captureStartValues()} method:</p>
<pre>
public class CustomTransition extends Transition {
// Define a key for storing a property value in
// TransitionValues.values with the syntax
// package_name:transition_class:property_name to avoid collisions
private static final String PROPNAME_BACKGROUND =
"com.example.android.customtransition:CustomTransition:background";
&#64;Override
public void captureStartValues(TransitionValues transitionValues) {
// Call the convenience method captureValues
captureValues(transitionValues);
}
// For the view in transitionValues.view, get the values you
// want and put them in transitionValues.values
private void captureValues(TransitionValues transitionValues) {
// Get a reference to the view
View view = transitionValues.view;
// Store its background property in the values map
transitionValues.values.put(PROPNAME_BACKGROUND, view.getBackground());
}
...
}
</pre>
<h3 id="EndingValues">Capture Ending Values</h3>
<p>The framework calls the {@link android.transition.Transition#captureEndValues} method
once for every target view in the ending scene. In all other respects, {@link
android.transition.Transition#captureEndValues captureEndValues()} works the same as {@link
android.transition.Transition#captureStartValues captureStartValues()}.</p>
<p>The following code snippet shows an implementation of the {@link
android.transition.Transition#captureEndValues captureEndValues()} method:</p>
<pre>
&#64;Override
public void captureEndValues(TransitionValues transitionValues) {
captureValues(transitionValues);
}
</pre>
<p>In this example, both the {@link android.transition.Transition#captureStartValues
captureStartValues()} and {@link android.transition.Transition#captureEndValues captureEndValues()}
methods invoke <code>captureValues()</code> to retrieve and store values. The view property
that <code>captureValues()</code> 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.</p>
<h2 id="CreateAnimator">Create a Custom Animator</h2>
<p>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 {@link
android.transition.Transition#createAnimator createAnimator()} method. When the
framework calls this method, it passes in the scene root view and the {@link
android.transition.TransitionValues} objects that contain the starting and ending values
you captured.</p>
<p>The number of times the framework calls the {@link
android.transition.Transition#createAnimator createAnimator()} method 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 {@link
android.transition.Transition#createAnimator 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.</p>
<p>For target views that exist on both the starting and ending scenes, the framework provides
a {@link android.transition.TransitionValues} object for both the <code>startValues</code> and
<code>endValues</code> arguments. For target views that only exist in the starting or the
ending scene, the framework provides a {@link android.transition.TransitionValues} object
for the corresponding argument and <code>null</code> for the other.</p>
<p>To implement the {@link android.transition.Transition#createAnimator} method when you create
a custom transition, use the view property values you captured to create an {@link
android.animation.Animator} object and return it to the framework. For an example implementation,
see the <a
href="{@docRoot}samples/CustomTransition/src/com.example.android.customtransition/ChangeColor.html">
<code>ChangeColor</code></a> class in the <a href="{@docRoot}samples/CustomTransition/index.html">
CustomTransition</a> sample. For more information about property animators, see
<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>.</p>
<h2 id="Apply">Apply a Custom Transition</h2>
<p>Custom transitions work the same as built-in transitions. You can apply a custom transition
using a transition manager, as described in <a
href="{@docRoot}training/transitions/transitions.html#Apply">Applying a Transition</a>.</p>

80
docs/html/training/transitions/index.jd Normal file
View File

@@ -0,0 +1,80 @@
page.title=Animating Views Using Scenes and Transitions
@jd:body
<!-- Sidebox -->
<div id="tb-wrapper">
<div id="tb">
<h2>Dependencies and Prerequisites</h2>
<ul>
<li>Android 4.4.2 (API level 19) or higher</li>
</ul>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}guide/topics/ui/how-android-draws.html">
How Android Draws Views</a></li>
</ul>
<h2>Try it out</h2>
<ul>
<li><a href="{@docRoot}samples/BasicTransition/index.html">BasicTransition</a> sample</li>
<li><a href="{@docRoot}samples/CustomTransition/index.html">CustomTransition</a> sample</li>
</ul>
</div>
</div>
<!-- Video box -->
<a class="notice-developers-video wide" href="http://www.youtube.com/watch?v=S3H7nJ4QaD8">
<div>
<h3>Video</h3>
<p>DevBytes: Android 4.4 Transitions</p>
</div>
</a>
<p>The user interface of an activity often changes in response to user input and other events.
For example, an activity that contains a form where users can type search queries can hide
the form when the user submits it and show a list of search results in its place.</p>
<p>To provide visual continuity in these situations, you can animate changes between
different view hierarchies in your user interface. These animations give users feedback on
their actions and help them learn how your app works.</p>
<p>Android includes the <em>transitions framework</em>, which enables you to easily
animate changes between two view hierarchies. The framework animates the views at runtime by
changing some of their property values over time. The framework includes built-in animations
for common effects and lets you create custom animations and transition lifecycle callbacks.</p>
<p>This class teaches you to use the built-in animations in the transitions framework to
animate changes between view hierarchies. This class also covers how to create custom
animations.</p>
<p class="note"><strong>Note:</strong> For Android versions earlier than 4.4.2 (API level 19)
but greater than or equal to Android 4.0 (API level 14), use the <code>animateLayoutChanges</code>
attribute to animate layouts. To learn more, see
<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> and
<a href="{@docRoot}training/animation/layout.html">Animating Layout Changes</a>.</p>
<h2>Lessons</h2>
<dl>
<dt><a href="{@docRoot}training/transitions/overview.html">
The Transitions Framework</a></dt>
<dd>
Learn the main features and components of the transitions framework.
</dd>
<dt><a href="{@docRoot}training/transitions/scenes.html">
Creating a Scene</a></dt>
<dd>
Learn how to create a scene to store the state of a view hierarchy.
</dd>
<dt><a href="{@docRoot}training/transitions/transitions.html">
Applying a Transition</a></dt>
<dd>
Learn how to apply a transition between two scenes of a view hierarchy.
</dd>
<dt><a href="{@docRoot}training/transitions/custom-transitions.html">
Creating Custom Transitions</a></dt>
<dd>
Learn how to create other animation effects not included in the transitions framework.
</dd>
</dl>

165
docs/html/training/transitions/overview.jd Normal file
View File

@@ -0,0 +1,165 @@
page.title=The Transitions Framework
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson covers</h2>
<ol>
<li><a href="#Overview">Overview</a></li>
<li><a href="#Scenes">Scenes</a></li>
<li><a href="#Transitions">Transitions</a></li>
<li><a href="#Limitations">Limitations</a></li>
</ol>
</div>
</div>
<p>Animating your app's user interface provides more than just visual appeal. Animations
highlight changes and provide visual cues that help users learn how your app works.</p>
<p>To help you animate a change between one view hierarchy and another, Android provides the
transitions framework. This framework applies one or more animations to all the views in the
hierarchies as it changes between them.</p>
<p>The framework has the following features:</p>
<dl>
<dt><em>Group-level animations</em></dt>
<dd>Applies one or more animation effects to all of the views in a view hierarchy.</dd>
<dt><em>Transition-based animation</em></dt>
<dd>Runs animations based on the changes between starting and ending view property values.</dd>
<dt><em>Built-in animations</em></dt>
<dd>Includes predefined animations for common effects such as fade out or movement.</dd>
<!-- Figure 1 - Transitions video -->
<div style="float:right;margin-left:30px;margin-top:10px">
<div class="framed-nexus5-port-span-5" style="clear:left;">
<video class="play-on-hover" height="442" autoplay="" poster="">
<source src="{@docRoot}images/transitions/transition_sample_video.mp4" type="video/mp4">
<source src="{@docRoot}images/transitions/transition_sample_video.ogv" type="video/ogg">
<source src="{@docRoot}images/transitions/transition_sample_video.webm" type="video/webm">
</video>
</div>
<p class="img-caption" style="margin-top:7px;margin-bottom:0px">
<strong>Figure 1.</strong> Visual cues using user interface animation.</p>
<div style="margin-top:5px;margin-bottom:20px;font-size:10pt" class="video-instructions">&nbsp;</div>
</div>
<dt><em>Resource file support</em></dt>
<dd>Loads view hierarchies and built-in animations from layout resource files.</dd>
<dt><em>Lifecycle callbacks</em></dt>
<dd>Defines callbacks that provide finer control over the animation and hierarchy change
process.</dd>
</dl>
<h2 id="Overview">Overview</h2>
<p>The example in Figure 1 shows how an animation provides visual cues to help the user. As the
app changes from its search entry screen to its search results screen, it fades out views that
are no longer in use and fades in new views.</p>
<p>This animation is an example of using the transitions framework. The framework
animates changes to all the views in two view hierarchies. A view hierarchy can be as simple
as a single view or as complex as a {@link android.view.ViewGroup} containing an elaborate
tree of views. The framework animates each view by changing one or more of its property values
over time between the initial or <em>starting</em> view hierarchy and the final or <em>ending</em>
view hierarchy.</p>
<p>The transitions framework works in parallel with view hierarchies and animations. The
purpose of the framework is to store the state of view hierarchies, change between these
hierarchies in order to modify the appearance of the device screen, and animate the change by
storing and applying animation definitions.</p>
<p>The diagram in Figure 2 illustrates the relationship between view hierarchies, framework
objects, and animations:</p>
<!-- Figure 2 - diagram -->
<img src="{@docRoot}images/transitions/transitions_diagram.png"
width="506" height="234" alt="" style="margin-top:7px" />
<p class="img-caption"><strong>Figure 2.</strong> Relationships in the transitions framework.</p>
<p>The transitions framework provides abstractions for scenes, transitions, and transition
managers. These are described in detail in the following sections. To use the framework, you
create scenes for the view hierarchies in your app that you plan to change between. Next, you
create a transition for each animation you want to use. To start the animation between two
view hierarchies, you use a transition manager specifying the transition to use and the ending
scene. This procedure is described in detail in the remaining lessons in this class.</p>
<h2 id="Scenes">Scenes</h2>
<p>A scene stores the state of a view hierarchy, including all its views and their property
values. A view hierarchy can be a simple view or a complex tree of views and child layouts.
Storing the view hierarchy state in a scene enables you to transition into that state from
another scene. The framework provides the {@link android.transition.Scene} class to represent
a scene.</p>
<p>The transitions framework lets you create scenes from layout resource files or from
{@link android.view.ViewGroup} objects in your code. Creating a scene in your code is useful
if you generated a view hierarchy dynamically or if you are modifying it at runtime.</p>
<p>In most cases, you do not create a starting scene explicitly. If you have applied a
transition, the framework uses the previous ending scene as the starting scene for any
subsequent transitions. If you have not applied a transition, the framework collects information
about the views from the current state of the screen.</p>
<p>A scene can also define its own actions that run when you make a scene change. For example,
this feature is useful for cleaning up view settings after you transition to a scene.</p>
<p>In addition to the view hierarchy and its property values, a scene also stores a reference
to the parent of the view hierarchy. This root view is called a <strong>scene root</strong>.
Changes to the scene and animations that affect the scene occur within the scene root.</p>
<p>To learn how to create scenes, see
<a href="{@docRoot}training/transitions/scenes.html">Creating a Scene</a>.</p>
<h2 id="Transitions">Transitions</h2>
<p>In the transitions framework, animations create a series of frames that depict a change
between the view hierarchies in the starting and ending scenes. Information about the animation
is stored in a {@link android.transition.Transition} object. To run the animation, you apply the
transition using a {@link android.transition.TransitionManager} instance. The framework can
transition between two different scenes or transition to a different state for the current
scene.</p>
<p>The framework includes a set of built-in transitions for commonly-used animation effects,
such as fading and resizing views. You can also define your own custom transitions to create
an animation effect using the APIs in the animations framework. The transitions framework also
enables you to combine different animation effects in a transition set that contains a group
of individual built-in or custom transitions.</p>
<p>The transition lifecycle is similar to the activity lifecycle, and it represents the
transition states that the framework monitors between the start and the completion of an
animation. At important lifecycle states, the framework invokes callback methods that you can
implement to make adjustments to your user interface at different phases of the transition.</p>
<p>To learn more about transitions, see
<a href="{@docRoot}training/transitions/transitions.html">Applying a Transition</a> and
<a href="{@docRoot}training/transitions/custom-transitions.html">Creating Custom
Transitions</a>.</p>
<h2 id="Limitations">Limitations</h2>
<p>This section lists some known limitations of the transitions framework:</p>
<ul>
<li>Animations applied to a {@link android.view.SurfaceView} may not appear correctly.
{@link android.view.SurfaceView} instances are updated from a non-UI thread, so the updates
may be out of sync with the animations of other views.</li>
<li>Some specific transition types may not produce the desired animation effect when applied
to a {@link android.view.TextureView}.</li>
<li>Classes that extend {@link android.widget.AdapterView}, such as
{@link android.widget.ListView}, manage their child views in ways that are incompatible with
the transitions framework. If you try to animate a view based on
{@link android.widget.AdapterView}, the device display may hang.</li>
<li>If you try to resize a {@link android.widget.TextView} with an animation, the text will
pop to a new location before the object has completely resized. To avoid this problem, do not
animate the resizing of views that contain text.</li>
</ul>

211
docs/html/training/transitions/scenes.jd Normal file
View File

@@ -0,0 +1,211 @@
page.title=Creating a Scene
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#FromLayout">Create a Scene From a Layout Resource</a></li>
<li><a href="#FromCode">Create a Scene in Your Code</a></li>
<li><a href="#Actions">Create Scene Actions</a></li>
</ol>
</div>
</div>
<p>Scenes store the state of a view hierarchy, including all its views and their property
values. The transitions framework can run animations between a starting and an ending scene.
The starting scene is often determined automatically from the current state of the user
interface. For the ending scene, the framework enables you to create a scene from a layout
resource file or from a group of views in your code.</p>
<p>This lesson shows you how to create scenes in your app and how to define scene actions.
The next lesson shows you how to transition between two scenes.</p>
<p class="note"><strong>Note:</strong> The framework can animate changes in a single view
hierarchy without using scenes, as described in
<a href="{@docRoot}training/transitions/transitions.html#NoScenes">Apply a Transition Without
Scenes</a>. However, understanding this lesson is essential to work with transitions.</p>
<h2 id="FromLayout">Create a Scene From a Layout Resource</h2>
<p>You can create a {@link android.transition.Scene} instance directly from a layout resource
file. Use this technique when the view hierarchy in the file is mostly static. The resulting
scene represents the state of the view hierarchy at the time you created the
{@link android.transition.Scene} instance. If you change the view hierarchy, you have to
recreate the scene. The framework creates the scene from the entire view hierarchy in the
file; you can not create a scene from part of a layout file.</p>
<p>To create a {@link android.transition.Scene} instance from a layout resource file, retrieve
the scene root from your layout as a {@link android.view.ViewGroup} instance and then call the
{@link android.transition.Scene#getSceneForLayout Scene.getSceneForLayout()} method with the
scene root and the resource ID of the layout file that contains the view hierarchy for the
scene.</p>
<h3>Define Layouts for Scenes</h3>
<p>The code snippets in the rest of this section show you how to create two different scenes
with the same scene root element. The snippets also demonstrate that you can load multiple
unrelated {@link android.transition.Scene} objects without implying that they are related to
each other.</p>
<p>The example consists of the following layout definitions:</p>
<ul>
<li>The main layout of an activity with a text label and a child layout.</li>
<li>A relative layout for the first scene with two text fields.</li>
<li>A relative layout for the second scene with the same two text fields in different order.</li>
</ul>
<p>The example is designed so that all of the animation occurs within the child layout of the
main layout for the activity. The text label in the main layout remains static.</p>
<p>The main layout for the activity is defined as follows:</p>
<p class="code-caption">res/layout/activity_main.xml</p>
<pre>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/master_layout">
&lt;TextView
android:id="@+id/title"
...
android:text="Title"/>
&lt;FrameLayout
android:id="@+id/scene_root">
&lt;include layout="@layout/a_scene" />
&lt;/FrameLayout>
&lt;/LinearLayout>
</pre>
<p>This layout definition contains a text field and a child layout for the scene root. The
layout for the first scene is included in the main layout file. This allows the app to display
it as part of the initial user interface and also to load it into a scene, since the framework
can load only a whole layout file into a scene.</p>
<p>The layout for the first scene is defined as follows:</p>
<p class="code-caption">res/layout/a_scene.xml</p>
<pre>
&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/scene_container"
android:layout_width="match_parent"
android:layout_height="match_parent" >
&lt;TextView
android:id="@+id/text_view1
android:text="Text Line 1" />
&lt;TextView
android:id="@+id/text_view2
android:text="Text Line 2" />
&lt;/RelativeLayout>
</pre>
<p>The layout for the second scene contains the same two text fields (with the same IDs)
placed in a different order and is defined as follows:</p>
<p class="code-caption">res/layout/another_scene.xml</p>
<pre>
&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/scene_container"
android:layout_width="match_parent"
android:layout_height="match_parent" >
&lt;TextView
android:id="@+id/text_view2
android:text="Text Line 2" />
&lt;TextView
android:id="@+id/text_view1
android:text="Text Line 1" />
&lt;/RelativeLayout>
</pre>
<h3>Generate Scenes from Layouts</h3>
<p>After you create definitions for the two relative layouts, you can obtain an scene for
each of them. This enables you to later transition between the two UI configurations.
To obtain a scene, you need a reference to the scene root and the layout resource ID.</p>
<p>The following code snippet shows you how to get a reference to the scene root and create
two {@link android.transition.Scene} objects from the layout files:</p>
<pre>
Scene mAScene;
Scene mAnotherScene;
// Create the scene root for the scenes in this app
mSceneRoot = (ViewGroup) findViewById(R.id.scene_root);
// Create the scenes
mAScene = Scene.getSceneForLayout(mSceneRoot, R.layout.a_scene, this);
mAnotherScene =
Scene.getSceneForLayout(mSceneRoot, R.layout.another_scene, this);
</pre>
<p>In the app, there are now two {@link android.transition.Scene} objects based on view
hierarchies. Both scenes use the scene root defined by the
{@link android.widget.FrameLayout} element in <code>res/layout/activity_main.xml</code>.</p>
<h2 id="FromCode">Create a Scene in Your Code</h2>
<p>You can also create a {@link android.transition.Scene} instance in your code from a
{@link android.view.ViewGroup} object. Use this technique when you modify the view hierarchies
directly in your code or when you generate them dynamically.</p>
<p>To create a scene from a view hierarchy in your code, use the
{@link android.transition.Scene#Scene(android.view.ViewGroup, android.view.View) Scene(sceneRoot, viewHierarchy)}
constructor. Calling this constructor is equivalent to calling the
{@link android.transition.Scene#getSceneForLayout Scene.getSceneForLayout()} method when you
have already inflated a layout file.</p>
<p>The following code snippet demonstrates how to create a {@link android.transition.Scene}
instance from the scene root element and the view hierarchy for the scene in your code:</p>
<pre>
Scene mScene;
// Obtain the scene root element
mSceneRoot = (ViewGroup) mSomeLayoutElement;
// Obtain the view hierarchy to add as a child of
// the scene root when this scene is entered
mViewHierarchy = (ViewGroup) someOtherLayoutElement;
// Create a scene
mScene = new Scene(mSceneRoot, mViewHierarchy);
</pre>
<h2 id="Actions">Create Scene Actions</h2>
<p>The framework enables you to define custom scene actions that the system runs when entering
or exiting a scene. In many cases, defining custom scene actions is not necessary, since the
framework animates the change between scenes automatically.</p>
<p>Scene actions are useful for handling these cases:</p>
<ul>
<li>Animate views that are not in the same hierarchy. You can animate views for both the
starting and ending scenes using exit and entry scene actions.</li>
<li>Animate views that the transitions framework cannot animate automatically, such as
{@link android.widget.ListView} objects. For more information, see
<a href="{@docRoot}training/transitions/overview.html#Limitations">Limitations</a>.</li>
</ul>
<p>To provide custom scene actions, define your actions as {@link java.lang.Runnable} objects
and pass them to the {@link android.transition.Scene#setExitAction Scene.setExitAction()} or
{@link android.transition.Scene#setEnterAction Scene.setEnterAction()} methods. The framework
calls the {@link android.transition.Scene#setExitAction setExitAction()} method on the starting
scene before running the transition animation and the {@link
android.transition.Scene#setEnterAction setEnterAction()} method on the ending scene after
running the transition animation.</p>
<p class="note"><strong>Note:</strong> Do not use scene actions to pass data between views in
the starting and ending scenes. For more information, see
<a href="{@docRoot}training/transitions/transitions.html#Callbacks">Defining Transition
Lifecycle Callbacks</a>.</p>

315
docs/html/training/transitions/transitions.jd Normal file
View File

@@ -0,0 +1,315 @@
page.title=Applying a Transition
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#Create">Create a Transition</a></li>
<li><a href="#Apply">Apply a Transition</a></li>
<li><a href="#Targets">Choose Specific Target Views</a></li>
<li><a href="#Multiple">Specify Multiple Transitions</a></li>
<li><a href="#NoScenes">Apply a Transition Without Scenes</a></li>
<li><a href="#Callbacks">Define Transition Lifecycle Callbacks</a></li>
</ol>
</div>
</div>
<p>In the transitions framework, animations create a series of frames that depict a change
between the view hierarchies in the starting and ending scenes. The framework represents
these animations as transition objects, which contain information about an animation. To
run an animation, you provide the transition to use and the ending scene to a transition
manager.</p>
<p>This lesson teaches you run an animation between two scenes using built-in transitions
to move, resize, and fade views. The next lesson shows you how to define custom transitions.</p>
<h2 id="Create">Create a Transition</h2>
<p>In the previous lesson, you learned how to create scenes that represent the state of
different view hierarchies. Once you have defined the starting scene and the ending scene you
want to change between, you need to create a {@link android.transition.Transition} object
that defines an animation. The framework enables you to specify a built-in transition in a
resource file and inflate it in your code or to create an instance of a built-in transition
directly in your code.</p>
<!-- Built in transition table -->
<p class="table-caption" id="table1"><strong>Table 1.</strong> Built-in transition types.</p>
<table>
<tr>
<th scope="col">Class</th>
<th scope="col">Tag</th>
<th scope="col">Attributes</th>
<th scope="col">Effect</th>
</tr>
<tr>
<td><code><a href="/reference/android/transition/AutoTransition.html">AutoTransition</a></code></td>
<td>&lt;autoTransition/&gt;</td>
<td style="text-align=center;"> - </td>
<td>Default transition. Fade out, move and resize, and fade in views, in that order.</td>
</tr>
<tr>
<td><code><a href="/reference/android/transition/Fade.html">Fade</a></code></td>
<td>&lt;fade/&gt;</td>
<td><code>android:fadingMode="[fade_in |<br> fade_out |<br> fade_in_out]"</code></td>
<td>
<code>fade_in</code> fades in views<br>
<code>fade_out</code> fades out views<br>
<code>fade_in_out</code> (default) does a <code>fade_out</code> followed by a <code>fade_in</code>.
</td>
</tr>
<tr>
<td><code><a href="/reference/android/transition/ChangeBounds.html">ChangeBounds</a></code></td>
<td>&lt;changeBounds/&gt;</td>
<td style="text-align=center;"> - </td>
<td>Moves and resizes views.</td>
</tr>
</table>
<h3 id="FromFile">Create a transition instance from a resource file</h3>
<p>This technique enables you to modify your transition definition without having to change
the code of your activity. This technique is also useful to separate complex transition
definitions from your application code, as shown in <a href="#Multiple">Specify Multiple
Transitions</a>.</p>
<p>To specify a built-in transition in a resource file, follow these steps:</p>
<ol>
<li>Add the <code>res/transition/</code> directory to your project.</li>
<li>Create a new XML resource file inside this directory.</li>
<li>Add an XML node for one of the built-in transitions.</li>
</ol>
<p>For example, the following resource file specifies the {@link android.transition.Fade}
transition:</p>
<p class="code-caption">res/transition/fade_transition.xml</p>
<pre>
&lt;fade xmlns:android="http://schemas.android.com/apk/res/android" />
</pre>
<p>The following code snippet shows how to inflate a {@link android.transition.Transition}
instance inside your activity from a resource file:</p>
<pre>
Transition mFadeTransition =
TransitionInflater.from(this).
inflateTransition(R.transition.fade_transition);
</pre>
<h3 id="FromCode">Create a transition instance in your code</h3>
<p>This technique is useful for creating transition objects dynamically if you modify the user
interface in your code, and to create simple built-in transition instances with few or
no parameters.</p>
<p>To create an instance of a built-in transition, invoke one of the public constructors in
the subclasses of the {@link android.transition.Transition} class. For example, the following
code snippet creates an instance of the {@link android.transition.Fade} transition:</p>
<pre>
Transition mFadeTransition = new Fade();
</pre>
<h2 id="Apply">Apply a Transition</h2>
<p>You typically apply a transition to change between different view hierarchies in response
to an event, such as a user action. For example, consider a search app: when the user enters
a search term and clicks the search button, the app changes to the scene that represents the
results layout while applying a transition that fades out the search button and fades in the
search results.</p>
<p>To make a scene change while applying a transition in response to some event in your
activity, call the {@link android.transition.TransitionManager#go TransitionManager.go()}
static method with the ending scene and the transition instance to use for the animation,
as shown in the following snippet:</p>
<pre>
TransitionManager.go(mEndingScene, mFadeTransition);
</pre>
<p>The framework changes the view hierarchy inside the scene root with the view hierarchy
from the ending scene while running the animation specified by the transition instance. The
starting scene is the ending scene from the last transition. If there was no previous
transition, the starting scene is determined automatically from the current state of the
user interface.</p>
<p>If you do not specify a transition instance, the transition manager can apply an automatic
transition that does something reasonable for most situations. For more information, see the
API reference for the {@link android.transition.TransitionManager} class.</p>
<h2 id="Targets">Choose Specific Target Views</h2>
<p>The framework applies transitions to all views in the starting and ending scenes by
default. In some cases, you may only want to apply an animation to a subset of views in a
scene. For example, the framework does not support animating changes to
{@link android.widget.ListView} objects, so you should not try to animate them during a
transition. The framework enables you to select specific views you want to animate.</p>
<p>Each view that the transition animates is called a <em>target</em>. You can only
select targets that are part of the view hierarchy associated with a scene.</p>
<p>To remove one or more views from the list of targets, call the {@link
android.transition.Transition#removeTarget removeTarget()} method before starting
the transition. To add only the views you specify to the list of targets, call the
{@link android.transition.Transition#addTarget addTarget()} method. For more
information, see the API reference for the {@link android.transition.Transition} class.</p>
<h2 id="Multiple">Specify Multiple Transitions</h2>
<p>To get the most impact from an animation, you should match it to the type of changes
that occur between the scenes. For example, if you are removing some views and adding others
between scenes, a fade out/fade in animation provides a noticeable indication that some views
are no longer available. If you are moving views to different points on the screen, a better
choice would be to animate the movement so that users notice the new location of the views.</p>
<p>You do not have to choose only one animation, since the transitions framework enables you
to combine animation effects in a transition set that contains a group of individual built-in
or custom transitions.</p>
<p>To define a transition set from a collection of transitions in XML, create a resource file
in the <code>res/transitions/</code> directory and list the transitions under the
<code>transitionSet</code> element. For example, the following snippet shows how to specify a
transition set that has the same behaviour as the {@link android.transition.AutoTransition}
class:</p>
<pre>
&lt;transitionSet xmlns:android="http://schemas.android.com/apk/res/android"
android:transitionOrdering="sequential">
&lt;fade android:fadingMode="fade_out" />
&lt;changeBounds />
&lt;fade android:fadingMode="fade_in" />
&lt;/transitionSet>
</pre>
<p>To inflate the transition set into a {@link android.transition.TransitionSet} object in
your code, call the {@link android.transition.TransitionInflater#from TransitionInflater.from()}
method in your activity. The {@link android.transition.TransitionSet} class extends from the
{@link android.transition.Transition} class, so you can use it with a transition manager just
like any other {@link android.transition.Transition} instance.</p>
<h2 id="NoScenes">Apply a Transition Without Scenes</h2>
<p>Changing view hierarchies is not the only way to modify your user interface. You can also
make changes by adding, modifying, and removing child views within the current hierarchy. For
example, you can implement a search interaction with just a single layout. Start with the
layout showing a search entry field and a search icon. To change the user interface to show
the results, remove the search button when the user clicks it by calling the {@link
android.view.ViewGroup#removeView ViewGroup.removeView()} method, and add the search results by
calling {@link android.view.ViewGroup#addView ViewGroup.addView()} method.</p>
<p>You may want to use this approach if the alternative is to have two hierarchies that are
nearly identical. Rather than having to create and maintain two separate layout files for a
minor difference in the user interface, you can have one layout file containing a view
hierarchy that you modify in code.</p>
<p>If you make changes within the current view hierarchy in this fashion, you do not need to
create a scene. Instead, you can create and apply a transition between two states of a view
hierarchy using a <em>delayed transition</em>. This feature of the transitions framework
starts with the current view hierarchy state, records changes you make to its views, and applies
a transition that animates the changes when the system redraws the user interface.</p>
<p>To create a delayed transition within a single view hierarchy, follow these steps:</p>
<ol>
<li>When the event that triggers the transition occurs, call the {@link
android.transition.TransitionManager#beginDelayedTransition
TransitionManager.beginDelayedTransition()} method providing the parent view of all the views
you want to change and the transition to use. The framework stores the current state of the
child views and their property values.</li>
<li>Make changes to the child views as required by your use case. The framework records
the changes you make to the child views and their properties.</li>
<li>When the system redraws the user interface according to your changes, the framework
animates the changes between the original state and the new state.</li>
</ol>
<p>The following example shows how to animate the addition of a text view to a view hierarchy
using a delayed transition. The first snippet shows the layout definition file:</p>
<p class="code-caption">res/layout/activity_main.xml</p>
<pre>
&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/mainLayout"
android:layout_width="match_parent"
android:layout_height="match_parent" >
&lt;EditText
android:id="@+id/inputText"
android:layout_alignParentLeft="true"
android:layout_alignParentTop="true"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
...
&lt;/RelativeLayout>
</pre>
<p>The next snippet shows the code that animates the addition of the text view:</p>
<p class="code-caption">MainActivity.java</p>
<pre>
private TextView mLabelText;
private Fade mFade;
private ViewGroup mRootView;
...
// Load the layout
this.setContentView(R.layout.activity_main);
...
// Create a new TextView and set some View properties
mLabelText = new TextView();
mLabelText.setText("Label").setId("1");
// Get the root view and create a transition
mRootView = (ViewGroup) findViewById(R.id.mainLayout);
mFade = new Fade(IN);
// Start recording changes to the view hierarchy
TransitionManager.beginDelayedTransition(mRootView, mFade);
// Add the new TextView to the view hierarchy
mRootView.addView(mLabelText);
// When the system redraws the screen to show this update,
// the framework will animate the addition as a fade in
</pre>
<h2 id="Callbacks">Define Transition Lifecycle Callbacks</h2>
<p>The transition lifecycle is similar to the activity lifecycle. It represents the transition
states that the framework monitors during the time between a call to the {@link
android.transition.TransitionManager#go TransitionManager.go()} method and the completion of
the animation. At important lifecycle states, the framework invokes callbacks defined by
the {@link android.transition.Transition.TransitionListener TransitionListener}
interface.</p>
<p>Transition lifecycle callbacks are useful, for example, for copying a view property value
from the starting view hierarchy to the ending view hierarchy during a scene change. You
cannot simply copy the value from its starting view to the view in the ending view hierarchy,
because the ending view hierarchy is not inflated until the transition is completed.
Instead, you need to store the value in a variable and then copy it into the ending view
hierarchy when the framework has finished the transition. To get notified when the transition
is completed, you can implement the {@link
android.transition.Transition.TransitionListener#onTransitionEnd
TransitionListener.onTransitionEnd()} method in your activity.</p>
<p>For more information, see the API reference for the {@link
android.transition.Transition.TransitionListener TransitionListener} class.</p>