API and doc cleanup, plus small animation/UI features

Adding features which round out the animation APIs (missing
getters, etc.). Also fix doc typos.

Issue #8350510 Add APIs needed for future animation capabilities

Change-Id: I063736848ba26e6d6c809b15fc3a103c74222f46

9 files changed, 169 insertions, 52 deletions

diff --git a/core/java/android/animation/Animatable.java b/core/java/android/animation/Animatable.java
new file mode 100644
index 0000000..f9ccb4d
--- /dev/null
+++ b/core/java/android/animation/Animatable.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.animation;
+
+/**
+ * This interface is implemented by animation-related classes that expose
+ * the ability to set and get duration, startDelay, and interpolators.
+ */
+public interface Animatable {
+
+    /**
+     * The amount of time, in milliseconds, to delay processing the animation
+     * after the animation is started. The {@link #setDuration(long)} of the
+     * animation will not begin to elapse until after the startDelay has elapsed.
+     *
+     * @return the number of milliseconds to delay running the animation
+     */
+    long getStartDelay();
+
+    /**
+     * The amount of time, in milliseconds, to delay processing the animation
+     * after the animation is started. The {@link #setDuration(long)} of the
+     * animation will not begin to elapse until after the startDelay has elapsed.
+
+     * @param startDelay The amount of the delay, in milliseconds
+     */
+    void setStartDelay(long startDelay);
+
+    /**
+     * Sets the length of the animation.
+     *
+     * @param duration The length of the animation, in milliseconds.
+     */
+    Animatable setDuration(long duration);
+
+    /**
+     * Gets the duration of the animation.
+     *
+     * @return The length of the animation, in milliseconds.
+     */
+    long getDuration();
+
+    /**
+     * The time interpolator used in calculating the elapsed fraction of the
+     * animation. The interpolator determines whether the animation runs with
+     * linear or non-linear motion, such as acceleration and deceleration.
+     *
+     * @param value the interpolator to be used by this animation
+     */
+    void setInterpolator(TimeInterpolator value);
+
+    /**
+     * Returns the timing interpolator that this animation uses.
+     *
+     * @return The timing interpolator for this animation.
+     */
+    public TimeInterpolator getInterpolator();
+}
diff --git a/core/java/android/animation/Animator.java b/core/java/android/animation/Animator.java
index 788765d..da97d72 100644
--- a/core/java/android/animation/Animator.java
+++ b/core/java/android/animation/Animator.java
@@ -22,14 +22,21 @@ import java.util.ArrayList;
  * This is the superclass for classes which provide basic support for animations which can be
  * started, ended, and have <code>AnimatorListeners</code> added to them.
  */
