Creating a Scene

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 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 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 Scene instance from a layout resource file, retrieve the scene root from your layout as a ViewGroup instance and then call the 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 Scene objects without implying that they are related to each other.

The example consists of the following layout definitions:

• The main layout of an activity with a text label and a child layout.
• A relative layout for the first scene with two text fields.
• A relative layout for the second scene with the same two text fields in different order.

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 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 Scene objects based on view hierarchies. Both scenes use the scene root defined by the FrameLayout element in res/layout/activity_main.xml.

Create a Scene in Your Code

You can also create a Scene instance in your code from a 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 Scene(sceneRoot, viewHierarchy) constructor. Calling this constructor is equivalent to calling the Scene.getSceneForLayout() method when you have already inflated a layout file.

The following code snippet demonstrates how to create a 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:

• 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.
• Animate views that the transitions framework cannot animate automatically, such as ListView objects. For more information, see Limitations.

To provide custom scene actions, define your actions as Runnable objects and pass them to the Scene.setExitAction() or Scene.setEnterAction() methods. The framework calls the setExitAction() method on the starting scene before running the transition animation and the 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.