ObjectAnimator.java revision 2794eb3b02e2404d453d3ad22a8a85a138130a07
1/* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.animation; 18 19import android.util.Log; 20 21import java.lang.reflect.Method; 22 23/** 24 * This subclass of {@link ValueAnimator} provides support for animating properties on target objects. 25 * The constructors of this class take parameters to define the target object that will be animated 26 * as well as the name of the property that will be animated. Appropriate set/get functions 27 * are then determined internally and the animation will call these functions as necessary to 28 * animate the property. 29 */ 30public final class ObjectAnimator extends ValueAnimator { 31 32 // The target object on which the property exists, set in the constructor 33 private Object mTarget; 34 35 private String mPropertyName; 36 37 /** 38 * Sets the name of the property that will be animated. This name is used to derive 39 * a setter function that will be called to set animated values. 40 * For example, a property name of <code>foo</code> will result 41 * in a call to the function <code>setFoo()</code> on the target object. If either 42 * <code>valueFrom</code> or <code>valueTo</code> is null, then a getter function will 43 * also be derived and called. 44 * 45 * <p>Note that the setter function derived from this property name 46 * must take the same parameter type as the 47 * <code>valueFrom</code> and <code>valueTo</code> properties, otherwise the call to 48 * the setter function will fail.</p> 49 * 50 * <p>If this ObjectAnimator has been set up to animate several properties together, 51 * using more than one PropertyValuesHolder objects, then setting the propertyName simply 52 * sets the propertyName in the first of those PropertyValuesHolder objects.</p> 53 * 54 * @param propertyName The name of the property being animated. 55 */ 56 public void setPropertyName(String propertyName) { 57 // mValues could be null if this is being constructed piecemeal. Just record the 58 // propertyName to be used later when setValues() is called if so. 59 if (mValues != null) { 60 PropertyValuesHolder valuesHolder = mValues[0]; 61 String oldName = valuesHolder.getPropertyName(); 62 valuesHolder.setPropertyName(propertyName); 63 mValuesMap.remove(oldName); 64 mValuesMap.put(propertyName, valuesHolder); 65 } 66 mPropertyName = propertyName; 67 // New property/values/target should cause re-initialization prior to starting 68 mInitialized = false; 69 } 70 71 /** 72 * Gets the name of the property that will be animated. This name will be used to derive 73 * a setter function that will be called to set animated values. 74 * For example, a property name of <code>foo</code> will result 75 * in a call to the function <code>setFoo()</code> on the target object. If either 76 * <code>valueFrom</code> or <code>valueTo</code> is null, then a getter function will 77 * also be derived and called. 78 */ 79 public String getPropertyName() { 80 return mPropertyName; 81 } 82 83 /** 84 * Determine the setter or getter function using the JavaBeans convention of setFoo or 85 * getFoo for a property named 'foo'. This function figures out what the name of the 86 * function should be and uses reflection to find the Method with that name on the 87 * target object. 88 * 89 * @param prefix "set" or "get", depending on whether we need a setter or getter. 90 * @return Method the method associated with mPropertyName. 91 */ 92 private Method getPropertyFunction(String prefix, Class valueType) { 93 // TODO: faster implementation... 94 Method returnVal = null; 95 String firstLetter = mPropertyName.substring(0, 1); 96 String theRest = mPropertyName.substring(1); 97 firstLetter = firstLetter.toUpperCase(); 98 String setterName = prefix + firstLetter + theRest; 99 Class args[] = null; 100 if (valueType != null) { 101 args = new Class[1]; 102 args[0] = valueType; 103 } 104 try { 105 returnVal = mTarget.getClass().getMethod(setterName, args); 106 } catch (NoSuchMethodException e) { 107 Log.e("ObjectAnimator", 108 "Couldn't find setter/getter for property " + mPropertyName + ": " + e); 109 } 110 return returnVal; 111 } 112 113 /** 114 * Creates a new ObjectAnimator object. This default constructor is primarily for 115 * use internally; the other constructors which take parameters are more generally 116 * useful. 117 */ 118 public ObjectAnimator() { 119 } 120 121 /** 122 * A constructor that takes a single property name and set of values. This constructor is 123 * used in the simple case of animating a single property. 124 * 125 * @param target The object whose property is to be animated. This object should 126 * have a public method on it called <code>setName()</code>, where <code>name</code> is 127 * the value of the <code>propertyName</code> parameter. 128 * @param propertyName The name of the property being animated. 129 */ 130 private ObjectAnimator(Object target, String propertyName) { 131 mTarget = target; 132 setPropertyName(propertyName); 133 } 134 135 /** 136 * Constructs and returns an ObjectAnimator that animates between int values. A single 137 * value implies that that value is the one being animated to. However, this is not typically 138 * useful in a ValueAnimator object because there is no way for the object to determine the 139 * starting value for the animation (unlike ObjectAnimator, which can derive that value 140 * from the target object and property being animated). Therefore, there should typically 141 * be two or more values. 142 * 143 * @param target The object whose property is to be animated. This object should 144 * have a public method on it called <code>setName()</code>, where <code>name</code> is 145 * the value of the <code>propertyName</code> parameter. 146 * @param propertyName The name of the property being animated. 147 * @param values A set of values that the animation will animate between over time. 148 * @return A ValueAnimator object that is set up to animate between the given values. 149 */ 150 public static ObjectAnimator ofInt(Object target, String propertyName, int... values) { 151 ObjectAnimator anim = new ObjectAnimator(target, propertyName); 152 anim.setIntValues(values); 153 return anim; 154 } 155 156 /** 157 * Constructs and returns an ObjectAnimator that animates between float values. A single 158 * value implies that that value is the one being animated to. However, this is not typically 159 * useful in a ValueAnimator object because there is no way for the object to determine the 160 * starting value for the animation (unlike ObjectAnimator, which can derive that value 161 * from the target object and property being animated). Therefore, there should typically 162 * be two or more values. 163 * 164 * @param target The object whose property is to be animated. This object should 165 * have a public method on it called <code>setName()</code>, where <code>name</code> is 166 * the value of the <code>propertyName</code> parameter. 167 * @param propertyName The name of the property being animated. 168 * @param values A set of values that the animation will animate between over time. 169 * @return A ValueAnimator object that is set up to animate between the given values. 170 */ 171 public static ObjectAnimator ofFloat(Object target, String propertyName, float... values) { 172 ObjectAnimator anim = new ObjectAnimator(target, propertyName); 173 anim.setFloatValues(values); 174 return anim; 175 } 176 177 /** 178 * Constructs and returns an ObjectAnimator that animates between long values. A single 179 * value implies that that value is the one being animated to. However, this is not typically 180 * useful in a ValueAnimator object because there is no way for the object to determine the 181 * starting value for the animation (unlike ObjectAnimator, which can derive that value 182 * from the target object and property being animated). Therefore, there should typically 183 * be two or more values. 184 * 185 * @param target The object whose property is to be animated. This object should 186 * have a public method on it called <code>setName()</code>, where <code>name</code> is 187 * the value of the <code>propertyName</code> parameter. 188 * @param propertyName The name of the property being animated. 189 * @param values A set of values that the animation will animate between over time. 190 * @return A ValueAnimator object that is set up to animate between the given values. 191 */ 192 public static ObjectAnimator ofLong(Object target, String propertyName, long... values) { 193 ObjectAnimator anim = new ObjectAnimator(target, propertyName); 194 anim.setLongValues(values); 195 return anim; 196 } 197 198 /** 199 * Constructs and returns an ObjectAnimator that animates between double values. A single 200 * value implies that that value is the one being animated to. However, this is not typically 201 * useful in a ValueAnimator object because there is no way for the object to determine the 202 * starting value for the animation (unlike ObjectAnimator, which can derive that value 203 * from the target object and property being animated). Therefore, there should typically 204 * be two or more values. 205 * 206 * @param target The object whose property is to be animated. This object should 207 * have a public method on it called <code>setName()</code>, where <code>name</code> is 208 * the value of the <code>propertyName</code> parameter. 209 * @param propertyName The name of the property being animated. 210 * @param values A set of values that the animation will animate between over time. 211 * @return A ValueAnimator object that is set up to animate between the given values. 212 */ 213 public static ObjectAnimator ofDouble(Object target, String propertyName, double... values) { 214 ObjectAnimator anim = new ObjectAnimator(target, propertyName); 215 anim.setDoubleValues(values); 216 return anim; 217 } 218 219 /** 220 * A constructor that takes <code>PropertyValueHolder</code> values. This constructor should 221 * be used when animating several properties at once with the same ObjectAnimator, since 222 * PropertyValuesHolder allows you to associate a set of animation values with a property 223 * name. 224 * 225 * @param target The object whose property is to be animated. This object should 226 * have public methods on it called <code>setName()</code>, where <code>name</code> is 227 * the name of the property passed in as the <code>propertyName</code> parameter for 228 * each of the PropertyValuesHolder objects. 229 * @param propertyName The name of the property being animated. 230 * @param evaluator A TypeEvaluator that will be called on each animation frame to 231 * provide the ncessry interpolation between the Object values to derive the animated 232 * value. 233 * @param values The PropertyValuesHolder objects which hold each the property name and values 234 * to animate that property between. 235 */ 236 public static ObjectAnimator ofObject(Object target, String propertyName, 237 TypeEvaluator evaluator, Object... values) { 238 ObjectAnimator anim = new ObjectAnimator(target, propertyName); 239 anim.setObjectValues(values); 240 anim.setEvaluator(evaluator); 241 return anim; 242 } 243 244 /** 245 * Constructs and returns an ObjectAnimator that animates between the sets of values 246 * specifed in <code>PropertyValueHolder</code> objects. This variant should 247 * be used when animating several properties at once with the same ObjectAnimator, since 248 * PropertyValuesHolder allows you to associate a set of animation values with a property 249 * name. 250 * 251 * @param target The object whose property is to be animated. This object should 252 * have public methods on it called <code>setName()</code>, where <code>name</code> is 253 * the name of the property passed in as the <code>propertyName</code> parameter for 254 * each of the PropertyValuesHolder objects. 255 * @param values A set of PropertyValuesHolder objects whose values will be animated 256 * between over time. 257 * @return A ValueAnimator object that is set up to animate between the given values. 258 */ 259 public static ObjectAnimator ofPropertyValuesHolder(Object target, 260 PropertyValuesHolder... values) { 261 ObjectAnimator anim = new ObjectAnimator(); 262 anim.mTarget = target; 263 anim.setValues(values); 264 return anim; 265 } 266 267 @Override 268 public void setIntValues(int... values) { 269 if (mValues == null || mValues.length == 0) { 270 // No values yet - this animator is being constructed piecemeal. Init the values with 271 // whatever the current propertyName is 272 setValues(PropertyValuesHolder.ofInt(mPropertyName, values)); 273 } else { 274 super.setIntValues(values); 275 } 276 } 277 278 @Override 279 public void setFloatValues(float... values) { 280 if (mValues == null || mValues.length == 0) { 281 // No values yet - this animator is being constructed piecemeal. Init the values with 282 // whatever the current propertyName is 283 setValues(PropertyValuesHolder.ofFloat(mPropertyName, values)); 284 } else { 285 super.setFloatValues(values); 286 } 287 } 288 289 @Override 290 public void setDoubleValues(double... values) { 291 if (mValues == null || mValues.length == 0) { 292 // No values yet - this animator is being constructed piecemeal. Init the values with 293 // whatever the current propertyName is 294 setValues(PropertyValuesHolder.ofDouble(mPropertyName, values)); 295 } else { 296 super.setDoubleValues(values); 297 } 298 } 299 300 @Override 301 public void setLongValues(long... values) { 302 if (mValues == null || mValues.length == 0) { 303 // No values yet - this animator is being constructed piecemeal. Init the values with 304 // whatever the current propertyName is 305 setValues(PropertyValuesHolder.ofLong(mPropertyName, values)); 306 } else { 307 super.setLongValues(values); 308 } 309 } 310 311 @Override 312 public void setObjectValues(Object... values) { 313 if (mValues == null || mValues.length == 0) { 314 // No values yet - this animator is being constructed piecemeal. Init the values with 315 // whatever the current propertyName is 316 setValues(PropertyValuesHolder.ofObject(mPropertyName, (TypeEvaluator)null, values)); 317 } else { 318 super.setObjectValues(values); 319 } 320 } 321 322 /** 323 * This function is called immediately before processing the first animation 324 * frame of an animation. If there is a nonzero <code>startDelay</code>, the 325 * function is called after that delay ends. 326 * It takes care of the final initialization steps for the 327 * animation. This includes setting mEvaluator, if the user has not yet 328 * set it up, and the setter/getter methods, if the user did not supply 329 * them. 330 * 331 * <p>Overriders of this method should call the superclass method to cause 332 * internal mechanisms to be set up correctly.</p> 333 */ 334 @Override 335 void initAnimation() { 336 if (!mInitialized) { 337 // mValueType may change due to setter/getter setup; do this before calling super.init(), 338 // which uses mValueType to set up the default type evaluator. 339 int numValues = mValues.length; 340 for (int i = 0; i < numValues; ++i) { 341 mValues[i].setupSetterAndGetter(mTarget); 342 } 343 super.initAnimation(); 344 } 345 } 346 347 /** 348 * Sets the length of the animation. The default duration is 300 milliseconds. 349 * 350 * @param duration The length of the animation, in milliseconds. 351 * @return ObjectAnimator The object called with setDuration(). This return 352 * value makes it easier to compose statements together that construct and then set the 353 * duration, as in 354 * <code>ObjectAnimator.ofInt(target, propertyName, 0, 10).setDuration(500).start()</code>. 355 */ 356 @Override 357 public ObjectAnimator setDuration(long duration) { 358 super.setDuration(duration); 359 return this; 360 } 361 362 363 /** 364 * The target object whose property will be animated by this animation 365 * 366 * @return The object being animated 367 */ 368 public Object getTarget() { 369 return mTarget; 370 } 371 372 /** 373 * Sets the target object whose property will be animated by this animation 374 * 375 * @param target The object being animated 376 */ 377 @Override 378 public void setTarget(Object target) { 379 mTarget = target; 380 // New property/values/target should cause re-initialization prior to starting 381 mInitialized = false; 382 } 383 384 @Override 385 public void setupStartValues() { 386 initAnimation(); 387 int numValues = mValues.length; 388 for (int i = 0; i < numValues; ++i) { 389 mValues[i].setupStartValue(mTarget); 390 } 391 } 392 393 @Override 394 public void setupEndValues() { 395 initAnimation(); 396 int numValues = mValues.length; 397 for (int i = 0; i < numValues; ++i) { 398 mValues[i].setupEndValue(mTarget); 399 } 400 } 401 402 /** 403 * This method is called with the elapsed fraction of the animation during every 404 * animation frame. This function turns the elapsed fraction into an interpolated fraction 405 * and then into an animated value (from the evaluator. The function is called mostly during 406 * animation updates, but it is also called when the <code>end()</code> 407 * function is called, to set the final value on the property. 408 * 409 * <p>Overrides of this method must call the superclass to perform the calculation 410 * of the animated value.</p> 411 * 412 * @param fraction The elapsed fraction of the animation. 413 */ 414 @Override 415 void animateValue(float fraction) { 416 super.animateValue(fraction); 417 int numValues = mValues.length; 418 for (int i = 0; i < numValues; ++i) { 419 mValues[i].setAnimatedValue(mTarget); 420 } 421 } 422 423 @Override 424 public ObjectAnimator clone() { 425 final ObjectAnimator anim = (ObjectAnimator) super.clone(); 426 return anim; 427 } 428} 429