Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fa21bdfd authored by Chet Haase's avatar Chet Haase
Browse files

Document behavior of object references in Animator classes 

Animators that are created with Object values may have undefined
behavior when those objects are changed outside of the animator itself.
For example, an animator created with a start Rect and end Rect
will animate the bounds between those two objects. But if the caller
changes either the start or end rect before or during the animation,
that will affect the values used on every frame of the animation.

Issue #28304520 Strange interpolation of property values holder values

Change-Id: Id6ac19c8369ae34450e6b53d68f5e492b27c577e
parent 3053c3f2

core/java/android/animation/ObjectAnimator.java

+15 −0
Original line number Diff line number Diff line
@@ -585,6 +585,11 @@ public final class ObjectAnimator extends ValueAnimator { 
     * along the way, and an ending value (these values will be distributed evenly across

     * the duration of the animation).

     *

     * <p><strong>Note:</strong> The values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the animator. If the objects will be mutated externally after

     * this method is called, callers should pass a copy of those objects instead.

     *

     * @param target The object whose property is to be animated. This object should

     * have a public method on it called <code>setName()</code>, where <code>name</code> is

     * the value of the <code>propertyName</code> parameter.
@@ -635,6 +640,11 @@ public final class ObjectAnimator extends ValueAnimator { 
     * along the way, and an ending value (these values will be distributed evenly across

     * the duration of the animation).

     *

     * <p><strong>Note:</strong> The values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the animator. If the objects will be mutated externally after

     * this method is called, callers should pass a copy of those objects instead.

     *

     * @param target The object whose property is to be animated.

     * @param property The property being animated.

     * @param evaluator A TypeEvaluator that will be called on each animation frame to
@@ -663,6 +673,11 @@ public final class ObjectAnimator extends ValueAnimator { 
     * supplied, the <code>TypeConverter</code> must be a

     * {@link android.animation.BidirectionalTypeConverter} to retrieve the current value.

     *

     * <p><strong>Note:</strong> The values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the animator. If the objects will be mutated externally after

     * this method is called, callers should pass a copy of those objects instead.

     *

     * @param target The object whose property is to be animated.

     * @param property The property being animated.

     * @param converter Converts the animated object to the Property type.

core/java/android/animation/PropertyValuesHolder.java

+21 −1
Original line number Diff line number Diff line
@@ -388,6 +388,11 @@ public class PropertyValuesHolder implements Cloneable { 
     * set of Object values. This variant also takes a TypeEvaluator because the system

     * cannot automatically interpolate between objects of unknown type.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally

     * after this method is called, callers should pass a copy of those objects instead.

     *

     * @param propertyName The name of the property being animated.

     * @param evaluator A TypeEvaluator that will be called on each animation frame to

     * provide the necessary interpolation between the Object values to derive the animated
@@ -433,6 +438,11 @@ public class PropertyValuesHolder implements Cloneable { 
     * set of Object values. This variant also takes a TypeEvaluator because the system

     * cannot automatically interpolate between objects of unknown type.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally

     * after this method is called, callers should pass a copy of those objects instead.

     *

     * @param property The property being animated. Should not be null.

     * @param evaluator A TypeEvaluator that will be called on each animation frame to

     * provide the necessary interpolation between the Object values to derive the animated
@@ -458,6 +468,11 @@ public class PropertyValuesHolder implements Cloneable { 
     * must be a {@link android.animation.BidirectionalTypeConverter} to retrieve the current

     * value.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally

     * after this method is called, callers should pass a copy of those objects instead.

     *

     * @param property The property being animated. Should not be null.

     * @param converter Converts the animated object to the Property type.

     * @param evaluator A TypeEvaluator that will be called on each animation frame to
@@ -637,6 +652,11 @@ public class PropertyValuesHolder implements Cloneable { 
     * derived automatically from <code>propertyName</code>, since otherwise PropertyValuesHolder has

     * no way of determining what the value should be.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the PropertyValuesHolder. If the objects will be mutated externally

     * after this method is called, callers should pass a copy of those objects instead.

     *

     * @param values One or more values that the animation will animate between.

     */

    public void setObjectValues(Object... values) {

core/java/android/animation/ValueAnimator.java

+10 −0
Original line number Diff line number Diff line
@@ -353,6 +353,11 @@ public class ValueAnimator extends Animator implements AnimationHandler.Animatio 
     * from the target object and property being animated). Therefore, there should typically

     * be two or more values.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the animator. If the objects will be mutated externally after

     * this method is called, callers should pass a copy of those objects instead.

     *

     * <p>Since ValueAnimator does not know how to animate between arbitrary Objects, this

     * factory method also takes a TypeEvaluator object that the ValueAnimator will use

     * to perform that interpolation.
@@ -434,6 +439,11 @@ public class ValueAnimator extends Animator implements AnimationHandler.Animatio 
     * from the target object and property being animated). Therefore, there should typically

     * be two or more values.

     *

     * <p><strong>Note:</strong> The Object values are stored as references to the original

     * objects, which means that changes to those objects after this method is called will

     * affect the values on the animator. If the objects will be mutated externally after

     * this method is called, callers should pass a copy of those objects instead.

     *

     * <p>If there are already multiple sets of values defined for this ValueAnimator via more

     * than one PropertyValuesHolder object, this method will set the values for the first

     * of those objects.</p>