diff options
Diffstat (limited to 'docs/html/training/transitions')
| -rw-r--r-- | docs/html/training/transitions/custom-transitions.jd | 189 | ||||
| -rw-r--r-- | docs/html/training/transitions/index.jd | 80 | ||||
| -rw-r--r-- | docs/html/training/transitions/overview.jd | 165 | ||||
| -rw-r--r-- | docs/html/training/transitions/scenes.jd | 211 | ||||
| -rw-r--r-- | docs/html/training/transitions/transitions.jd | 315 |
5 files changed, 960 insertions, 0 deletions
diff --git a/docs/html/training/transitions/custom-transitions.jd b/docs/html/training/transitions/custom-transitions.jd new file mode 100644 index 0000000..b64daae --- /dev/null +++ b/docs/html/training/transitions/custom-transitions.jd @@ -0,0 +1,189 @@ +page.title=Creating Custom Transitions + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#Extend">Extend the Transition Class</a></li> + <li><a href="#CaptureProperties">Capture View Property Values</a></li> + <li><a href="#CreateAnimator">Create a Custom Animator</a></li> + <li><a href="#Apply">Apply a Custom Transition</a></li> +</ol> +</div> +</div> + +<p>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.</p> + +<p>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.</p> + +<p>This lesson teaches you to capture property values and generate animations to create +custom transitions.</p> + + + +<h2 id="Extend">Extend the Transition Class</h2> + +<p>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:</p> + +<pre> +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) {} +} +</pre> + +<p>The following sections explain how to override these methods.</p> + + + +<h2 id="CaptureProperties">Capture View Property Values</h2> + +<p>Transition animations use the property animation system described in +<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>. 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.</p> + +<p>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.</p> + + +<h3 id="StartingValues">Capturing Starting Values</h3> + +<p>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.</p> + +<p>To ensure that the key for a property value does not conflict with other {@link +android.transition.TransitionValues} keys, use the following naming scheme:</p> + +<pre> +package_name:transition_name:property_name +</pre> + +<p>The following snippet shows an implementation of the {@link +android.transition.Transition#captureStartValues captureStartValues()} method:</p> + +<pre> +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()); + } + ... +} +</pre> + + +<h3 id="EndingValues">Capture Ending Values</h3> + +<p>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()}.</p> + +<p>The following code snippet shows an implementation of the {@link +android.transition.Transition#captureEndValues captureEndValues()} method:</p> + +<pre> +@Override +public void captureEndValues(TransitionValues transitionValues) { + captureValues(transitionValues); +} +</pre> + +<p>In this example, both the {@link android.transition.Transition#captureStartValues +captureStartValues()} and {@link android.transition.Transition#captureEndValues captureEndValues()} +methods invoke <code>captureValues()</code> to retrieve and store values. The view property +that <code>captureValues()</code> 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.</p> + + + +<h2 id="CreateAnimator">Create a Custom Animator</h2> + +<p>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.</p> + +<p>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.</p> + +<p>For target views that exist on both the starting and ending scenes, the framework provides +a {@link android.transition.TransitionValues} object for both the <code>startValues</code> and +<code>endValues</code> 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 <code>null</code> for the other.</p> + +<p>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 <a +href="{@docRoot}samples/CustomTransition/src/com.example.android.customtransition/ChangeColor.html"> +<code>ChangeColor</code></a> class in the <a href="{@docRoot}samples/CustomTransition/index.html"> +CustomTransition</a> sample. For more information about property animators, see +<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a>.</p> + + + +<h2 id="Apply">Apply a Custom Transition</h2> + +<p>Custom transitions work the same as built-in transitions. You can apply a custom transition +using a transition manager, as described in <a +href="{@docRoot}training/transitions/transitions.html#Apply">Applying a Transition</a>.</p> diff --git a/docs/html/training/transitions/index.jd b/docs/html/training/transitions/index.jd new file mode 100644 index 0000000..53faa01 --- /dev/null +++ b/docs/html/training/transitions/index.jd @@ -0,0 +1,80 @@ +page.title=Animating Views Using Scenes and Transitions + +@jd:body + +<!-- Sidebox --> +<div id="tb-wrapper"> +<div id="tb"> + <h2>Dependencies and Prerequisites</h2> + <ul> + <li>Android 4.4.2 (API level 19) or higher</li> + </ul> + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}guide/topics/ui/how-android-draws.html"> + How Android Draws Views</a></li> + </ul> + <h2>Try it out</h2> + <ul> + <li><a href="{@docRoot}samples/BasicTransition/index.html">BasicTransition</a> sample</li> + <li><a href="{@docRoot}samples/CustomTransition/index.html">CustomTransition</a> sample</li> + </ul> +</div> +</div> + +<!-- Video box --> +<a class="notice-developers-video wide" href="http://www.youtube.com/watch?v=S3H7nJ4QaD8"> +<div> + <h3>Video</h3> + <p>DevBytes: Android 4.4 Transitions</p> +</div> +</a> + +<p>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.</p> + +<p>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.</p> + +<p>Android includes the <em>transitions framework</em>, 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.</p> + +<p>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.</p> + +<p class="note"><strong>Note:</strong> 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 <code>animateLayoutChanges</code> +attribute to animate layouts. To learn more, see +<a href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> and +<a href="{@docRoot}training/animation/layout.html">Animating Layout Changes</a>.</p> + + +<h2>Lessons</h2> + +<dl> +<dt><a href="{@docRoot}training/transitions/overview.html"> +The Transitions Framework</a></dt> +<dd> + Learn the main features and components of the transitions framework. +</dd> +<dt><a href="{@docRoot}training/transitions/scenes.html"> +Creating a Scene</a></dt> +<dd> + Learn how to create a scene to store the state of a view hierarchy. +</dd> +<dt><a href="{@docRoot}training/transitions/transitions.html"> +Applying a Transition</a></dt> +<dd> + Learn how to apply a transition between two scenes of a view hierarchy. +</dd> +<dt><a href="{@docRoot}training/transitions/custom-transitions.html"> +Creating Custom Transitions</a></dt> +<dd> + Learn how to create other animation effects not included in the transitions framework. +</dd> +</dl> diff --git a/docs/html/training/transitions/overview.jd b/docs/html/training/transitions/overview.jd new file mode 100644 index 0000000..044cf16 --- /dev/null +++ b/docs/html/training/transitions/overview.jd @@ -0,0 +1,165 @@ +page.title=The Transitions Framework + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson covers</h2> +<ol> + <li><a href="#Overview">Overview</a></li> + <li><a href="#Scenes">Scenes</a></li> + <li><a href="#Transitions">Transitions</a></li> + <li><a href="#Limitations">Limitations</a></li> +</ol> +</div> +</div> + +<p>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.</p> + +<p>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.</p> + +<p>The framework has the following features:</p> + +<dl> +<dt><em>Group-level animations</em></dt> +<dd>Applies one or more animation effects to all of the views in a view hierarchy.</dd> +<dt><em>Transition-based animation</em></dt> +<dd>Runs animations based on the changes between starting and ending view property values.</dd> +<dt><em>Built-in animations</em></dt> +<dd>Includes predefined animations for common effects such as fade out or movement.</dd> + +<!-- Figure 1 - Transitions video --> +<div style="float:right;margin-left:30px;margin-top:10px"> +<div class="framed-nexus5-port-span-5" style="clear:left;"> +<video class="play-on-hover" height="442" autoplay="" poster=""> +<source src="{@docRoot}images/transitions/transition_sample_video.mp4" type="video/mp4"> +<source src="{@docRoot}images/transitions/transition_sample_video.ogv" type="video/ogg"> +<source src="{@docRoot}images/transitions/transition_sample_video.webm" type="video/webm"> +</video> +</div> +<p class="img-caption" style="margin-top:7px;margin-bottom:0px"> +<strong>Figure 1.</strong> Visual cues using user interface animation.</p> +<div style="margin-top:5px;margin-bottom:20px;font-size:10pt" class="video-instructions"> </div> +</div> + +<dt><em>Resource file support</em></dt> +<dd>Loads view hierarchies and built-in animations from layout resource files.</dd> +<dt><em>Lifecycle callbacks</em></dt> +<dd>Defines callbacks that provide finer control over the animation and hierarchy change +process.</dd> +</dl> + + + +<h2 id="Overview">Overview</h2> + +<p>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.</p> + +<p>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 <em>starting</em> view hierarchy and the final or <em>ending</em> +view hierarchy.</p> + +<p>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.</p> + +<p>The diagram in Figure 2 illustrates the relationship between view hierarchies, framework +objects, and animations:</p> + +<!-- Figure 2 - diagram --> +<img src="{@docRoot}images/transitions/transitions_diagram.png" + width="506" height="234" alt="" style="margin-top:7px" /> +<p class="img-caption"><strong>Figure 2.</strong> Relationships in the transitions framework.</p> + +<p>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.</p> + + + +<h2 id="Scenes">Scenes</h2> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>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 <strong>scene root</strong>. +Changes to the scene and animations that affect the scene occur within the scene root.</p> + +<p>To learn how to create scenes, see +<a href="{@docRoot}training/transitions/scenes.html">Creating a Scene</a>.</p> + + + +<h2 id="Transitions">Transitions</h2> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>To learn more about transitions, see +<a href="{@docRoot}training/transitions/transitions.html">Applying a Transition</a> and +<a href="{@docRoot}training/transitions/custom-transitions.html">Creating Custom +Transitions</a>.</p> + + + +<h2 id="Limitations">Limitations</h2> + +<p>This section lists some known limitations of the transitions framework:</p> + +<ul> +<li>Animations applied to a {@link android.view.SurfaceView} may not appear correctly. +{@link android.view.SurfaceView} instances are updated from a non-UI thread, so the updates +may be out of sync with the animations of other views.</li> +<li>Some specific transition types may not produce the desired animation effect when applied +to a {@link android.view.TextureView}.</li> +<li>Classes that extend {@link android.widget.AdapterView}, such as +{@link android.widget.ListView}, manage their child views in ways that are incompatible with +the transitions framework. If you try to animate a view based on +{@link android.widget.AdapterView}, the device display may hang.</li> +<li>If you try to resize a {@link android.widget.TextView} with an animation, the text will +pop to a new location before the object has completely resized. To avoid this problem, do not +animate the resizing of views that contain text.</li> +</ul> diff --git a/docs/html/training/transitions/scenes.jd b/docs/html/training/transitions/scenes.jd new file mode 100644 index 0000000..4bf7d0e --- /dev/null +++ b/docs/html/training/transitions/scenes.jd @@ -0,0 +1,211 @@ +page.title=Creating a Scene + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#FromLayout">Create a Scene From a Layout Resource</a></li> + <li><a href="#FromCode">Create a Scene in Your Code</a></li> + <li><a href="#Actions">Create Scene Actions</a></li> +</ol> +</div> +</div> + +<p>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.</p> + +<p>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.</p> + +<p class="note"><strong>Note:</strong> The framework can animate changes in a single view +hierarchy without using scenes, as described in +<a href="{@docRoot}training/transitions/transitions.html#NoScenes">Apply a Transition Without +Scenes</a>. However, understanding this lesson is essential to work with transitions.</p> + + + +<h2 id="FromLayout">Create a Scene From a Layout Resource</h2> + +<p>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.</p> + +<p>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.</p> + +<h3>Define Layouts for Scenes</h3> + +<p>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.</p> + +<p>The example consists of the following layout definitions:</p> + +<ul> +<li>The main layout of an activity with a text label and a child layout.</li> +<li>A relative layout for the first scene with two text fields.</li> +<li>A relative layout for the second scene with the same two text fields in different order.</li> +</ul> + +<p>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.</p> + +<p>The main layout for the activity is defined as follows:</p> + +<p class="code-caption">res/layout/activity_main.xml</p> + +<pre> +<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> +</pre> + +<p>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.</p> + +<p>The layout for the first scene is defined as follows:</p> + +<p class="code-caption">res/layout/a_scene.xml</p> + +<pre> +<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> +</pre> + +<p>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:</p> + +<p class="code-caption">res/layout/another_scene.xml</p> + +<pre> +<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> +</pre> + +<h3>Generate Scenes from Layouts</h3> + +<p>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.</p> + +<p>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:</p> + +<pre> +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); +</pre> + +<p>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 <code>res/layout/activity_main.xml</code>.</p> + + + +<h2 id="FromCode">Create a Scene in Your Code</h2> + +<p>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.</p> + +<p>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.</p> + +<p>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:</p> + +<pre> +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); +</pre> + + + +<h2 id="Actions">Create Scene Actions</h2> + +<p>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.</p> + +<p>Scene actions are useful for handling these cases:</p> + +<ul> +<li>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.</li> +<li>Animate views that the transitions framework cannot animate automatically, such as +{@link android.widget.ListView} objects. For more information, see +<a href="{@docRoot}training/transitions/overview.html#Limitations">Limitations</a>.</li> +</ul> + +<p>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.</p> + +<p class="note"><strong>Note:</strong> Do not use scene actions to pass data between views in +the starting and ending scenes. For more information, see +<a href="{@docRoot}training/transitions/transitions.html#Callbacks">Defining Transition +Lifecycle Callbacks</a>.</p> diff --git a/docs/html/training/transitions/transitions.jd b/docs/html/training/transitions/transitions.jd new file mode 100644 index 0000000..489e291 --- /dev/null +++ b/docs/html/training/transitions/transitions.jd @@ -0,0 +1,315 @@ +page.title=Applying a Transition + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#Create">Create a Transition</a></li> + <li><a href="#Apply">Apply a Transition</a></li> + <li><a href="#Targets">Choose Specific Target Views</a></li> + <li><a href="#Multiple">Specify Multiple Transitions</a></li> + <li><a href="#NoScenes">Apply a Transition Without Scenes</a></li> + <li><a href="#Callbacks">Define Transition Lifecycle Callbacks</a></li> +</ol> +</div> +</div> + +<p>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.</p> + +<p>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.</p> + + + +<h2 id="Create">Create a Transition</h2> + +<p>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.</p> + +<!-- Built in transition table --> +<p class="table-caption" id="table1"><strong>Table 1.</strong> Built-in transition types.</p> +<table> +<tr> + <th scope="col">Class</th> + <th scope="col">Tag</th> + <th scope="col">Attributes</th> + <th scope="col">Effect</th> +</tr> +<tr> + <td><code><a href="/reference/android/transition/AutoTransition.html">AutoTransition</a></code></td> + <td><autoTransition/></td> + <td style="text-align=center;"> - </td> + <td>Default transition. Fade out, move and resize, and fade in views, in that order.</td> +</tr> +<tr> + <td><code><a href="/reference/android/transition/Fade.html">Fade</a></code></td> + <td><fade/></td> + <td><code>android:fadingMode="[fade_in |<br> fade_out |<br> fade_in_out]"</code></td> + <td> + <code>fade_in</code> fades in views<br> + <code>fade_out</code> fades out views<br> + <code>fade_in_out</code> (default) does a <code>fade_out</code> followed by a <code>fade_in</code>. + </td> +</tr> +<tr> + <td><code><a href="/reference/android/transition/ChangeBounds.html">ChangeBounds</a></code></td> + <td><changeBounds/></td> + <td style="text-align=center;"> - </td> + <td>Moves and resizes views.</td> +</tr> +</table> + + +<h3 id="FromFile">Create a transition instance from a resource file</h3> + +<p>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 <a href="#Multiple">Specify Multiple +Transitions</a>.</p> + +<p>To specify a built-in transition in a resource file, follow these steps:</p> + +<ol> +<li>Add the <code>res/transition/</code> directory to your project.</li> +<li>Create a new XML resource file inside this directory.</li> +<li>Add an XML node for one of the built-in transitions.</li> +</ol> + +<p>For example, the following resource file specifies the {@link android.transition.Fade} +transition:</p> + +<p class="code-caption">res/transition/fade_transition.xml</p> + +<pre> +<fade xmlns:android="http://schemas.android.com/apk/res/android" /> +</pre> + +<p>The following code snippet shows how to inflate a {@link android.transition.Transition} +instance inside your activity from a resource file:</p> + +<pre> +Transition mFadeTransition = + TransitionInflater.from(this). + inflateTransition(R.transition.fade_transition); +</pre> + + +<h3 id="FromCode">Create a transition instance in your code</h3> + +<p>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.</p> + +<p>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:</p> + +<pre> +Transition mFadeTransition = new Fade(); +</pre> + + + +<h2 id="Apply">Apply a Transition</h2> + +<p>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.</p> + +<p>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:</p> + +<pre> +TransitionManager.go(mEndingScene, mFadeTransition); +</pre> + +<p>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.</p> + +<p>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.</p> + + + +<h2 id="Targets">Choose Specific Target Views</h2> + +<p>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.</p> + +<p>Each view that the transition animates is called a <em>target</em>. You can only +select targets that are part of the view hierarchy associated with a scene.</p> + +<p>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.</p> + + + +<h2 id="Multiple">Specify Multiple Transitions</h2> + +<p>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.</p> + +<p>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.</p> + +<p>To define a transition set from a collection of transitions in XML, create a resource file +in the <code>res/transitions/</code> directory and list the transitions under the +<code>transitionSet</code> 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:</p> + +<pre> +<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> +</pre> + +<p>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.</p> + + + +<h2 id="NoScenes">Apply a Transition Without Scenes</h2> + +<p>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.</p> + +<p>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.</p> + +<p>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 <em>delayed transition</em>. 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.</p> + +<p>To create a delayed transition within a single view hierarchy, follow these steps:</p> + +<ol> +<li>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.</li> +<li>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.</li> +<li>When the system redraws the user interface according to your changes, the framework +animates the changes between the original state and the new state.</li> +</ol> + +<p>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:</p> + +<p class="code-caption">res/layout/activity_main.xml</p> + +<pre> +<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> +</pre> + +<p>The next snippet shows the code that animates the addition of the text view:</p> + +<p class="code-caption">MainActivity.java</p> + +<pre> +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 +</pre> + + + +<h2 id="Callbacks">Define Transition Lifecycle Callbacks</h2> + +<p>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.</p> + +<p>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.</p> + +<p>For more information, see the API reference for the {@link +android.transition.Transition.TransitionListener TransitionListener} class.</p> |