2 * Copyright (C) 2010 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package com.actionbarsherlock.internal.nineoldandroids.animation;
19 import android.view.animation.Interpolator;
22 * This class holds a time/value pair for an animation. The Keyframe class is used
23 * by {@link ValueAnimator} to define the values that the animation target will have over the course
24 * of the animation. As the time proceeds from one keyframe to the other, the value of the
25 * target object will animate between the value at the previous keyframe and the value at the
26 * next keyframe. Each keyframe also holds an optional {@link TimeInterpolator}
27 * object, which defines the time interpolation over the intervalue preceding the keyframe.
29 * <p>The Keyframe class itself is abstract. The type-specific factory methods will return
30 * a subclass of Keyframe specific to the type of value being stored. This is done to improve
31 * performance when dealing with the most common cases (e.g., <code>float</code> and
32 * <code>int</code> values). Other types will fall into a more general Keyframe class that
33 * treats its values as Objects. Unless your animation requires dealing with a custom type
34 * or a data structure that needs to be animated directly (and evaluated using an implementation
35 * of {@link TypeEvaluator}), you should stick to using float and int as animations using those
36 * types have lower runtime overhead than other types.</p>
38 @SuppressWarnings("rawtypes")
39 public abstract class Keyframe implements Cloneable {
41 * The time at which mValue will hold true.
46 * The type of the value in this Keyframe. This type is determined at construction time,
47 * based on the type of the <code>value</code> object passed into the constructor.
52 * The optional time interpolator for the interval preceding this keyframe. A null interpolator
53 * (the default) results in linear interpolation over the interval.
55 private /*Time*/Interpolator mInterpolator = null;
58 * Flag to indicate whether this keyframe has a valid value. This flag is used when an
59 * animation first starts, to populate placeholder keyframes with real values derived
60 * from the target object.
62 boolean mHasValue = false;
65 * Constructs a Keyframe object with the given time and value. The time defines the
66 * time, as a proportion of an overall animation's duration, at which the value will hold true
67 * for the animation. The value for the animation between keyframes will be calculated as
68 * an interpolation between the values at those keyframes.
70 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
71 * of time elapsed of the overall animation duration.
72 * @param value The value that the object will animate to as the animation time approaches
73 * the time in this keyframe, and the the value animated from as the time passes the time in
76 public static Keyframe ofInt(float fraction, int value) {
77 return new IntKeyframe(fraction, value);
81 * Constructs a Keyframe object with the given time. The value at this time will be derived
82 * from the target object when the animation first starts (note that this implies that keyframes
83 * with no initial value must be used as part of an {@link ObjectAnimator}).
84 * The time defines the
85 * time, as a proportion of an overall animation's duration, at which the value will hold true
86 * for the animation. The value for the animation between keyframes will be calculated as
87 * an interpolation between the values at those keyframes.
89 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
90 * of time elapsed of the overall animation duration.
92 public static Keyframe ofInt(float fraction) {
93 return new IntKeyframe(fraction);
97 * Constructs a Keyframe object with the given time and value. The time defines the
98 * time, as a proportion of an overall animation's duration, at which the value will hold true
99 * for the animation. The value for the animation between keyframes will be calculated as
100 * an interpolation between the values at those keyframes.
102 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
103 * of time elapsed of the overall animation duration.
104 * @param value The value that the object will animate to as the animation time approaches
105 * the time in this keyframe, and the the value animated from as the time passes the time in
108 public static Keyframe ofFloat(float fraction, float value) {
109 return new FloatKeyframe(fraction, value);
113 * Constructs a Keyframe object with the given time. The value at this time will be derived
114 * from the target object when the animation first starts (note that this implies that keyframes
115 * with no initial value must be used as part of an {@link ObjectAnimator}).
116 * The time defines the
117 * time, as a proportion of an overall animation's duration, at which the value will hold true
118 * for the animation. The value for the animation between keyframes will be calculated as
119 * an interpolation between the values at those keyframes.
121 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
122 * of time elapsed of the overall animation duration.
124 public static Keyframe ofFloat(float fraction) {
125 return new FloatKeyframe(fraction);
129 * Constructs a Keyframe object with the given time and value. The time defines the
130 * time, as a proportion of an overall animation's duration, at which the value will hold true
131 * for the animation. The value for the animation between keyframes will be calculated as
132 * an interpolation between the values at those keyframes.
134 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
135 * of time elapsed of the overall animation duration.
136 * @param value The value that the object will animate to as the animation time approaches
137 * the time in this keyframe, and the the value animated from as the time passes the time in
140 public static Keyframe ofObject(float fraction, Object value) {
141 return new ObjectKeyframe(fraction, value);
145 * Constructs a Keyframe object with the given time. The value at this time will be derived
146 * from the target object when the animation first starts (note that this implies that keyframes
147 * with no initial value must be used as part of an {@link ObjectAnimator}).
148 * The time defines the
149 * time, as a proportion of an overall animation's duration, at which the value will hold true
150 * for the animation. The value for the animation between keyframes will be calculated as
151 * an interpolation between the values at those keyframes.
153 * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
154 * of time elapsed of the overall animation duration.
156 public static Keyframe ofObject(float fraction) {
157 return new ObjectKeyframe(fraction, null);
161 * Indicates whether this keyframe has a valid value. This method is called internally when
162 * an {@link ObjectAnimator} first starts; keyframes without values are assigned values at
163 * that time by deriving the value for the property from the target object.
165 * @return boolean Whether this object has a value assigned.
167 public boolean hasValue() {
172 * Gets the value for this Keyframe.
174 * @return The value for this Keyframe.
176 public abstract Object getValue();
179 * Sets the value for this Keyframe.
181 * @param value value for this Keyframe.
183 public abstract void setValue(Object value);
186 * Gets the time for this keyframe, as a fraction of the overall animation duration.
188 * @return The time associated with this keyframe, as a fraction of the overall animation
189 * duration. This should be a value between 0 and 1.
191 public float getFraction() {
196 * Sets the time for this keyframe, as a fraction of the overall animation duration.
198 * @param fraction time associated with this keyframe, as a fraction of the overall animation
199 * duration. This should be a value between 0 and 1.
201 public void setFraction(float fraction) {
202 mFraction = fraction;
206 * Gets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
207 * that there is no interpolation, which is the same as linear interpolation.
209 * @return The optional interpolator for this Keyframe.
211 public /*Time*/Interpolator getInterpolator() {
212 return mInterpolator;
216 * Sets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
217 * that there is no interpolation, which is the same as linear interpolation.
219 * @return The optional interpolator for this Keyframe.
221 public void setInterpolator(/*Time*/Interpolator interpolator) {
222 mInterpolator = interpolator;
226 * Gets the type of keyframe. This information is used by ValueAnimator to determine the type of
227 * {@link TypeEvaluator} to use when calculating values between keyframes. The type is based
228 * on the type of Keyframe created.
230 * @return The type of the value stored in the Keyframe.
232 public Class getType() {
237 public abstract Keyframe clone();
240 * This internal subclass is used for all types which are not int or float.
242 static class ObjectKeyframe extends Keyframe {
245 * The value of the animation at the time mFraction.
249 ObjectKeyframe(float fraction, Object value) {
250 mFraction = fraction;
252 mHasValue = (value != null);
253 mValueType = mHasValue ? value.getClass() : Object.class;
256 public Object getValue() {
260 public void setValue(Object value) {
262 mHasValue = (value != null);
266 public ObjectKeyframe clone() {
267 ObjectKeyframe kfClone = new ObjectKeyframe(getFraction(), mValue);
268 kfClone.setInterpolator(getInterpolator());
274 * Internal subclass used when the keyframe value is of type int.
276 static class IntKeyframe extends Keyframe {
279 * The value of the animation at the time mFraction.
283 IntKeyframe(float fraction, int value) {
284 mFraction = fraction;
286 mValueType = int.class;
290 IntKeyframe(float fraction) {
291 mFraction = fraction;
292 mValueType = int.class;
295 public int getIntValue() {
299 public Object getValue() {
303 public void setValue(Object value) {
304 if (value != null && value.getClass() == Integer.class) {
305 mValue = ((Integer)value).intValue();
311 public IntKeyframe clone() {
312 IntKeyframe kfClone = new IntKeyframe(getFraction(), mValue);
313 kfClone.setInterpolator(getInterpolator());
319 * Internal subclass used when the keyframe value is of type float.
321 static class FloatKeyframe extends Keyframe {
323 * The value of the animation at the time mFraction.
327 FloatKeyframe(float fraction, float value) {
328 mFraction = fraction;
330 mValueType = float.class;
334 FloatKeyframe(float fraction) {
335 mFraction = fraction;
336 mValueType = float.class;
339 public float getFloatValue() {
343 public Object getValue() {
347 public void setValue(Object value) {
348 if (value != null && value.getClass() == Float.class) {
349 mValue = ((Float)value).floatValue();
355 public FloatKeyframe clone() {
356 FloatKeyframe kfClone = new FloatKeyframe(getFraction(), mValue);
357 kfClone.setInterpolator(getInterpolator());