Merge "Improve Javadoc for AnimatedVectorDrawable" into nyc-mr1-dev

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

 * <p>

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

 * </p>

 * <p>

 * 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 <a href="#ThreeXML">three separate XML files</a>,

 * or <a href="#OneXML">one XML</a>.

 * </p>

 * <li>Here is a simple VectorDrawable in this vectordrawable.xml file.

 * <a name="ThreeXML"></a>

 * <h3>Define an AnimatedVectorDrawable in three separate XML files</h3>

 * <ul>

 * <a name="VDExample"></a>

 * <li><h4>XML for the VectorDrawable containing properties to be animated</h4>

 * <p>

 * Animations can be performed on both group and path attributes, which requires groups and paths to

 * have unique names in the same VectorDrawable. Groups and paths without animations do not need to

 * be named.

 * </p>

 * Below is an example of a VectorDrawable defined in vectordrawable.xml. This VectorDrawable is

 * referred to by its file name (not including file suffix) in the

 * <a href="AVDExample">AnimatedVectorDrawable XML example</a>.

 * <pre>

 * <vector xmlns:android="http://schemas.android.com/apk/res/android"

 *     android:height="64dp"

 *     </group>

 * </vector>

 * </pre></li>

 *

 * <a name="AVDExample"></a>

 * <li><h4>XML for AnimatedVectorDrawable</h4>

 * <p>

 * Second is the AnimatedVectorDrawable's XML file, which defines the target

 * VectorDrawable, the target paths and groups to animate, the properties of the

 * path and group to animate and the animations defined as the ObjectAnimators

 * or AnimatorSets.

 * An AnimatedVectorDrawable element has a VectorDrawable attribute, and one or more target

 * element(s). The target elements can be the path or group to be animated. Each target element

 * contains a name attribute that references a property (of a path or a group) to animate, and an

 * animation attribute that points to an ObjectAnimator or an AnimatorSet.

 * </p>

 * <li>Here is a simple AnimatedVectorDrawable defined in this avd.xml file.

 * Note how we use the names to refer to the groups and paths in the vectordrawable.xml.

 * The following code sample defines an AnimatedVectorDrawable. Note that the names refer to the

 * groups and paths in the <a href="#VDExample">VectorDrawable XML above</a>.

 * <pre>

 * <animated-vector xmlns:android="http://schemas.android.com/apk/res/android"

 *     android:drawable="@drawable/vectordrawable" >

 *         android:name="v"

 *         android:animation="@anim/path_morph" />

 * </animated-vector>

 * </pre></li>

 * </pre>

 * </li>

 *

 * <li><h4>XML for Animations defined using ObjectAnimator or AnimatorSet</h4>

 * <p>

 * Last is the Animator XML file, which is the same as a normal ObjectAnimator

 * or AnimatorSet.

 * To complete this example, here are the 2 animator files used in avd.xml:

 * rotation.xml and path_morph.xml.

 * From the previous <a href="#AVDExample">example of AnimatedVectorDrawable</a>, two animations

 * were used: rotation.xml and path_morph.xml.

 * </p>

 * <li>Here is the rotation.xml, which will rotate the target group for 360 degrees.

 * rotation.xml rotates the target group from 0 degree to 360 degrees over 6000ms:

 * <pre>

 * <objectAnimator

 *     android:duration="6000"

 *     android:propertyName="rotation"

 *     android:valueFrom="0"

 *     android:valueTo="360" />

 * </pre></li>

 * <li>Here is the path_morph.xml, which will morph the path from one shape to

 * the other. Note that the paths must be compatible for morphing.

 * In more details, the paths should have exact same length of commands , and

 * exact same length of parameters for each commands.

 * Note that the path strings are better stored in strings.xml for reusing.

 * </pre>

 *

 * path_morph.xml morphs the path from one shape into the other. Note that the paths must be

 * compatible for morphing. Specifically, the paths must have the same commands, in the same order,

 * and must have the same number of parameters for each command. It is recommended to store path

 * strings as string resources for reuse.

 * <pre>

 * <set xmlns:android="http://schemas.android.com/apk/res/android">

 *     <objectAnimator

 *         android:valueTo="M300,70 l 0,-70 70,0  0,140 -70,0 z"

 *         android:valueType="pathType"/>

 * </set>

 * </pre></li>

 * </pre>

 * </ul>

 * <a name="OneXML"></a>

 * <h3>Define an AnimatedVectorDrawable all in one XML file</h3>

 * <p>

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

 * </p>

 * <pre>

 * <animated-vector xmlns:android="http://schemas.android.com/apk/res/android" >

        return super.getChangingConfigurations() | mAnimatedVectorState.getChangingConfigurations();

    }

    /**

     * Draws the AnimatedVectorDrawable into the given canvas.

     * <p>

     * <strong>Note:</strong> 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.

     * </p>

     *

     * @param canvas The canvas to draw into

     */

    @Override

    public void draw(Canvas canvas) {

        if (!canvas.isHardwareAccelerated() && mAnimatorSet instanceof VectorDrawableAnimatorRT) {

    }

    /**

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

     */

            } else {

                addPendingAction(START_ANIMATION);

            }

        }

        @Override