Animating Views Using Scenes and Transitions - 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.

NEXT: APPLYING A TRANSITION