1page.title=Creating a Scene
2
3@jd:body
4
5<div id="tb-wrapper">
6<div id="tb">
7<h2>This lesson teaches you to</h2>
8<ol>
9  <li><a href="#FromLayout">Create a Scene From a Layout Resource</a></li>
10  <li><a href="#FromCode">Create a Scene in Your Code</a></li>
11  <li><a href="#Actions">Create Scene Actions</a></li>
12</ol>
13</div>
14</div>
15
16<p>Scenes store the state of a view hierarchy, including all its views and their property
17values. The transitions framework can run animations between a starting and an ending scene.
18The starting scene is often determined automatically from the current state of the user
19interface. For the ending scene, the framework enables you to create a scene from a layout
20resource file or from a group of views in your code.</p>
21
22<p>This lesson shows you how to create scenes in your app and how to define scene actions.
23The next lesson shows you how to transition between two scenes.</p>
24
25<p class="note"><strong>Note:</strong> The framework can animate changes in a single view
26hierarchy without using scenes, as described in
27<a href="{@docRoot}training/transitions/transitions.html#NoScenes">Apply a Transition Without
28Scenes</a>. However, understanding this lesson is essential to work with transitions.</p>
29
30
31
32<h2 id="FromLayout">Create a Scene From a Layout Resource</h2>
33
34<p>You can create a {@link android.transition.Scene} instance directly from a layout resource
35file. Use this technique when the view hierarchy in the file is mostly static. The resulting
36scene represents the state of the view hierarchy at the time you created the
37{@link android.transition.Scene} instance. If you change the view hierarchy, you have to
38recreate the scene. The framework creates the scene from the entire view hierarchy in the
39file; you can not create a scene from part of a layout file.</p>
40
41<p>To create a {@link android.transition.Scene} instance from a layout resource file, retrieve
42the scene root from your layout as a {@link android.view.ViewGroup} instance and then call the
43{@link android.transition.Scene#getSceneForLayout Scene.getSceneForLayout()} method with the
44scene root and the resource ID of the layout file that contains the view hierarchy for the
45scene.</p>
46
47<h3>Define Layouts for Scenes</h3>
48
49<p>The code snippets in the rest of this section show you how to create two different scenes
50with the same scene root element. The snippets also demonstrate that you can load multiple
51unrelated {@link android.transition.Scene} objects without implying that they are related to
52each other.</p>
53
54<p>The example consists of the following layout definitions:</p>
55
56<ul>
57<li>The main layout of an activity with a text label and a child layout.</li>
58<li>A relative layout for the first scene with two text fields.</li>
59<li>A relative layout for the second scene with the same two text fields in different order.</li>
60</ul>
61
62<p>The example is designed so that all of the animation occurs within the child layout of the
63main layout for the activity. The text label in the main layout remains static.</p>
64
65<p>The main layout for the activity is defined as follows:</p>
66
67<p class="code-caption">res/layout/activity_main.xml</p>
68
69<pre>
70&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
71    android:id="@+id/master_layout">
72    &lt;TextView
73        android:id="@+id/title"
74        ...
75        android:text="Title"/>
76    &lt;FrameLayout
77        android:id="@+id/scene_root">
78        &lt;include layout="@layout/a_scene" />
79    &lt;/FrameLayout>
80&lt;/LinearLayout>
81</pre>
82
83<p>This layout definition contains a text field and a child layout for the scene root. The
84layout for the first scene is included in the main layout file. This allows the app to display
85it as part of the initial user interface and also to load it into a scene, since the framework
86can load only a whole layout file into a scene.</p>
87
88<p>The layout for the first scene is defined as follows:</p>
89
90<p class="code-caption">res/layout/a_scene.xml</p>
91
92<pre>
93&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
94    android:id="@+id/scene_container"
95    android:layout_width="match_parent"
96    android:layout_height="match_parent" >
97    &lt;TextView
98        android:id="@+id/text_view1
99        android:text="Text Line 1" />
100    &lt;TextView
101        android:id="@+id/text_view2
102        android:text="Text Line 2" />
103&lt;/RelativeLayout>
104</pre>
105
106<p>The layout for the second scene contains the same two text fields (with the same IDs)
107placed in a different order and is defined as follows:</p>
108
109<p class="code-caption">res/layout/another_scene.xml</p>
110
111<pre>
112&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
113    android:id="@+id/scene_container"
114    android:layout_width="match_parent"
115    android:layout_height="match_parent" >
116    &lt;TextView
117        android:id="@+id/text_view2
118        android:text="Text Line 2" />
119    &lt;TextView
120        android:id="@+id/text_view1
121        android:text="Text Line 1" />
122&lt;/RelativeLayout>
123</pre>
124
125<h3>Generate Scenes from Layouts</h3>
126
127<p>After you create definitions for the two relative layouts, you can obtain an scene for
128each of them. This enables you to later transition between the two UI configurations.
129To obtain a scene, you need a reference to the scene root and the layout resource ID.</p>
130
131<p>The following code snippet shows you how to get a reference to the scene root and create
132two {@link android.transition.Scene} objects from the layout files:</p>
133
134<pre>
135Scene mAScene;
136Scene mAnotherScene;
137
138// Create the scene root for the scenes in this app
139mSceneRoot = (ViewGroup) findViewById(R.id.scene_root);
140
141// Create the scenes
142mAScene = Scene.getSceneForLayout(mSceneRoot, R.layout.a_scene, this);
143mAnotherScene =
144    Scene.getSceneForLayout(mSceneRoot, R.layout.another_scene, this);
145</pre>
146
147<p>In the app, there are now two {@link android.transition.Scene} objects based on view
148hierarchies. Both scenes use the scene root defined by the
149{@link android.widget.FrameLayout} element in <code>res/layout/activity_main.xml</code>.</p>
150
151
152
153<h2 id="FromCode">Create a Scene in Your Code</h2>
154
155<p>You can also create a {@link android.transition.Scene} instance in your code from a
156{@link android.view.ViewGroup} object. Use this technique when you modify the view hierarchies
157directly in your code or when you generate them dynamically.</p>
158
159<p>To create a scene from a view hierarchy in your code, use the
160{@link android.transition.Scene#Scene(android.view.ViewGroup, android.view.View) Scene(sceneRoot, viewHierarchy)}
161constructor. Calling this constructor is equivalent to calling the
162{@link android.transition.Scene#getSceneForLayout Scene.getSceneForLayout()} method when you
163have already inflated a layout file.</p>
164
165<p>The following code snippet demonstrates how to create a {@link android.transition.Scene}
166instance from the scene root element and the view hierarchy for the scene in your code:</p>
167
168<pre>
169Scene mScene;
170
171// Obtain the scene root element
172mSceneRoot = (ViewGroup) mSomeLayoutElement;
173
174// Obtain the view hierarchy to add as a child of
175// the scene root when this scene is entered
176mViewHierarchy = (ViewGroup) someOtherLayoutElement;
177
178// Create a scene
179mScene = new Scene(mSceneRoot, mViewHierarchy);
180</pre>
181
182
183
184<h2 id="Actions">Create Scene Actions</h2>
185
186<p>The framework enables you to define custom scene actions that the system runs when entering
187or exiting a scene. In many cases, defining custom scene actions is not necessary, since the
188framework animates the change between scenes automatically.</p>
189
190<p>Scene actions are useful for handling these cases:</p>
191
192<ul>
193<li>Animate views that are not in the same hierarchy. You can animate views for both the
194starting and ending scenes using exit and entry scene actions.</li>
195<li>Animate views that the transitions framework cannot animate automatically, such as
196{@link android.widget.ListView} objects. For more information, see
197<a href="{@docRoot}training/transitions/overview.html#Limitations">Limitations</a>.</li>
198</ul>
199
200<p>To provide custom scene actions, define your actions as {@link java.lang.Runnable} objects
201and pass them to the {@link android.transition.Scene#setExitAction Scene.setExitAction()} or
202{@link android.transition.Scene#setEnterAction Scene.setEnterAction()} methods. The framework
203calls the {@link android.transition.Scene#setExitAction setExitAction()} method on the starting
204scene before running the transition animation and the {@link
205android.transition.Scene#setEnterAction setEnterAction()} method on the ending scene after
206running the transition animation.</p>
207
208<p class="note"><strong>Note:</strong> Do not use scene actions to pass data between views in
209the starting and ending scenes. For more information, see
210<a href="{@docRoot}training/transitions/transitions.html#Callbacks">Defining Transition
211Lifecycle Callbacks</a>.</p>
212