1 page.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 17 values. The transitions framework can run animations between a starting and an ending scene. 18 The starting scene is often determined automatically from the current state of the user 19 interface. For the ending scene, the framework enables you to create a scene from a layout 20 resource 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. 23 The 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 26 hierarchy without using scenes, as described in 27 <a href="{@docRoot}training/transitions/transitions.html#NoScenes">Apply a Transition Without 28 Scenes</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 35 file. Use this technique when the view hierarchy in the file is mostly static. The resulting 36 scene 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 38 recreate the scene. The framework creates the scene from the entire view hierarchy in the 39 file; 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 42 the 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 44 scene root and the resource ID of the layout file that contains the view hierarchy for the 45 scene.</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 50 with the same scene root element. The snippets also demonstrate that you can load multiple 51 unrelated {@link android.transition.Scene} objects without implying that they are related to 52 each 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 63 main 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 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" 71 android:id="@+id/master_layout"> 72 <TextView 73 android:id="@+id/title" 74 ... 75 android:text="Title"/> 76 <FrameLayout 77 android:id="@+id/scene_root"> 78 <include layout="@layout/a_scene" /> 79 </FrameLayout> 80 </LinearLayout> 81 </pre> 82 83 <p>This layout definition contains a text field and a child layout for the scene root. The 84 layout for the first scene is included in the main layout file. This allows the app to display 85 it as part of the initial user interface and also to load it into a scene, since the framework 86 can 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 <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 <TextView 98 android:id="@+id/text_view1 99 android:text="Text Line 1" /> 100 <TextView 101 android:id="@+id/text_view2 102 android:text="Text Line 2" /> 103 </RelativeLayout> 104 </pre> 105 106 <p>The layout for the second scene contains the same two text fields (with the same IDs) 107 placed 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 <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 <TextView 117 android:id="@+id/text_view2 118 android:text="Text Line 2" /> 119 <TextView 120 android:id="@+id/text_view1 121 android:text="Text Line 1" /> 122 </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 128 each of them. This enables you to later transition between the two UI configurations. 129 To 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 132 two {@link android.transition.Scene} objects from the layout files:</p> 133 134 <pre> 135 Scene mAScene; 136 Scene mAnotherScene; 137 138 // Create the scene root for the scenes in this app 139 mSceneRoot = (ViewGroup) findViewById(R.id.scene_root); 140 141 // Create the scenes 142 mAScene = Scene.getSceneForLayout(mSceneRoot, R.layout.a_scene, this); 143 mAnotherScene = 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 148 hierarchies. 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 157 directly 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)} 161 constructor. Calling this constructor is equivalent to calling the 162 {@link android.transition.Scene#getSceneForLayout Scene.getSceneForLayout()} method when you 163 have already inflated a layout file.</p> 164 165 <p>The following code snippet demonstrates how to create a {@link android.transition.Scene} 166 instance from the scene root element and the view hierarchy for the scene in your code:</p> 167 168 <pre> 169 Scene mScene; 170 171 // Obtain the scene root element 172 mSceneRoot = (ViewGroup) mSomeLayoutElement; 173 174 // Obtain the view hierarchy to add as a child of 175 // the scene root when this scene is entered 176 mViewHierarchy = (ViewGroup) someOtherLayoutElement; 177 178 // Create a scene 179 mScene = 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 187 or exiting a scene. In many cases, defining custom scene actions is not necessary, since the 188 framework 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 194 starting 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 201 and pass them to the {@link android.transition.Scene#setExitAction Scene.setExitAction()} or 202 {@link android.transition.Scene#setEnterAction Scene.setEnterAction()} methods. The framework 203 calls the {@link android.transition.Scene#setExitAction setExitAction()} method on the starting 204 scene before running the transition animation and the {@link 205 android.transition.Scene#setEnterAction setEnterAction()} method on the ending scene after 206 running the transition animation.</p> 207 208 <p class="note"><strong>Note:</strong> Do not use scene actions to pass data between views in 209 the starting and ending scenes. For more information, see 210 <a href="{@docRoot}training/transitions/transitions.html#Callbacks">Defining Transition 211 Lifecycle Callbacks</a>.</p> 212
