various fixes for animations and javadocs

Issues around threading of animations and AnimatorSet bugs are
fixed in this change. Unrelated fixes to javadocs in other
framework classes are also part of the change.

Change-Id: I35f7e03ffdec9143bc2eb155e8f9384798ad35b3

5 files changed, 81 insertions, 42 deletions

diff --git a/api/current.xml b/api/current.xml
index 86e8f8b..04d7a1d 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -18994,7 +18994,7 @@
  visibility="public"
 >
 <method name="after"
- return="void"
+ return="android.animation.AnimatorSet.Builder"
  abstract="false"
  native="false"
  synchronized="false"
@@ -19007,7 +19007,7 @@
 </parameter>
 </method>
 <method name="after"
- return="void"
+ return="android.animation.AnimatorSet.Builder"
  abstract="false"
  native="false"
  synchronized="false"
@@ -19020,7 +19020,7 @@
 </parameter>
 </method>
 <method name="before"
- return="void"
+ return="android.animation.AnimatorSet.Builder"
  abstract="false"
  native="false"
  synchronized="false"
@@ -19033,7 +19033,7 @@
 </parameter>
 </method>
 <method name="with"
- return="void"
+ return="android.animation.AnimatorSet.Builder"
  abstract="false"
  native="false"
  synchronized="false"
@@ -249195,7 +249195,7 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="arg0" type="T">
+<parameter name="t" type="T">
 </parameter>
 </method>
 </interface>
diff --git a/core/java/android/animation/AnimatorSet.java b/core/java/android/animation/AnimatorSet.java
index 9ba9388..f5420d1 100644
--- a/core/java/android/animation/AnimatorSet.java
+++ b/core/java/android/animation/AnimatorSet.java
@@ -341,6 +341,20 @@ public final class AnimatorSet extends Animator {
         return this;
     }
 
+    @Override
+    public void setupStartValues() {
+        for (Node node : mNodes) {
+            node.animation.setupStartValues();
+        }
+    }
+
+    @Override
+    public void setupEndValues() {
+        for (Node node : mNodes) {
+            node.animation.setupEndValues();
+        }
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -401,6 +415,7 @@ public final class AnimatorSet extends Animator {
                     }
                 }
             });
+            delayAnim.start();
         }
         if (mListeners != null) {
             ArrayList<AnimatorListener> tmpListeners =
@@ -408,6 +423,11 @@ public final class AnimatorSet extends Animator {
             int numListeners = tmpListeners.size();
             for (int i = 0; i < numListeners; ++i) {
                 tmpListeners.get(i).onAnimationStart(this);
+                if (mNodes.size() == 0) {
+                    // Handle unusual case where empty AnimatorSet is started - should send out
+                    // end event immediately since the event will not be sent out at all otherwise
+                    tmpListeners.get(i).onAnimationEnd(this);
+                }
             }
         }
     }
