Merge "cherry pick from hc mr1 Change-Id:... (cbd31aec) · Commits · e / os / android_frameworks_base

docs/html/guide/topics/graphics/animation.jd

+8 −95

Original line number	Diff line number	Diff line
		@@ -81,6 +81,12 @@ parent.link=index.html
		If view animation accomplishes everything that you need to do, or if your existing code already
		works the way you want, there is no need to use the property animation system.</p>

		<p class="note"><strong>Tip:</strong> To see how the ADT layout editor allows you to develop and
		preview animations in your layout, watch the <a
		href="http://www.youtube.com/watch?v=Oq05KqjXTvs&feature=player_detailpage#t=1709s">Android
		Developer Tools session</a> from Google I/O '11</p>


		<h2 id="what">What is Property Animation?</h2>
		A property animation changes a property's (a field in
		an object) value over a specified length of time. To animate something, you specify the
		@@ -109,6 +115,7 @@ parent.link=index.html
		ultimately dependent on how busy the system is overall and how fast the system can service the underlying timer.</li>
		</ul>


		<h3 id="how">How the property animation system works</h3>

		<p>First, let's go over how an animation works with a simple example. Figure 1 depicts a
		@@ -894,99 +901,5 @@ resources.</p>
		<li>{@link android.animation.AnimatorSet} - <code><set></code></li>
		</ul>

		<p>Both <code><animator></code> ({@link android.animation.ValueAnimator}) and
		<code><objectAnimator></code> ({@link android.animation.ObjectAnimator}) have the following
		attributes:</p>

		<dl>
		<dt><code>android:duration</code></dt>

		<dd>The number of milliseconds that the animation runs. The default is 300 ms.</dd>

		<dt><code>android:valueFrom</code> and <code>android:valueTo</code></dt>

		<dd>The values being animated between. These are restricted to numbers (<code>float</code> or
		<code>int</code>) and color values (such as #00ff00). They can be <code>float</code>, <code>int</code>, colors,
		or any kind of <code>Object</code> when creating animations programmatically.</dd>

		<dt><code>android:valueType</code></dt>

		<dd>Set to either <code>"floatType"</code> or <code>"intType"</code>. The default is
		<code>"floatType"</code> unless you specify something else or if the <code>valuesFrom</code>
		and <code>valuesTo</code> values are colors.</dd>

		<dt><code>android:startOffset</code></dt>

		<dd>The delay, in milliseconds, before the animation begins playing (after calling {@link
		android.animation.ValueAnimator#start start()}).</dd>
		<p>See <a href="{@docRoot}guide/topics/resources/animation-resource.html#Property">Animation Resources</a>

		<dt><code>android:repeatCount</code></dt>

		<dd>How many times to repeat an animation. Set to <code>"-1"</code> to infinitely repeat or
		to a positive integer. For example, a value of <code>"1"</code> means that the animation is
		repeated once after the initial run of the animation, so the animation plays a total of two
		times. The default value is <code>"0"</code>, which means no repetition.</dd>

		<dt><code>android:repeatMode</code></dt>

		<dd>How an animation behaves when it reaches the end of the animation.
		<code>android:repeatCount</code> must be set to a positive integer or <code>"-1"</code> for
		this attribute to have an effect. Set to <code>"reverse"</code> to have the animation reverse
		direction with each iteration or <code>"repeat"</code> to have the animation loop from the
		beginning each time.</dd>
		</dl>

		<p>The <code><objectAnimator></code> ({@link android.animation.ObjectAnimator}) element has the
		additional attribute <code>android:propertyName</code>, that lets you specify the name of the
		property
		being animated. The <code><objectAnimator></code> element does not expose a <code>target</code>
		attribute, however, so you cannot set the object to animate in the XML declaration. You have to
		inflate the XML resource by calling {@link android.animation.AnimatorInflater#loadAnimator
		loadAnimator()} and call {@link android.animation.ObjectAnimator#setTarget setTarget()} to set
		the target object unlike the underlying {@link android.animation.ObjectAnimator},
		before calling {@link android.animation.ObjectAnimator#start start()}.</p>

		<p>The <code><set></code> element ({@link android.animation.AnimatorSet}) exposes a single
		attribute, <code>android:ordering</code>. Set this attribute to <code>"together"</code> (default)
		to play
		all the animations in this set at once. Set this attribute to <code>"sequentially"</code> to play
		the animations in the order they are declared.</p>

		<p>You can specify nested <code><set></code> elements to further group animations together.
		The
		animations that you want to group together should be children of the <code><set></code> tag and can
		define their own <code>ordering</code> attribute.</p>

		<p>As an example, this XML code creates an {@link android.animation.AnimatorSet} object that
		animates x and y at the same time, then runs an animation that fades an object out:</p>
		<pre>
		<set android:ordering="sequentially">
		<set>
		<objectAnimator
		android:propertyName="x"
		android:duration="500"
		android:valueTo="400"
		android:valueType="int"/>
		<objectAnimator
		android:propertyName="y"
		android:duration="500"
		android:valueTo="300"
		android:valueType="int"/>
		</set>
		<objectAnimator
		android:propertyName="alpha"
		android:duration="500"
		android:valueTo="0f"/>
		</set>
		</pre>

		<p>In order to run this animation, you must inflate the XML resources in your code to an {@link
		android.animation.AnimatorSet} object, and then set the target objects for all of the animations
		before starting the animation set. Calling {@link android.animation.AnimatorSet#setTarget
		setTarget()} sets a single target object for all children of the {@link
		android.animation.AnimatorSet}.</p>

		<p class="note"><strong>Tip:</strong> To see how the ADT layout editor allows you to develop and
		preview animations in your layout, watch the <a
		href="http://www.youtube.com/watch?v=Oq05KqjXTvs&feature=player_detailpage#t=1709s">Android
		Developer Tools session</a> from Google I/O '11</p>

docs/html/guide/topics/resources/animation-resource.jd

+339 −34

Original line number	Diff line number	Diff line
		@@ -5,28 +5,348 @@ parent.link=available-resources.html

		<div id="qv-wrapper">
		<div id="qv">
		<h2>In this document</h2>
		<ol>
		<li><a href="#Property">Property Animation</a></li>
		<li><a href="#View">View Animation</a>
		<ol>
		<li><a href="Tween">Tween animation</li>
		<li><a href="Frame">Frame animation</li>
		</ol>
		</li>
		</ol>
		<h2>See also</h2>
		<ol>
		<li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D
		Graphics</a></li>
		<li><a href="{@docRoot}guide/topics/graphics/view-animation.html">View Animation</a></li>
		<li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li>
		</ol>
		</div>
		</div>


		<p>An animation resource can define one of two types of animations:</p>

		<dl>
		<dt><a href="#Tween">Tween Animation</a></dt>
		<dd>Creates an animation by performing a series of transformations on a single image.
		An {@link android.view.animation.Animation}.</dd>
		<dt><a href="#Frame">Frame Animation</a></dt>
		<dd>Creates an animation by showing a sequence of images in order.
		An {@link android.graphics.drawable.AnimationDrawable}.</dd>
		<dt><a href="#Property">Property Animation</a></dt>
		<dd>Creates an animation by modifying an object's property values over a set period
		of time with an {@link android.animation.Animator}.</dd>
		<dt><a href="#View">View Animation</a></dt>
		<dd>
		<p>There are two types of animations that you can do with the view animation framework:</p>
		<ul>
		<li><a href="#Tween">Tween animation</a>: Creates an animation by performing a series of transformations on a single image
		with an {@link android.view.animation.Animation}</li>
		<li><a href="#Frame">Frame animation</a>: or creates an animation by showing a sequence of images in order
		with an {@link android.graphics.drawable.AnimationDrawable}.</li>
		</ul>
		</dd>
		</dl>


		<h2 id="Property">Property Animation</h2>
		<p>An animation defined in XML that modifies properties of the target object, such as
		background color or alpha value, over a set amount of time.</p>

		<dl class="xml">

		<dt>file location:</dt>
		<dd><code>res/animator/<em>filename</em>.xml</code><br/>
		The filename will be used as the resource ID.</dd>

		<dt>compiled resource datatype:</dt>
		<dd>Resource pointer to a {@link android.animation.ValueAnimator}, {@link android.animation.ObjectAnimator},
		or {@link android.animation.AnimatorSet}.</dd>

		<dt>resource reference:</dt>
		<dd>
		In Java: <code>R.animator.<em>filename</em></code><br/>
		In XML: <code>@[<em>package</em>:]animator/<em>filename</em></code>
		</dd>

		<dt>syntax:</dt>
		<dd>
		<pre class="stx">
		<<a href="#animator-set-element">set</a>
		android:ordering=["together" \| "sequentially"]>

		<<a href="#obj-animator-element">objectAnimator</a>
		android:propertyName="<em>string</em>"
		android:duration="<em>int</em>"
		android:valueFrom="<em>float</em> \| <em>int</em> \| <em>color</em>"
		android:valueTo="<em>float</em> \| <em>int</em> \| <em>color</em>"
		android:startOffset="<em>int</em>"
		android:repeatCount="<em>int</em>"
		android:repeatMode=["repeat" \| "reverse"]
		android:valueType=["intType" \| "floatType"]/>

		<<a href="#val-animator-element">animator</a>
		android:duration="<em>int</em>"
		android:valueFrom="<em>float</em> \| <em>int</em> \| <em>color</em>"
		android:valueTo="<em>float</em> \| <em>int</em> \| <em>color</em>"
		android:startOffset="<em>int</em>"
		android:repeatCount="<em>int</em>"
		android:repeatMode=["repeat" \| "reverse"]
		android:valueType=["intType" \| "floatType"]/>

		<<a href="#animator-set-element">set</a>>
		...
		</set>
		</set>
		</pre>

		<p>The file must have a single root element: either
		<code><set></code>, <code><objectAnimator></code>, or <code><valueAnimator></code>. You can
		group animation elements together inside the <code><set></code> element, including other
		<code><set></code> elements.
		</p>
		</dd>

		<dt>elements:</dt>
		<dd>
		<dl class="tag-list">
		<dt id="animator-set-element"><code><set></code></dt>
		<dd>A container that holds other animation elements (<code><objectAnimator></code>,
		<code><valueAnimator></code>, or other <code><set></code> elements). Represents
		an {@link android.animation.AnimatorSet}.
		<p>You can specify nested <code><set></code> tags to further
		group animations together. Each <code><set></code> can define its own
		<code>ordering</code> attribute.</p>

		<p class="caps">attributes:</p>
		<dl class="atn-list">
		<dt>
		<code>android:ordering</code>
		</dt>
		<dd>
		<em>Keyword</em>. Specifies the play ordering of animations in this set.
		<table>
		<tr><th>Value</th><th>Description</th></tr>
		<tr><td><code>sequentially</code></td><td>Play animations in this set sequentially</td></tr>
		<tr><td><code>together</code> (default)</td><td>Play animations in this set at the same time.</td></tr>
		</table>
		</dd>
		</dl>
		</dd>

		<dt id="obj-animator-element"><code><objectAnimator></code></dt>
		<dd>Animates a specific property of an object over a specific amount of time. Represents
		an {@link android.animation.ObjectAnimator}.</p>

		<p class="caps">attributes:</p>
		<dl class="atn-list">
		<dt>
		<code>android:propertyName</code>
		</dt>
		<dd>
		<em>String</em>. <strong>Required</strong>. The object's property to animate, referenced by its name. For example you can specify
		<code>"alpha"</code> or <code>"backgroundColor"</code> for a View object.
		The <code>objectAnimator</code> element does not expose a <code>target</code>
		attribute, however, so you cannot set the object to animate in the XML declaration. You have to
		inflate your animation XML resource by calling {@link android.animation.AnimatorInflater#loadAnimator
		loadAnimator()} and call {@link android.animation.ObjectAnimator#setTarget setTarget()} to set
		the target object that contains this property.
		</dd>

		<dt>
		<code>android:valueTo</code>
		</dt>
		<dd>
		<em>float, int, or color</em>. <strong>Required</strong>. The value where the animated property ends. Colors are represented
		as six digit hexadecimal numbers (for example, #333333).
		</dd>

		<dt>
		<code>android:valueFrom</code>
		</dt>
		<dd>
		<em>float, int, or color</em>. The value where the animated property starts. If not
		specified, the animation starts at the value obtained by the property's get method. Colors are represented
		as six digit hexadecimal numbers (for example, #333333).
		</dd>

		<dt>
		<code>android:duration</code>
		</dt>
		<dd>
		<em>int</em>. The time in milliseconds of the animation. 300 milliseconds is the default.
		</dd>

		<dt>
		<code>android:startOffset</code>
		</dt>
		<dd>
		<em>int</em>. The amount of milliseconds the animation delays after
		{@link android.animation.ObjectAnimator#start start()} is called.
		</dd>

		<dt>
		<code>android:repeatCount</code>
		</dt>
		<dd>
		<em>int</em>. How many times to repeat an animation. Set to <code>"-1"</code> to infinitely
		repeat or to a positive integer. For example, a value of <code>"1"</code> means that the animation
		is repeated once after the initial run of the animation, so the animation plays a total
		of two times. The default value is <code>"0"</code>, which means no repetition.

		</dd>

		<dt>
		<code>android:repeatMode</code>
		</dt>
		<dd>
		<em>int</em>. How an animation behaves when it reaches the end of the animation. <code>android:repeatCount</code>
		must be set to a positive integer or <code>"-1"</code> for this attribute to have an effect. Set to <code>"reverse"</code>
		to have the animation reverse direction with each iteration or <code>"repeat"</code> to have the animation
		loop from the beginning each time.
		</dd>

		<dt>
		<code>android:valueType</code>
		</dt>
		<dd>
		<em>Keyword</em>. Do not specify this attribute if the value is a color. The animation framework automatically handles color
		values
		<table>
		<tr><th>Value</th><th>Description</th></tr>
		<tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr>
		<tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr>
		</table>
		</dd>

		</dl>
		</dd>

		<dt id="val-animator-element"><code><animator></code></dt>
		<dd>Animates a over a specified amount of time.
		Represents a {@link android.animation.ValueAnimator}.

		<p class="caps">attributes:</p>
		<dl class="atn-list">
		<dt>
		<code>android:valueTo</code>
		</dt>
		<dd>
		<em>float, int, or color</em>. <strong>Required</strong>. The value where the animation ends. Colors are represented
		as six digit hexadecimal numbers (for example, #333333).
		</dd>

		<dt>
		<code>android:valueFrom</code>
		</dt>
		<dd>
		<em>float, int, or color</em>. <strong>Required</strong>. The value where the animation starts. Colors are represented
		as six digit hexadecimal numbers (for example, #333333).
		</dd>

		<dt>
		<code>android:duration</code>
		</dt>
		<dd>
		<em>int</em>. The time in milliseconds of the animation. 300ms is the default.
		</dd>

		<dt>
		<code>android:startOffset</code>
		</dt>
		<dd>
		<em>int</em>. The amount of milliseconds the animation delays after
		{@link android.animation.ValueAnimator#start start()} is called.
		</dd>

		<dt>
		<code>android:repeatCount</code>
		</dt>
		<dd>
		<em>int</em>. How many times to repeat an animation. Set to <code>"-1"</code> to infinitely
		repeat or to a positive integer. For example, a value of <code>"1"</code> means that the animation
		is repeated once after the initial run of the animation, so the animation plays a total
		of two times. The default value is <code>"0"</code>, which means no repetition.
		</dd>

		<dt>
		<code>android:repeatMode</code>
		</dt>
		<dd>
		<em>int</em>. How an animation behaves when it reaches the end of the animation. <code>android:repeatCount</code>
		must be set to a positive integer or <code>"-1"</code> for this attribute to have an effect. Set to <code>"reverse"</code>
		to have the animation reverse direction with each iteration or <code>"repeat"</code> to have the animation
		loop from the beginning each time.
		</dd>

		<dt>
		<code>android:valueType</code>
		</dt>
		<dd>
		<em>Keyword</em>. Do not specify this attribute if the value is a color. The animation framework automatically handles color
		values.
		<table>
		<tr><th>Value</th><th>Description</th></tr>
		<tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr>
		<tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr>
		</table>
		</dd>

		</dl>
		</dd>
		</dl>

		</dd> <!-- end elements and attributes -->

		<dt>example:</dt>
		<dd>
		<pp>XML file saved at <code>res/animator/property_animator.xml</code>:</p>
		<pre>
		<set android:ordering="sequentially">
		<set>
		<objectAnimator
		android:propertyName="x"
		android:duration="500"
		android:valueTo="400"
		android:valueType="intType"/>
		<objectAnimator
		android:propertyName="y"
		android:duration="500"
		android:valueTo="300"
		android:valueType="intType"/>
		</set>
		<objectAnimator
		android:propertyName="alpha"
		android:duration="500"
		android:valueTo="1f"/>
		</set>
		</pre>
		<p>In order to run this animation, you must inflate the XML resources in your code to an {@link
		android.animation.AnimatorSet} object, and then set the target objects for all of the animations
		before starting the animation set. Calling {@link android.animation.AnimatorSet#setTarget
		setTarget()} sets a single target object for all children of the {@link
		android.animation.AnimatorSet} as a convenience. The following code shows how to do this:</p>

		<pre>
		AnimatorSet set = (AnimatorSet) AnimatorInflater.loadAnimator(myContext,
		R.anim.property_animator);
		set.setTarget(myObject);
		set.start();
		</pre>

		<h2 id="Tween">Tween Animation</h2>

		</dd> <!-- end example -->

		<dt>see also:</dt>
		<dd>
		<ul>
		<li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li>
		<li><a href="http://zoso:8080/resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples
		on how to use the property animation system.</li>
		</ul>
		</dd>

		</dl>

		<h2 id="View">View Animation</h2>
		The view animation framework supports both tween and frame by frame animations, which can both be declared
		in XML. The following sections describe how to use both methods.

		<h3 id="Tween">Tween animation</h3>

		<p>An animation defined in XML that performs transitions such as rotating,
		fading, moving, and stretching on a graphic.
		@@ -254,18 +574,14 @@ image.{@link android.view.View#startAnimation(Animation) startAnimation}(hypersp
		<dt>see also:</dt>
		<dd>
		<ul>
		<li><a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D
		<li><a href="{@docRoot}guide/topics/graphics/view-animation.html#tween-animation">2D
		Graphics: Tween Animation</a></li>
		</ul>
		</dd>

		</dl>





		<h3 id="Interpolators">Interpolators</h3>
		<h4 id="Interpolators">Interpolators</h4>

		<p>An interpolator is an animation modifier defined in XML that affects the rate of change in an
		animation. This allows your existing animation effects to be accelerated, decelerated, repeated,
		@@ -456,22 +772,7 @@ sinusoidal pattern.
		</dl>

















		<h2 id="Frame">Frame Animation</h2>
		<h3 id="Frame">Frame animation</h3>

		<p>An animation defined in XML that shows a sequence of images in order (like a film).
		</p>
		@@ -562,7 +863,11 @@ rocketAnimation.{@link android.graphics.drawable.AnimationDrawable#start()};
		</dl>
		</dd> <!-- end example -->

		<dt>see also:</dt>
		<dd>
		<ul>
		<li><a href="{@docRoot}guide/topics/graphics/view-animation.html#frame-animation">2D
		Graphics: Frame Animation</a></li>
		</ul>
		</dd>
		</dl>