Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 4c433225 authored by Robert Ly's avatar Robert Ly Committed by Android (Google) Code Review
Browse files

Merge "Doc change: animation devguide topic" into honeycomb

parents ada2592b f99b782b

core/java/android/animation/package.html

+17 −2
Original line number Diff line number Diff line 
<html>

<body>

Provides classes for animating values over time, and setting those values on target

objects.

<p>

These classes provide functionality for the property animation system, which allows you 

to animate object properties of any type. <code>int</code>, <code>float</code>, and hexadecimal

color values are supported by default. You can animate any other type by telling the system how

to calculate the values for that given type with a custom {@link android.animation.TypeEvaluator}.

</p>



<p>

You can set many different types of interpolators (contained in {@link android.view.animation}),

specify {@link android.animation.Keyframe keyframes}, or group animations to play sequentially

or simultaneously (with {@link android.animation.AnimatorSet}) to further control your animation

behaviors.</p>



<p>

For a guide on how to use the property animation system, see the

<a href="{@docRoot}guide/topics/media/index.html">Animation</a> developer guide.

</p>

</body>

</html>

docs/html/guide/guide_toc.cs

+3 −0
Original line number Diff line number Diff line
@@ -213,6 +213,9 @@ 
          <li><a href="<?cs var:toroot ?>guide/topics/graphics/opengl.html">

                <span class="en">3D with OpenGL</span>

              </a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/graphics/animation.html">

                <span class="en">Animation</span>

              </a><span class="new">new!</span></li>

        </ul>

      </li>

      <li><a href="<?cs var:toroot ?>guide/topics/media/index.html">

docs/html/guide/topics/graphics/2d-graphics.jd

+1 −171
Original line number Diff line number Diff line
@@ -17,8 +17,6 @@ parent.link=index.html 
      <li><a href="#shape-drawable">Shape Drawable</a></li>

   <!--   <li><a href="#state-list">StateListDrawable</a></li> -->

      <li><a href="#nine-patch">Nine-patch</a></li>

      <li><a href="#tween-animation">Tween Animation</a></li>

      <li><a href="#frame-animation">Frame Animation</a></li>

    </ol>

  </div>

</div>
@@ -329,171 +327,3 @@ stretches to accommodate it. 
</p>



<img src="{@docRoot}images/ninepatch_examples.png" alt=""/>
 
 No newline at end of file
 




<h2 id="tween-animation">Tween Animation</h2>



<p>A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on

the contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text. 

If it has a background image, the background image will be transformed along with the text.

The {@link android.view.animation animation package} provides all the classes used in a tween animation.</p>



<p>A sequence of animation instructions defines the tween animation, defined by either XML or Android code.

Like defining a layout, an XML file is recommended because it's more readable, reusable, and swappable 

than hard-coding the animation. In the example below, we use XML. (To learn more about defining an animation 

in your application code, instead of XML, refer to the 

{@link android.view.animation.AnimationSet} class and other {@link android.view.animation.Animation} subclasses.)</p>



<p>The animation instructions define the transformations that you want to occur, when they will occur, 

and how long they should take to apply. Transformations can be sequential or simultaneous &mdash;

for example, you can have the contents of a TextView move from left to right, and then 

rotate 180 degrees, or you can have the text move and rotate simultaneously. Each transformation 

takes a set of parameters specific for that transformation (starting size and ending size

for size change, starting angle and ending angle for rotation, and so on), and

also a set of common parameters (for instance, start time and duration). To make

several transformations happen simultaneously, give them the same start time;

to make them sequential, calculate the start time plus the duration of the preceding transformation.

</p>



<p>The animation XML file belongs in the <code>res/anim/</code> directory of your Android project.

The file must have a single root element: this will be either a single <code>&lt;alpha&gt;</code>,

<code>&lt;scale&gt;</code>, <code>&lt;translate&gt;</code>, <code>&lt;rotate&gt;</code>, interpolator element, 

or <code>&lt;set&gt;</code> element that holds groups of these elements (which may include another

<code>&lt;set&gt;</code>). By default, all animation instructions are applied simultaneously. 

To make them occur sequentially, you must specify the <code>startOffset</code> attribute, as shown in the example below.

</p>



<p>The following XML from one of the ApiDemos is used to stretch, 

then simultaneously spin and rotate a View object.

</p>

<pre>

&lt;set android:shareInterpolator="false"&gt;

   &lt;scale

          android:interpolator="&#64;android:anim/accelerate_decelerate_interpolator"

          android:fromXScale="1.0"

          android:toXScale="1.4"

          android:fromYScale="1.0"

          android:toYScale="0.6"

          android:pivotX="50%"

          android:pivotY="50%"

          android:fillAfter="false"

          android:duration="700" /&gt;

   &lt;set android:interpolator="&#64;android:anim/decelerate_interpolator"&gt;

      &lt;scale

             android:fromXScale="1.4" 

             android:toXScale="0.0"

             android:fromYScale="0.6"

             android:toYScale="0.0" 

             android:pivotX="50%" 

             android:pivotY="50%" 

             android:startOffset="700"

             android:duration="400" 

             android:fillBefore="false" /&gt;

      &lt;rotate 

             android:fromDegrees="0" 

             android:toDegrees="-45"

             android:toYScale="0.0" 

             android:pivotX="50%" 

             android:pivotY="50%"

             android:startOffset="700"

             android:duration="400" /&gt;

   &lt;/set&gt;