-public abstract class Animator implements Cloneable {
-
+public abstract class Animator implements Cloneable, Animatable {
 
     /**
      * The set of listeners to be sent events through the life of an animation.
      */
     ArrayList<AnimatorListener> mListeners = null;
 
+    @Override
+    public abstract Animator setDuration(long duration);
+
+    @Override
+    public TimeInterpolator getInterpolator() {
+        return null;
+    }
+
     /**
      * Starts this animation. If the animation has a nonzero startDelay, the animation will start
      * running after that delay elapses. A non-delayed animation will have its initial
@@ -70,47 +77,6 @@ public abstract class Animator implements Cloneable {
     }
 
     /**
-     * The amount of time, in milliseconds, to delay starting the animation after
-     * {@link #start()} is called.
-     *
-     * @return the number of milliseconds to delay running the animation
-     */
-    public abstract long getStartDelay();
-
-    /**
-     * The amount of time, in milliseconds, to delay starting the animation after
-     * {@link #start()} is called.
-
-     * @param startDelay The amount of the delay, in milliseconds
-     */
-    public abstract void setStartDelay(long startDelay);
-
-
-    /**
-     * Sets the length of the animation.
-     *
-     * @param duration The length of the animation, in milliseconds.
-     */
-    public abstract Animator setDuration(long duration);
-
-    /**
-     * Gets the length of the animation.
-     *
-     * @return The length of the animation, in milliseconds.
-     */
-    public abstract long getDuration();
-
-    /**
-     * The time interpolator used in calculating the elapsed fraction of this animation. The
-     * interpolator determines whether the animation runs with linear or non-linear motion,
-     * such as acceleration and deceleration. The default value is
-     * {@link android.view.animation.AccelerateDecelerateInterpolator}
-     *
-     * @param value the interpolator to be used by this animation
-     */
-    public abstract void setInterpolator(TimeInterpolator value);
-
-    /**
      * Returns whether this Animator is currently running (having been started and gone past any
      * initial startDelay period and not yet ended).
      *
diff --git a/core/java/android/animation/AnimatorSet.java b/core/java/android/animation/AnimatorSet.java
index f9fa444..b48853b 100644
--- a/core/java/android/animation/AnimatorSet.java
+++ b/core/java/android/animation/AnimatorSet.java
@@ -120,9 +120,19 @@ public final class AnimatorSet extends Animator {
     // set, it is passed along to the child animations.
     private long mDuration = -1;
 
+    // Records the interpolator for the set. Null value indicates that no interpolator
+    // was set on this AnimatorSet, so it should not be passed down to the children.
+    private TimeInterpolator mInterpolator = null;
+
 
     /**
      * Sets up this AnimatorSet to play all of the supplied animations at the same time.
+     * This is equivalent to calling {@link #play(Animator)} with the first animator in the
+     * set and then {@link Builder#with(Animator)} with each of the other animators. Note that
+     * an Animator with a {@link Animator#setStartDelay(long) startDelay} will not actually
+     * start until that delay elapses, which means that if the first animator in the list
+     * supplied to this constructor has a startDelay, none of the other animators will start
+     * until that first animator's startDelay has elapsed.
      *
      * @param items The animations that will be started simultaneously.
      */
@@ -230,15 +240,21 @@ public final class AnimatorSet extends Animator {
 
     /**
      * Sets the TimeInterpolator for all current {@link #getChildAnimations() child animations}
-     * of this AnimatorSet.
+     * of this AnimatorSet. The default value is null, which means that no interpolator
+     * is set on this AnimatorSet. Setting the interpolator to any non-null value
+     * will cause that interpolator to be set on the child animations
+     * when the set is started.
      *
      * @param interpolator the interpolator to be used by each child animation of this AnimatorSet
      */
     @Override
     public void setInterpolator(TimeInterpolator interpolator) {
-        for (Node node : mNodes) {
-            node.animation.setInterpolator(interpolator);
-        }
+        mInterpolator = interpolator;
+    }
+
+    @Override
+    public TimeInterpolator getInterpolator() {
+        return mInterpolator;
     }
 
     /**
@@ -460,7 +476,12 @@ public final class AnimatorSet extends Animator {
                 node.animation.setDuration(mDuration);
             }
         }
-        // First, sort the nodes (if necessary). This will ensure that sortedNodes
+        if (mInterpolator != null) {
+            for (Node node : mNodes) {
+                node.animation.setInterpolator(mInterpolator);
+            }
+        }
+            // First, sort the nodes (if necessary). This will ensure that sortedNodes
         // contains the animation nodes in the correct order.
         sortNodes();
 
diff --git a/core/java/android/animation/ValueAnimator.java b/core/java/android/animation/ValueAnimator.java
index ea605b9..87b1574 100644
--- a/core/java/android/animation/ValueAnimator.java
+++ b/core/java/android/animation/ValueAnimator.java
@@ -854,6 +854,7 @@ public class ValueAnimator extends Animator {
      *
      * @return The timing interpolator for this ValueAnimator.
      */
+    @Override
     public TimeInterpolator getInterpolator() {
         return mInterpolator;
     }
diff --git a/core/java/android/view/LayoutInflater.java b/core/java/android/view/LayoutInflater.java
index 85695fc..aa43bad 100644
--- a/core/java/android/view/LayoutInflater.java
+++ b/core/java/android/view/LayoutInflater.java
@@ -654,7 +654,7 @@ public abstract class LayoutInflater {
 
     /**
      * Version of {@link #onCreateView(String, AttributeSet)} that also
-     * takes the future parent of the view being constructure.  The default
+     * takes the future parent of the view being constructed.  The default
      * implementation simply calls {@link #onCreateView(String, AttributeSet)}.
      *
      * @param parent The future parent of the returned view.  <em>Note that
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 7c82f7e..4fb2431 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -2758,6 +2758,11 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
 
     TransformationInfo mTransformationInfo;
 
+    /**
+     * Current clip bounds. to which all drawing of this view are constrained.
+     */
+    private Rect mClipBounds = null;
+
     private boolean mLastIsOpaque;
 
     /**
@@ -10103,7 +10108,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
     /**
      * Offset this view's horizontal location by the specified amount of pixels.
      *
-     * @param offset the numer of pixels to offset the view by
+     * @param offset the number of pixels to offset the view by
      */
     public void offsetLeftAndRight(int offset) {
         if (offset != 0) {
@@ -13374,6 +13379,33 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
     }
 
     /**
+     * Sets a rectangular area on this view to which the view will be clipped
+     * it is drawn. Setting the value to null will remove the clip bounds
+     * and the view will draw normally, using its full bounds.
+     *
+     * @param clipBounds The rectangular area, in the local coordinates of
+     * this view, to which future drawing operations will be clipped.
+     */
+    public void setClipBounds(Rect clipBounds) {
+        mClipBounds = clipBounds;
+        if (clipBounds != null) {
+            invalidate(clipBounds);
+        } else {
+            invalidate();
+        }
+    }
+
+    /**
+     * Returns a copy of the current {@link #setClipBounds(Rect) clipBounds}.
+     *
+     * @return A copy of the current clip bounds if clip bounds are set,
+     * otherwise null.
+     */
+    public Rect getClipBounds() {
+        return (mClipBounds != null) ? new Rect(mClipBounds) : null;
+    }
+
+    /**
      * Utility function, called by draw(canvas, parent, drawingTime) to handle the less common
      * case of an active Animation being run on the view.
      */
@@ -13849,6 +13881,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      * @param canvas The Canvas to which the View is rendered.
      */
     public void draw(Canvas canvas) {
+        if (mClipBounds != null) {
+            canvas.clipRect(mClipBounds);
+        }
         final int privateFlags = mPrivateFlags;
         final boolean dirtyOpaque = (privateFlags & PFLAG_DIRTY_MASK) == PFLAG_DIRTY_OPAQUE &&
                 (mAttachInfo == null || !mAttachInfo.mIgnoreDirtyState);
diff --git a/core/java/android/view/ViewGroup.java b/core/java/android/view/ViewGroup.java
index 311d1d0..6da4b62 100644
--- a/core/java/android/view/ViewGroup.java
+++ b/core/java/android/view/ViewGroup.java
@@ -3080,6 +3080,18 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
     }
 
     /**
+     * Returns whether ths group's children are clipped to their bounds before drawing.
+     * The default value is true.
+     * @see #setClipChildren(boolean)
+     *
+     * @return True if the group's children will be clipped to their bounds,
+     * false otherwise.
+     */
+    public boolean getClipChildren() {
+        return ((mGroupFlags & FLAG_CLIP_CHILDREN) != 0);
+    }
+
+    /**
      * By default, children are clipped to their bounds before drawing. This
      * allows view groups to override this behavior for animations, etc.
      *
@@ -4525,7 +4537,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
      */
     @Override
     public final void layout(int l, int t, int r, int b) {
-        if (mTransition == null || !mTransition.isChangingLayout()) {
+        if (!mSuppressLayout && (mTransition == null || !mTransition.isChangingLayout())) {
             if (mTransition != null) {
                 mTransition.layoutChange(this);
             }
diff --git a/core/java/android/view/ViewPropertyAnimator.java b/core/java/android/view/ViewPropertyAnimator.java
index 22f98b7..98df064 100644
--- a/core/java/android/view/ViewPropertyAnimator.java
+++ b/core/java/android/view/ViewPropertyAnimator.java
@@ -16,6 +16,7 @@
 
 package android.view;
 
+import android.animation.Animatable;
 import android.animation.Animator;
 import android.animation.ValueAnimator;
 import android.animation.TimeInterpolator;
@@ -323,6 +324,15 @@ public class ViewPropertyAnimator {
     }
 
     /**
+     * Returns the timing interpolator that this animation uses.
+     *
+     * @return The timing interpolator for this animation.
+     */
+    public TimeInterpolator getInterpolator() {
+        return null;
+    }
+
+    /**
      * Sets a listener for events in the underlying Animators that run the property
      * animations.
      *
diff --git a/core/java/android/widget/ImageView.java b/core/java/android/widget/ImageView.java
index cde6ceb..33fd8ce 100644
--- a/core/java/android/widget/ImageView.java
+++ b/core/java/android/widget/ImageView.java
@@ -348,7 +348,7 @@ public class ImageView extends View {
      * {@link #setImageBitmap(android.graphics.Bitmap)} and
      * {@link android.graphics.BitmapFactory} instead.</p>
      *
-     * @param resId the resource identifier of the the drawable
+     * @param resId the resource identifier of the drawable
      *
      * @attr ref android.R.styleable#ImageView_src
      */