From de113066d80c3f19979eb531484af73f64640de9 Mon Sep 17 00:00:00 2001 From: Ricardo Cervera Date: Mon, 12 Jan 2015 12:45:54 -0800 Subject: docs: Transitions training class. Change-Id: Ib41b42a890c44fdc001242bc356442ef9201b591 --- .../images/transitions/transition_sample_video.mp4 | Bin 0 -> 823950 bytes .../images/transitions/transition_sample_video.ogv | Bin 0 -> 210884 bytes .../transitions/transition_sample_video.webm | Bin 0 -> 215774 bytes .../images/transitions/transitions_diagram.png | Bin 0 -> 39338 bytes docs/html/training/training_toc.cs | 29 ++ .../training/transitions/custom-transitions.jd | 189 +++++++++++++ docs/html/training/transitions/index.jd | 80 ++++++ docs/html/training/transitions/overview.jd | 165 +++++++++++ docs/html/training/transitions/scenes.jd | 211 ++++++++++++++ docs/html/training/transitions/transitions.jd | 315 +++++++++++++++++++++ 10 files changed, 989 insertions(+) create mode 100644 docs/html/images/transitions/transition_sample_video.mp4 create mode 100644 docs/html/images/transitions/transition_sample_video.ogv create mode 100644 docs/html/images/transitions/transition_sample_video.webm create mode 100644 docs/html/images/transitions/transitions_diagram.png create mode 100644 docs/html/training/transitions/custom-transitions.jd create mode 100644 docs/html/training/transitions/index.jd create mode 100644 docs/html/training/transitions/overview.jd create mode 100644 docs/html/training/transitions/scenes.jd create mode 100644 docs/html/training/transitions/transitions.jd diff --git a/docs/html/images/transitions/transition_sample_video.mp4 b/docs/html/images/transitions/transition_sample_video.mp4 new file mode 100644 index 000000000000..37ae685864a1 Binary files /dev/null and b/docs/html/images/transitions/transition_sample_video.mp4 differ diff --git a/docs/html/images/transitions/transition_sample_video.ogv b/docs/html/images/transitions/transition_sample_video.ogv new file mode 100644 index 000000000000..55988147ae18 Binary files /dev/null and b/docs/html/images/transitions/transition_sample_video.ogv differ diff --git a/docs/html/images/transitions/transition_sample_video.webm b/docs/html/images/transitions/transition_sample_video.webm new file mode 100644 index 000000000000..346ba8c0c87d Binary files /dev/null and b/docs/html/images/transitions/transition_sample_video.webm differ diff --git a/docs/html/images/transitions/transitions_diagram.png b/docs/html/images/transitions/transitions_diagram.png new file mode 100644 index 000000000000..936394049d7f Binary files /dev/null and b/docs/html/images/transitions/transitions_diagram.png differ diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 0fcfb9c7b2b5..f5999a51b1b8 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -437,6 +437,35 @@ include the action bar on devices running Android 2.1 or higher." + +
  • +
    + Animating Views Using Scenes and Transitions +
    + +
    • +
  • + +
    + +

    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 lesson 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 {@link +android.transition.Transition} class and override the methods shown in the following snippet:

    + +
    +public class CustomTransition extends Transition {
+
+    @Override
+    public void captureStartValues(TransitionValues values) {}
+
+    @Override
+    public void captureEndValues(TransitionValues values) {}
+
+    @Override
+    public Animator createAnimator(ViewGroup sceneRoot,
+                                   TransitionValues startValues,
+                                   TransitionValues endValues) {}
+}
+
    + +

    The following sections explain how to override these methods.

    + + + +

    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 methods that allow a transition to +capture only the property values it needs and store them in the framework.

    + + +

    Capturing Starting Values

    + +

    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.

    + +

    To ensure that the key for a property value does not conflict with other {@link +android.transition.TransitionValues} keys, use the following naming scheme:

    + +
    +package_name:transition_name:property_name
