From 7d76fc4433e0eedf10b0a87860565ddc93e8ef2e Mon Sep 17 00:00:00 2001 From: Doris Liu Date: Fri, 16 Sep 2016 15:36:46 -0700 Subject: [PATCH] Improve Javadoc for AnimatedVectorDrawable This CL adds a summary of what developers can expect from running AVD on RenderThread. Also re-structure the class level Javadoc summary to better organize the examples. Test: make offline-sdk-docs BUG: 30402908 Change-Id: I7111f67db5f2ec352730f633bb34f2e89e1c70e9 --- .../drawable/AnimatedVectorDrawable.java | 108 ++++++++++++------ 1 file changed, 71 insertions(+), 37 deletions(-) diff --git a/graphics/java/android/graphics/drawable/AnimatedVectorDrawable.java b/graphics/java/android/graphics/drawable/AnimatedVectorDrawable.java index 0f305f3cff3d2..dcca431ea7544 100644 --- a/graphics/java/android/graphics/drawable/AnimatedVectorDrawable.java +++ b/graphics/java/android/graphics/drawable/AnimatedVectorDrawable.java @@ -65,19 +65,36 @@ import java.lang.ref.WeakReference; import java.util.ArrayList; /** - * This class uses {@link android.animation.ObjectAnimator} and - * {@link android.animation.AnimatorSet} to animate the properties of a - * {@link android.graphics.drawable.VectorDrawable} to create an animated drawable. + * This class animates properties of a {@link android.graphics.drawable.VectorDrawable} with + * animations defined using {@link android.animation.ObjectAnimator} or + * {@link android.animation.AnimatorSet}. *

- * AnimatedVectorDrawable are normally defined as 3 separate XML files. + * Starting from API 25, AnimatedVectorDrawable runs on RenderThread (as opposed to on UI thread for + * earlier APIs). This means animations in AnimatedVectorDrawable can remain smooth even when there + * is heavy workload on the UI thread. Note: If the UI thread is unresponsive, RenderThread may + * continue animating until the UI thread is capable of pushing another frame. Therefore, it is not + * possible to precisely coordinate a RenderThread-enabled AnimatedVectorDrawable with UI thread + * animations. Additionally, + * {@link android.graphics.drawable.Animatable2.AnimationCallback#onAnimationEnd(Drawable)} will be + * called the frame after the AnimatedVectorDrawable finishes on the RenderThread. *

*

- * First is the XML file for {@link android.graphics.drawable.VectorDrawable}. - * Note that we allow the animation to happen on the group's attributes and path's - * attributes, which requires they are uniquely named in this XML file. Groups - * and paths without animations do not need names. + * AnimatedVectorDrawable can be defined in either three separate XML files, + * or one XML. *

- *
  • Here is a simple VectorDrawable in this vectordrawable.xml file. + * + *

    Define an AnimatedVectorDrawable in three separate XML files

    + * + * + *

    Define an AnimatedVectorDrawable all in one XML file

    *

    - * Since AAPT tool is now supporting a new format which can bundle several related XML files into - * one, we can merge the previous example into one XML file, like this: + * Since the AAPT tool supports a new format that bundles several related XML files together, we can + * merge the XML files from the previous examples into one XML file: *

    * 
      * <animated-vector xmlns:android="http://schemas.android.com/apk/res/android" >
@@ -185,7 +209,7 @@ import java.util.ArrayList;
  *                 <objectAnimator
  *                     android:duration="3000"
  *                     android:propertyName="pathData"
- *                     android:valueFrom="M300,70 l 0,-70 70,70 0,0   -70,70z"
+ *                     android:valueFrom="M300,70 l 0,-70 70,70 0,0 -70,70z"
  *                     android:valueTo="M300,70 l 0,-70 70,0  0,140 -70,0 z"
  *                     android:valueType="pathType"/>
  *             </set>
@@ -286,6 +310,17 @@ public class AnimatedVectorDrawable extends Drawable implements Animatable2 {
         return super.getChangingConfigurations() | mAnimatedVectorState.getChangingConfigurations();
     }
 
+    /**
+     * Draws the AnimatedVectorDrawable into the given canvas.
+     * 
    
+     * Note: Calling this method with a software canvas when the
+     * AnimatedVectorDrawable is being animated on RenderThread (for API 25 and later) may yield
+     * outdated result, as the UI thread is not guaranteed to be in sync with RenderThread on
+     * VectorDrawable's property changes during RenderThread animations.
+     * 
    
+     *
+     * @param canvas The canvas to draw into
+     */
     @Override
     public void draw(Canvas canvas) {
         if (!canvas.isHardwareAccelerated() && mAnimatorSet instanceof VectorDrawableAnimatorRT) {
@@ -321,9 +356,9 @@ public class AnimatedVectorDrawable extends Drawable implements Animatable2 {
     }
 
     /**
-     * AnimatedVectorDrawable is running on render thread now. Therefore, if the root alpha is being
-     * animated, then the root alpha value we get from this call could be out of sync with alpha
-     * value used in the render thread. Otherwise, the root alpha should be always the same value.
+     * For API 25 and later, AnimatedVectorDrawable runs on RenderThread. Therefore, when the
+     * root alpha is being animated, this getter does not guarantee to return an up-to-date alpha
+     * value.
      *
      * @return the containing vector drawable's root alpha value.
      */
@@ -1495,7 +1530,6 @@ public class AnimatedVectorDrawable extends Drawable implements Animatable2 {
             } else {
                 addPendingAction(START_ANIMATION);
             }
-
         }
 
         @Override