@@ -894,7 +914,7 @@ public final class AnimatorSet extends Animator {
          * @param anim The animation that will play when the animation supplied to the
          * {@link AnimatorSet#play(Animator)} method starts.
          */
-        public void with(Animator anim) {
+        public Builder with(Animator anim) {
             Node node = mNodeMap.get(anim);
             if (node == null) {
                 node = new Node(anim);
@@ -903,6 +923,7 @@ public final class AnimatorSet extends Animator {
             }
             Dependency dependency = new Dependency(mCurrentNode, Dependency.WITH);
             node.addDependency(dependency);
+            return this;
         }
 
         /**
@@ -913,7 +934,7 @@ public final class AnimatorSet extends Animator {
          * @param anim The animation that will play when the animation supplied to the
          * {@link AnimatorSet#play(Animator)} method ends.
          */
-        public void before(Animator anim) {
+        public Builder before(Animator anim) {
             Node node = mNodeMap.get(anim);
             if (node == null) {
                 node = new Node(anim);
@@ -922,6 +943,7 @@ public final class AnimatorSet extends Animator {
             }
             Dependency dependency = new Dependency(mCurrentNode, Dependency.AFTER);
             node.addDependency(dependency);
+            return this;
         }
 
         /**
@@ -932,7 +954,7 @@ public final class AnimatorSet extends Animator {
          * @param anim The animation whose end will cause the animation supplied to the
          * {@link AnimatorSet#play(Animator)} method to play.
          */
-        public void after(Animator anim) {
+        public Builder after(Animator anim) {
             Node node = mNodeMap.get(anim);
             if (node == null) {
                 node = new Node(anim);
@@ -941,6 +963,7 @@ public final class AnimatorSet extends Animator {
             }
             Dependency dependency = new Dependency(node, Dependency.AFTER);
             mCurrentNode.addDependency(dependency);
+            return this;
         }
 
         /**
@@ -951,11 +974,12 @@ public final class AnimatorSet extends Animator {
          * @param delay The number of milliseconds that should elapse before the
          * animation starts.
          */
-        public void after(long delay) {
+        public Builder after(long delay) {
             // setup dummy ValueAnimator just to run the clock
             ValueAnimator anim = ValueAnimator.ofFloat(0f, 1f);
             anim.setDuration(delay);
             after(anim);
+            return this;
         }
 
     }
diff --git a/core/java/android/animation/ValueAnimator.java b/core/java/android/animation/ValueAnimator.java
index b021e75..e192067 100755
--- a/core/java/android/animation/ValueAnimator.java
+++ b/core/java/android/animation/ValueAnimator.java
@@ -19,6 +19,7 @@ package android.animation;
 import android.os.Handler;
 import android.os.Looper;
 import android.os.Message;
+import android.util.AndroidRuntimeException;
 import android.view.animation.AccelerateDecelerateInterpolator;
 import android.view.animation.AnimationUtils;
 
@@ -860,21 +861,22 @@ public class ValueAnimator extends Animator {
     /**
      * Start the animation playing. This version of start() takes a boolean flag that indicates
      * whether the animation should play in reverse. The flag is usually false, but may be set
-     * to true if called from the reverse() method/
+     * to true if called from the reverse() method.
+     *
+     * <p>The animation started by calling this method will be run on the thread that called
+     * this method. This thread should have a Looper on it (a runtime exception will be thrown if
+     * this is not the case). Also, if the animation will animate
+     * properties of objects in the view hierarchy, then the calling thread should be the UI
+     * thread for that view hierarchy.</p>
      *
      * @param playBackwards Whether the ValueAnimator should start playing in reverse.
      */
     private void start(boolean playBackwards) {
-        mPlayingBackwards = playBackwards;
-        Looper looper = Looper.getMainLooper();
-        final boolean isUiThread;
-        if (looper != null) {
-            isUiThread = Thread.currentThread() == looper.getThread();
-        } else {
-            // ignore check if we don't have a Looper (this isn't an Activity)
-            isUiThread = true;
+        if (Looper.myLooper() == null) {
+            throw new AndroidRuntimeException("Animators may only be run on Looper threads");
         }
-        if ((mStartDelay == 0) && isUiThread) {
+        mPlayingBackwards = playBackwards;
+        if (mStartDelay == 0) {
             if (mListeners != null) {
                 ArrayList<AnimatorListener> tmpListeners =
                         (ArrayList<AnimatorListener>) mListeners.clone();
@@ -912,9 +914,14 @@ public class ValueAnimator extends Animator {
                 listener.onAnimationCancel(this);
             }
         }
-        // Just set the CANCELED flag - this causes the animation to end the next time a frame
-        // is processed.
-        mPlayingState = CANCELED;
+        // Only cancel if the animation is actually running or has been started and is about
+        // to run
+        if (mPlayingState != STOPPED || sPendingAnimations.get().contains(this) ||
+                sDelayedAnims.get().contains(this)) {
+            // Just set the CANCELED flag - this causes the animation to end the next time a frame
+            // is processed.
+            mPlayingState = CANCELED;
+        }
     }
 
     @Override
diff --git a/core/java/android/os/Debug.java b/core/java/android/os/Debug.java
index 2b4f39a..1c295a7 100644
--- a/core/java/android/os/Debug.java
+++ b/core/java/android/os/Debug.java
@@ -513,21 +513,27 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
     }
 
     /**
-     * Count the number and aggregate size of memory allocations between
-     * two points.
+     * Start counting the number and aggregate size of memory allocations.
      *
-     * The "start" function resets the counts and enables counting.  The
-     * "stop" function disables the counting so that the analysis code
-     * doesn't cause additional allocations.  The "get" function returns
-     * the specified value.
+     * <p>The {@link #startAllocCounting() start} function resets the counts and enables counting.
+     * The {@link #stopAllocCounting() stop} function disables the counting so that the analysis
+     * code doesn't cause additional allocations.  The various <code>get</code> functions return
+     * the specified value. And the various <code>reset</code> functions reset the specified
+     * count.</p>
      *
-     * Counts are kept for the system as a whole and for each thread.
+     * <p>Counts are kept for the system as a whole and for each thread.
      * The per-thread counts for threads other than the current thread
-     * are not cleared by the "reset" or "start" calls.
+     * are not cleared by the "reset" or "start" calls.</p>
      */
     public static void startAllocCounting() {
         VMDebug.startAllocCounting();
     }
+
+    /**
+     * Stop counting the number and aggregate size of memory allocations.
+     *
+     * @see #startAllocCounting()
+     */
     public static void stopAllocCounting() {
         VMDebug.stopAllocCounting();
     }
@@ -671,11 +677,11 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
      * for catching regressions in code that is expected to operate
      * without causing any allocations.
      *
-     * Pass in the maximum number of allowed allocations.  Use -1 to disable
-     * the limit.  Returns the previous limit.
-     *
-     * The preferred way to use this is:
+     * <p>Pass in the maximum number of allowed allocations.  Use -1 to disable
+     * the limit.  Returns the previous limit.</p>
      *
+     * <p>The preferred way to use this is:
+     * <pre>
      *  int prevLimit = -1;
      *  try {
      *      prevLimit = Debug.setAllocationLimit(0);
@@ -683,16 +689,16 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
      *  } finally {
      *      Debug.setAllocationLimit(prevLimit);
      *  }
-     *
+     * </pre>
      * This allows limits to be nested.  The try/finally ensures that the
-     * limit is reset if something fails.
+     * limit is reset if something fails.</p>
      *
-     * Exceeding the limit causes a dalvik.system.AllocationLimitError to
+     * <p>Exceeding the limit causes a dalvik.system.AllocationLimitError to
      * be thrown from a memory allocation call.  The limit is reset to -1
-     * when this happens.
+     * when this happens.</p>
      *
-     * The feature may be disabled in the VM configuration.  If so, this
-     * call has no effect, and always returns -1.
+     * <p>The feature may be disabled in the VM configuration.  If so, this
+     * call has no effect, and always returns -1.</p>
      */
     public static int setAllocationLimit(int limit) {
         return VMDebug.setAllocationLimit(limit);
@@ -846,6 +852,7 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
      * API for gathering and querying instruction counts.
      *
      * Example usage:
+     * <pre>
      *   Debug.InstructionCount icount = new Debug.InstructionCount();
      *   icount.resetAndStart();
      *    [... do lots of stuff ...]
@@ -855,6 +862,7 @@ href="{@docRoot}guide/developing/tools/traceview.html">Traceview: A Graphical Lo
      *       System.out.println("Method invocations: "
      *           + icount.globalMethodInvocations());
      *   }
+     * </pre>
      */
     public static class InstructionCount {
         private static final int NUM_INSTR = 256;
diff --git a/graphics/java/android/graphics/ComposeShader.java b/graphics/java/android/graphics/ComposeShader.java
index 8d5c913..241ab17 100644
--- a/graphics/java/android/graphics/ComposeShader.java
+++ b/graphics/java/android/graphics/ComposeShader.java
@@ -30,7 +30,7 @@ public class ComposeShader extends Shader {
 
     /** Create a new compose shader, given shaders A, B, and a combining mode.
         When the mode is applied, it will be given the result from shader A as its
-        "dst", and the result of from shader B as its "src".
+        "dst", and the result from shader B as its "src".
         @param shaderA  The colors from this shader are seen as the "dst" by the mode
         @param shaderB  The colors from this shader are seen as the "src" by the mode
         @param mode     The mode that combines the colors from the two shaders. If mode
@@ -53,7 +53,7 @@ public class ComposeShader extends Shader {
 
     /** Create a new compose shader, given shaders A, B, and a combining PorterDuff mode.
         When the mode is applied, it will be given the result from shader A as its
-        "dst", and the result of from shader B as its "src".
+        "dst", and the result from shader B as its "src".
         @param shaderA  The colors from this shader are seen as the "dst" by the mode
         @param shaderB  The colors from this shader are seen as the "src" by the mode
         @param mode     The PorterDuff mode that combines the colors from the two shaders.