&lt;/set&gt;

</pre>

<p>Screen coordinates (not used in this example) are (0,0) at the upper left hand corner, 

and increase as you go down and to the right.</p>



<p>Some values, such as pivotX, can be specified relative to the object itself or relative to the parent. 

Be sure to use the proper format for what you want ("50" for 50% relative to the parent, or "50%" for 50% 

relative to itself).</p>



<p>You can determine how a transformation is applied over time by assigning an 

{@link android.view.animation.Interpolator}. Android includes 

several Interpolator subclasses that specify various speed curves: for instance, 

{@link android.view.animation.AccelerateInterpolator} tells 

a transformation to start slow and speed up. Each one has an attribute value that can be applied in the XML.</p>



<p>With this XML saved as <code>hyperspace_jump.xml</code> in the <code>res/anim/</code> directory of the

project, the following Java code will reference it and apply it to an {@link android.widget.ImageView} object

from the layout.

</p>

<pre>

ImageView spaceshipImage = (ImageView) findViewById(R.id.spaceshipImage);

Animation hyperspaceJumpAnimation = AnimationUtils.loadAnimation(this, R.anim.hyperspace_jump);

spaceshipImage.startAnimation(hyperspaceJumpAnimation);

</pre>



<p>As an alternative to <code>startAnimation()</code>, you can define a starting time for the animation with

<code>{@link android.view.animation.Animation#setStartTime(long) Animation.setStartTime()}</code>, 

then assign the animation to the View with

<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>.

</p>



<p>For more information on the XML syntax, available tags and attributes, see <a

href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>



<p class="note"><strong>Note:</strong> Regardless of how your animation may move or resize, the bounds of the 

View that holds your animation will not automatically adjust to accommodate it. Even so, the animation will still

be drawn beyond the bounds of its View and will not be clipped. However, clipping <em>will occur</em>

if the animation exceeds the bounds of the parent View.</p>





<h2 id="frame-animation">Frame Animation</h2>



<p>This is a traditional animation in the sense that it is created with a sequence of different

images, played in order, like a roll of film. The {@link android.graphics.drawable.AnimationDrawable}

class is the basis for frame animations.</p>



<p>While you can define the frames of an animation in your code, using the 

{@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML 

file that lists the frames that compose the animation. Like the tween animation above, the XML file for this kind 

of animation belongs in the <code>res/drawable/</code> directory of your Android project. In this case,

the instructions are the order and duration for each frame of the animation.</p>



<p>The XML file consists of an <code>&lt;animation-list></code> element as the root node and a series

of child <code>&lt;item></code> nodes that each define a frame: a drawable resource for the frame and the frame duration.

Here's an example XML file for a frame-by-frame animation:</p>

<pre>

&lt;animation-list xmlns:android="http://schemas.android.com/apk/res/android"

    android:oneshot="true">

    &lt;item android:drawable="&#64;drawable/rocket_thrust1" android:duration="200" />

    &lt;item android:drawable="&#64;drawable/rocket_thrust2" android:duration="200" />

    &lt;item android:drawable="&#64;drawable/rocket_thrust3" android:duration="200" />

&lt;/animation-list>

</pre>



<p>This animation runs for just three frames. By setting the <code>android:oneshot</code> attribute of the 

list to <var>true</var>, it will cycle just once then stop and hold on the last frame. If it is set <var>false</var> then

the animation will loop. With this XML saved as <code>rocket_thrust.xml</code> in the <code>res/drawable/</code> directory

of the project, it can be added as the background image to a View and then called to play. Here's an example Activity,

in which the animation is added to an {@link android.widget.ImageView} and then animated when the screen is touched:</p>

<pre>

AnimationDrawable rocketAnimation;



public void onCreate(Bundle savedInstanceState) {

  super.onCreate(savedInstanceState);

  setContentView(R.layout.main);



  ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image);

  rocketImage.setBackgroundResource(R.drawable.rocket_thrust);

  rocketAnimation = (AnimationDrawable) rocketImage.getBackground();

}



public boolean onTouchEvent(MotionEvent event) {

  if (event.getAction() == MotionEvent.ACTION_DOWN) {

    rocketAnimation.start();

    return true;

  }

  return super.onTouchEvent(event);

}

</pre>

<p>It's important to note that the <code>start()</code> method called on the AnimationDrawable cannot be

called during the <code>onCreate()</code> method of your Activity, because the AnimationDrawable is not yet fully attached

to the window. If you want to play the animation immediately, without

requiring interaction, then you might want to call it from the 

<code>{@link android.app.Activity#onWindowFocusChanged(boolean) onWindowFocusChanged()}</code> method in 

your Activity, which will get called when Android brings your window into focus.</p> 



<p>For more information on the XML syntax, available tags and attributes, see <a

href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>

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

0 → 100644
+839 −0

File added.

Preview size limit exceeded, changes collapsed.