+
    + +

    The following snippet shows an implementation of the {@link +android.transition.Transition#captureStartValues captureStartValues()} method:

    + +
    +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";
+
+    @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());
+    }
+    ...
+}
+
    + + +

    Capture Ending Values

    + +

    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()}.

    + +

    The following code snippet shows an implementation of the {@link +android.transition.Transition#captureEndValues captureEndValues()} method:

    + +
    +@Override
+public void captureEndValues(TransitionValues transitionValues) {
+    captureValues(transitionValues);
+}
+
    + +

    In this example, both the {@link android.transition.Transition#captureStartValues +captureStartValues()} and {@link android.transition.Transition#captureEndValues captureEndValues()} +methods 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 {@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.

    + +

    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.

    + +

    For target views that exist on both the starting and ending scenes, the framework provides +a {@link android.transition.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 {@link android.transition.TransitionValues} object +for the corresponding argument and null for the other.

    + +

    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 +ChangeColor class in the +CustomTransition sample. For more information about property animators, see +Property Animation.

    + + + +

    Apply a Custom Transition

    + +

    Custom transitions work the same as built-in transitions. You can apply a custom transition +using a transition manager, as described in Applying a Transition.

    diff --git a/docs/html/training/transitions/index.jd b/docs/html/training/transitions/index.jd new file mode 100644 index 000000000000..53faa01aad8b --- /dev/null +++ b/docs/html/training/transitions/index.jd @@ -0,0 +1,80 @@ +page.title=Animating Views Using Scenes and Transitions + +@jd:body + + +
    +
    +

    Dependencies and Prerequisites

    +
      +
    • Android 4.4.2 (API level 19) or higher
      • +
    +

    You should also read

    + +

    Try it out

    + +
    +
    + + + +
    +

    Video

    +

    DevBytes: Android 4.4 Transitions

    +
    +     + +

    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.

    + +

    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.

    + +

    Android includes the transitions framework, 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.

    + +

    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.

    + +

    Note: 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 animateLayoutChanges +attribute to animate layouts. To learn more, see +Property Animation and +Animating Layout Changes.

    + + +

    Lessons

    + +
    +
    +The Transitions Framework
    +
    + Learn the main features and components of the transitions framework. +
    +
    +Creating a Scene
    +
    + Learn how to create a scene to store the state of a view hierarchy. +
    +
    +Applying a Transition
    +
    + Learn how to apply a transition between two scenes of a view hierarchy. +
    +
    +Creating Custom Transitions
    +
    + Learn how to create other animation effects not included in the transitions framework. +
    +
    diff --git a/docs/html/training/transitions/overview.jd b/docs/html/training/transitions/overview.jd new file mode 100644 index 000000000000..044cf1691781 --- /dev/null +++ b/docs/html/training/transitions/overview.jd @@ -0,0 +1,165 @@ +page.title=The Transitions Framework + +@jd:body + +
    +
    +

    This lesson covers

    +
      +
    1. Overview
      2. +
    2. Scenes
      3. +
    3. Transitions
      4. +
    4. Limitations
      5. +
    +
    +
    + +

    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.

    + +

    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.

    + +

    The framework has the following features:

    + +
    +
    Group-level animations
    +
    Applies one or more animation effects to all of the views in a view hierarchy.
    +
    Transition-based animation
    +
    Runs animations based on the changes between starting and ending view property values.
    +
    Built-in animations
    +
    Includes predefined animations for common effects such as fade out or movement.
    + + +
    +
    + +
    +

    +Figure 1. Visual cues using user interface animation.

    +
     
    +
    + +
    Resource file support
    +
    Loads view hierarchies and built-in animations from layout resource files.
    +
    Lifecycle callbacks
    +
    Defines callbacks that provide finer control over the animation and hierarchy change +process.
    +
    + + + +

    Overview

    + +

    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.

    + +

    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 starting view hierarchy and the final or ending +view hierarchy.

    + +

    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.

    + +

    The diagram in Figure 2 illustrates the relationship between view hierarchies, framework +objects, and animations:

    + + + +

    Figure 2. Relationships in the transitions framework.

    + +

    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.

    + + + +

    Scenes

    + +

    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.

    + +

    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.

    + +

    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.

    + +

    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.

    + +

    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 scene root. +Changes to the scene and animations that affect the scene occur within the scene root.

    + +

    To learn how to create scenes, see +Creating a Scene.

    + + + +

    Transitions

    + +

    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.

    + +

    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.

    + +

    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.

    + +

    To learn more about transitions, see +Applying a Transition and +Creating Custom +Transitions.

    + + + +

    Limitations

    + +

    This section lists some known limitations of the transitions framework:

    + + diff --git a/docs/html/training/transitions/scenes.jd b/docs/html/training/transitions/scenes.jd new file mode 100644 index 000000000000..4bf7d0eac929 --- /dev/null +++ b/docs/html/training/transitions/scenes.jd @@ -0,0 +1,211 @@ +page.title=Creating a Scene + +@jd:body + + + +

    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.

    + +

    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.

    + +

    Note: The framework can animate changes in a single view +hierarchy without using scenes, as described in +Apply a Transition Without +Scenes. However, understanding this lesson is essential to work with transitions.

    + + + +

    Create a Scene From a Layout Resource

    + +

    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.

    + +

    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.

    + +

    Define Layouts for Scenes

    + +

    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.

    + +

    The example consists of the following layout definitions:

    + + + +

    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.

    + +

    The main layout for the activity is defined as follows:

    + +

    res/layout/activity_main.xml

    + +
    +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/master_layout">
+    <TextView
+        android:id="@+id/title"
+        ...
+        android:text="Title"/>
+    <FrameLayout
+        android:id="@+id/scene_root">
+        <include layout="@layout/a_scene" />
+    </FrameLayout>
+</LinearLayout>
+
    + +

    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.

    + +

    The layout for the first scene is defined as follows:

    + +

    res/layout/a_scene.xml

    + +
    +<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" >
+    <TextView
+        android:id="@+id/text_view1
+        android:text="Text Line 1" />
+    <TextView
+        android:id="@+id/text_view2
+        android:text="Text Line 2" />
+</RelativeLayout>
+
    + +

    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:

    + +

    res/layout/another_scene.xml

    + +
    +<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" >
+    <TextView
+        android:id="@+id/text_view2
+        android:text="Text Line 2" />
+    <TextView
+        android:id="@+id/text_view1
+        android:text="Text Line 1" />
+</RelativeLayout>
+
    + +

    Generate Scenes from Layouts

    + +

    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.

    + +

    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:

    + +
    +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);
+
    + +

    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 res/layout/activity_main.xml.

    + + + +

    Create a Scene in Your Code

    + +

    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.

    + +

    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.

    + +

    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:

    + +
    +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);
+
    + + + +

    Create Scene Actions

    + +

    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.

    + +

    Scene actions are useful for handling these cases:

    + + + +

    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.

    + +

    Note: Do not use scene actions to pass data between views in +the starting and ending scenes. For more information, see +Defining Transition +Lifecycle Callbacks.

    diff --git a/docs/html/training/transitions/transitions.jd b/docs/html/training/transitions/transitions.jd new file mode 100644 index 000000000000..489e291c79e0 --- /dev/null +++ b/docs/html/training/transitions/transitions.jd @@ -0,0 +1,315 @@ +page.title=Applying a Transition + +@jd:body + + + +

    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.

    + +

    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.

    + + + +

    Create a Transition

    + +

    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.

    + + +

    Table 1. Built-in transition types.

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    ClassTagAttributesEffect
    AutoTransition<autoTransition/> - Default transition. Fade out, move and resize, and fade in views, in that order.
    Fade<fade/>android:fadingMode="[fade_in |
    fade_out |
    fade_in_out]"    		 + fade_in fades in views
    + fade_out fades out views
    + fade_in_out (default) does a fade_out followed by a fade_in. +
    ChangeBounds<changeBounds/> - Moves and resizes views.
    + + +

    Create a transition instance from a resource file

    + +

    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 Specify Multiple +Transitions.

    + +

    To specify a built-in transition in a resource file, follow these steps:

    + +
      +
    1. Add the res/transition/ directory to your project.
      2. +
    2. Create a new XML resource file inside this directory.
      3. +
    3. Add an XML node for one of the built-in transitions.
      4. +
    + +

    For example, the following resource file specifies the {@link android.transition.Fade} +transition:

    + +

    res/transition/fade_transition.xml

    + +
    +<fade xmlns:android="http://schemas.android.com/apk/res/android" />
