diff --git a/docs/html/guide/topics/graphics/animation.jd b/docs/html/guide/topics/graphics/animation.jd index 0b02ee767e7d6..31e7c4b79e9e0 100644 --- a/docs/html/guide/topics/graphics/animation.jd +++ b/docs/html/guide/topics/graphics/animation.jd @@ -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.

+

Tip: To see how the ADT layout editor allows you to develop and +preview animations in your layout, watch the Android +Developer Tools session from Google I/O '11

+ +

What is Property Animation?

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. +

How the property animation system works

@@ -894,99 +901,5 @@ resources.

  • {@link android.animation.AnimatorSet} - <set>
    • -

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

    +

    See Animation Resources -

    -
    android:duration
    - -
    The number of milliseconds that the animation runs. The default is 300 ms.
    - -
    android:valueFrom and android:valueTo
    - -
    The values being animated between. These are restricted to numbers (float or - int) and color values (such as #00ff00). They can be float, int, colors, - or any kind of Object when creating animations programmatically.
    - -
    android:valueType
    - -
    Set to either "floatType" or "intType". The default is - "floatType" unless you specify something else or if the valuesFrom - and valuesTo values are colors.
    - -
    android:startOffset
    - -
    The delay, in milliseconds, before the animation begins playing (after calling {@link - android.animation.ValueAnimator#start start()}).
    - -
    android:repeatCount
    - -
    How many times to repeat an animation. Set to "-1" to infinitely repeat or - to a positive integer. For example, a value of "1" 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 "0", which means no repetition.
    - -
    android:repeatMode
    - -
    How an animation behaves when it reaches the end of the animation. - android:repeatCount must be set to a positive integer or "-1" for - this attribute to have an effect. Set to "reverse" to have the animation reverse - direction with each iteration or "repeat" to have the animation loop from the - beginning each time.
    -
    - -

    The <objectAnimator> ({@link android.animation.ObjectAnimator}) element has the - additional attribute android:propertyName, that lets you specify the name of the -property - being animated. The <objectAnimator> element does not expose a target - 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()}.

    - -

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

    - -

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

    - -

    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:

    - 
    -<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>
-
    - -

    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}.

    - -

    Tip: To see how the ADT layout editor allows you to develop and -preview animations in your layout, watch the Android -Developer Tools session from Google I/O '11

    diff --git a/docs/html/guide/topics/resources/animation-resource.jd b/docs/html/guide/topics/resources/animation-resource.jd index 972dd729cb1df..3df669c06eb71 100644 --- a/docs/html/guide/topics/resources/animation-resource.jd +++ b/docs/html/guide/topics/resources/animation-resource.jd @@ -5,28 +5,348 @@ parent.link=available-resources.html
    +

    In this document

    +
      +
    1. Property Animation
      2. +
    2. View Animation +
        +
      1. Tween animation
        2. +
      2. Frame animation
        3. +
      +
      3. +

    See also

      -
    1. 2D -Graphics
      2. +
    2. View Animation
      3. +
    3. Property Animation

    An animation resource can define one of two types of animations:

    +
    -
    Tween Animation
    -
    Creates an animation by performing a series of transformations on a single image. - An {@link android.view.animation.Animation}.
    -
    Frame Animation
    -
    Creates an animation by showing a sequence of images in order. - An {@link android.graphics.drawable.AnimationDrawable}.
    +
    Property Animation
    +
    Creates an animation by modifying an object's property values over a set period + of time with an {@link android.animation.Animator}.
    +
    View Animation
    +
    +

    There are two types of animations that you can do with the view animation framework:

    + +
    +

    Property Animation

    +

    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.

    -

    Tween Animation

    +
    + +
    file location:
    +
    res/animator/filename.xml
    +The filename will be used as the resource ID.
    + +
    compiled resource datatype:
    +
    Resource pointer to a {@link android.animation.ValueAnimator}, {@link android.animation.ObjectAnimator}, +or {@link android.animation.AnimatorSet}.
    + +
    resource reference:
    +
    +In Java: R.animator.filename
    +In XML: @[package:]animator/filename +
    + +
    syntax:
    +
    +
    +<set
+  android:ordering=["together" | "sequentially"]>
+
+    <objectAnimator
+        android:propertyName="string"
+        android:duration="int"
+        android:valueFrom="float | int | color"
+        android:valueTo="float | int | color"
+        android:startOffset="int"
+        android:repeatCount="int"
+        android:repeatMode=["repeat" | "reverse"]
+        android:valueType=["intType" | "floatType"]/>
+
+    <animator
+        android:duration="int"
+        android:valueFrom="float | int | color"
+        android:valueTo="float | int | color"
+        android:startOffset="int"
+        android:repeatCount="int"
+        android:repeatMode=["repeat" | "reverse"]
+        android:valueType=["intType" | "floatType"]/>
+
+    <set>
+        ...
+    </set>
+</set>
+
    + +

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

    +
    + +
    elements:
    +
    +
    +
    <set>
    +
    A container that holds other animation elements (<objectAnimator>, + <valueAnimator>, or other <set> elements). Represents + an {@link android.animation.AnimatorSet}. +

    You can specify nested <set> tags to further + group animations together. Each <set> can define its own + ordering attribute.

    + +

    attributes:

    +
    +
    + android:ordering +
    +
    + Keyword. Specifies the play ordering of animations in this set. + + + + +
    ValueDescription
    sequentiallyPlay animations in this set sequentially
    together (default)Play animations in this set at the same time.
    +
    +
    +
    + +
    <objectAnimator>
    +
    Animates a specific property of an object over a specific amount of time. Represents + an {@link android.animation.ObjectAnimator}.

    + +

    attributes:

    +
    +
    + android:propertyName +
    +
    + String. Required. The object's property to animate, referenced by its name. For example you can specify + "alpha" or "backgroundColor" for a View object. + The objectAnimator element does not expose a target + 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. +
    + +
    + android:valueTo +
    +
    + float, int, or color. Required. The value where the animated property ends. Colors are represented + as six digit hexadecimal numbers (for example, #333333). +
    + +
    + android:valueFrom +
    +
    + float, int, or color. 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). +
    + +
    + android:duration +
    +
    + int. The time in milliseconds of the animation. 300 milliseconds is the default. +
    + +
    + android:startOffset +
    +
    + int. The amount of milliseconds the animation delays after + {@link android.animation.ObjectAnimator#start start()} is called. +
    + +
    + android:repeatCount +
    +
    + int. How many times to repeat an animation. Set to "-1" to infinitely + repeat or to a positive integer. For example, a value of "1" 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 "0", which means no repetition. + +
    + +
    + android:repeatMode +
    +
    + int. How an animation behaves when it reaches the end of the animation. android:repeatCount + must be set to a positive integer or "-1" for this attribute to have an effect. Set to "reverse" + to have the animation reverse direction with each iteration or "repeat" to have the animation + loop from the beginning each time. +
    + +
    + android:valueType +
    +
    + Keyword. Do not specify this attribute if the value is a color. The animation framework automatically handles color + values + + + + +
    ValueDescription
    intTypeSpecifies that the animated values are integers
    floatType (default)Specifies that the animated values are floats
    +
    + +
    +
    + +
    <animator>
    +
    Animates a over a specified amount of time. + Represents a {@link android.animation.ValueAnimator}. + +

    attributes:

    +
    +
    + android:valueTo +
    +
    + float, int, or color. Required. The value where the animation ends. Colors are represented + as six digit hexadecimal numbers (for example, #333333). +
    + +
    + android:valueFrom +
    +
    + float, int, or color. Required. The value where the animation starts. Colors are represented + as six digit hexadecimal numbers (for example, #333333). +
    + +
    + android:duration +
    +
    + int. The time in milliseconds of the animation. 300ms is the default. +
    + +
    + android:startOffset +
    +
    + int. The amount of milliseconds the animation delays after + {@link android.animation.ValueAnimator#start start()} is called. +
    + +
    + android:repeatCount +
    +
    + int. How many times to repeat an animation. Set to "-1" to infinitely + repeat or to a positive integer. For example, a value of "1" 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 "0", which means no repetition. +
    + +
    + android:repeatMode +
    +
    + int. How an animation behaves when it reaches the end of the animation. android:repeatCount + must be set to a positive integer or "-1" for this attribute to have an effect. Set to "reverse" + to have the animation reverse direction with each iteration or "repeat" to have the animation + loop from the beginning each time. +
    + +
    + android:valueType +
    +
    + Keyword. Do not specify this attribute if the value is a color. The animation framework automatically handles color + values. + + + + +
    ValueDescription
    intTypeSpecifies that the animated values are integers
    floatType (default)Specifies that the animated values are floats
    +
    + +
    +
    +
    + +
    + +
    example:
    +
    + XML file saved at res/animator/property_animator.xml:

    +
    +<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>
+
    +

    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:

    + +
    +AnimatorSet set = (AnimatorSet) AnimatorInflater.loadAnimator(myContext,
+    R.anim.property_animator);
+set.setTarget(myObject);
+set.start();
+
    + + +
    + +
    see also:
    +
    + +
    + +
    + +

    View Animation

    +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. + +

    Tween animation

    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

    see also:
    - - - - -

    Interpolators

    +

    Interpolators

    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. - - - - - - - - - - - - - - - -

    Frame Animation

    +

    Frame animation

    An animation defined in XML that shows a sequence of images in order (like a film).

    @@ -562,7 +863,11 @@ rocketAnimation.{@link android.graphics.drawable.AnimationDrawable#start()}; +
    see also:
    +
    + +
    - - -