Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "cherry pick from hc mr1 Change-Id: Icd86c888b061e7b6770363443fea490c49b7739e" into honeycomb-mr2

Browse Source
This commit is contained in:
Robert Ly
2011-06-14 14:58:32 -07:00
committed by Android (Google) Code Review
parent a91d655291 4d1824206b
commit cbd31aec9f
2 changed files with 347 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
docs/html/guide/topics/graphics/animation.jd
View File

@@ -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
@@ -108,6 +114,7 @@ parent.link=index.html
default is set to refresh every 10 ms, but the speed in which your application can refresh frames is
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>
@@ -894,99 +901,5 @@ resources.</p>
<li>{@link android.animation.AnimatorSet} - <code>&lt;set&gt;</code></li>
</ul>
<p>Both <code>&lt;animator&gt;</code> ({@link android.animation.ValueAnimator}) and
<code>&lt;objectAnimator&gt;</code> ({@link android.animation.ObjectAnimator}) have the following
attributes:</p>
<p>See <a href="{@docRoot}guide/topics/resources/animation-resource.html#Property">Animation Resources</a>
<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>
<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>&lt;objectAnimator&gt;</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>&lt;objectAnimator&gt;</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>&lt;set&gt;</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>&lt;set&gt;</code> elements to further group animations together.
The
animations that you want to group together should be children of the <code>&lt;set&gt;</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>
&lt;set android:ordering="sequentially"&gt;
&lt;set&gt;
&lt;objectAnimator
android:propertyName="x"
android:duration="500"
android:valueTo="400"
android:valueType="int"/&gt;
&lt;objectAnimator
android:propertyName="y"
android:duration="500"
android:valueTo="300"
android:valueType="int"/&gt;
&lt;/set&gt;
&lt;objectAnimator
android:propertyName="alpha"
android:duration="500"
android:valueTo="0f"/&gt;
&lt;/set&gt;
</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>

373
docs/html/guide/topics/resources/animation-resource.jd
View File

@@ -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>
<h2 id="Tween">Tween Animation</h2>
<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">
&lt;<a href="#animator-set-element">set</a>
android:ordering=["together" | "sequentially"]&gt;
&lt;<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"]/&gt;
&lt;<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"]/&gt;
&lt;<a href="#animator-set-element">set</a>&gt;
...
&lt;/set&gt;
&lt;/set&gt;
</pre>
<p>The file must have a single root element: either
<code>&lt;set&gt;</code>, <code>&lt;objectAnimator&gt;</code>, or <code>&lt;valueAnimator&gt;</code>. You can
group animation elements together inside the <code>&lt;set&gt;</code> element, including other
<code>&lt;set&gt;</code> elements.
</p>
</dd>
<dt>elements:</dt>
<dd>
<dl class="tag-list">
<dt id="animator-set-element"><code>&lt;set&gt;</code></dt>
<dd>A container that holds other animation elements (<code>&lt;objectAnimator&gt;</code>,
<code>&lt;valueAnimator&gt;</code>, or other <code>&lt;set&gt;</code> elements). Represents
an {@link android.animation.AnimatorSet}.
<p>You can specify nested <code>&lt;set&gt;</code> tags to further
group animations together. Each <code>&lt;set&gt;</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>&lt;objectAnimator&gt;</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>&lt;animator&gt;</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>
&lt;set android:ordering="sequentially"&gt;
&lt;set&gt;
&lt;objectAnimator
android:propertyName="x"
android:duration="500"
android:valueTo="400"
android:valueType="intType"/&gt;
&lt;objectAnimator
android:propertyName="y"
android:duration="500"
android:valueTo="300"
android:valueType="intType"/&gt;
&lt;/set&gt;
&lt;objectAnimator
android:propertyName="alpha"
android:duration="500"
android:valueTo="1f"/&gt;
&lt;/set&gt;
</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>
</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>