+
    + +

    The following code snippet shows how to inflate a {@link android.transition.Transition} +instance inside your activity from a resource file:

    + +
    +Transition mFadeTransition =
+        TransitionInflater.from(this).
+        inflateTransition(R.transition.fade_transition);
+
    + + +

    Create a transition instance in your code

    + +

    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.

    + +

    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:

    + +
    +Transition mFadeTransition = new Fade();
+
    + + + +

    Apply a Transition

    + +

    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.

    + +

    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:

    + +
    +TransitionManager.go(mEndingScene, mFadeTransition);
+
    + +

    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.

    + +

    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.

    + + + +

    Choose Specific Target Views

    + +

    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.

    + +

    Each view that the transition animates is called a target. You can only +select targets that are part of the view hierarchy associated with a scene.

    + +

    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.

    + + + +

    Specify Multiple Transitions

    + +

    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.

    + +

    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.

    + +

    To define a transition set from a collection of transitions in XML, create a resource file +in the res/transitions/ directory and list the transitions under the +transitionSet 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:

    + +
    +<transitionSet xmlns:android="http://schemas.android.com/apk/res/android"
+    android:transitionOrdering="sequential">
+    <fade android:fadingMode="fade_out" />
+    <changeBounds />
+    <fade android:fadingMode="fade_in" />
+</transitionSet>
+
    + +

    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.

    + + + +

    Apply a Transition Without Scenes

    + +

    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.

    + +

    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.

    + +

    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 delayed transition. 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.

    + +

    To create a delayed transition within a single view hierarchy, follow these steps:

    + +
      +
    1. 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.
      2. +
    2. 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.
      3. +
    3. When the system redraws the user interface according to your changes, the framework +animates the changes between the original state and the new state.
      4. +
    + +

    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:

    + +

    res/layout/activity_main.xml

    + +
    +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/mainLayout"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent" >
+    <EditText
+        android:id="@+id/inputText"
+        android:layout_alignParentLeft="true"
+        android:layout_alignParentTop="true"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content" />
+    ...
+</RelativeLayout>
+
    + +

    The next snippet shows the code that animates the addition of the text view:

    + +

    MainActivity.java

    + +
    +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
+
    + + + +

    Define Transition Lifecycle Callbacks

    + +

    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.

    + +

    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.

    + +

    For more information, see the API reference for the {@link +android.transition.Transition.TransitionListener TransitionListener} class.

    -- cgit v1.2.3-59-g8ed1b