Keyframe.java revision e0ee2e9f3102c3c14c873a75a7b04e49787e0fb9 
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
19/**
20 * This class holds a time/value pair for an animation. The Keyframe class is used
21 * by {@link ValueAnimator} to define the values that the animation target will have over the course
22 * of the animation. As the time proceeds from one keyframe to the other, the value of the
23 * target object will animate between the value at the previous keyframe and the value at the
24 * next keyframe. Each keyframe also holds an optional {@link TimeInterpolator}
25 * object, which defines the time interpolation over the intervalue preceding the keyframe.
26 */
27public class Keyframe implements Cloneable {
28    /**
29     * The time at which mValue will hold true.
30     */
31    private float mFraction;
32
33    /**
34     * The value of the animation at the time mFraction.
35     */
36    private Object mValue;
37
38    /**
39     * The type of the value in this Keyframe. This type is determined at construction time,
40     * based on the type of the <code>value</code> object passed into the constructor.
41     */
42    private Class mValueType;
43
44    /**
45     * The optional time interpolator for the interval preceding this keyframe. A null interpolator
46     * (the default) results in linear interpolation over the interval.
47     */
48    private TimeInterpolator mInterpolator = null;
49
50    /**
51     * Private constructor, called from the public constructors with the additional
52     * <code>valueType</code> parameter.
53     *
54     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
55     * of time elapsed of the overall animation duration.
56     * @param value The value that the object will animate to as the animation time approaches
57     * the time in this keyframe, and the the value animated from as the time passes the time in
58     * this keyframe.
59     * @param valueType The type of the <code>value</code> object. This is used by the
60     * {@link #getValue()} functionm, which is queried by {@link ValueAnimator} to determine
61     * the type of {@link TypeEvaluator} to use to interpolate between values.
62     */
63    private Keyframe(float fraction, Object value, Class valueType) {
64        mFraction = fraction;
65        mValue = value;
66        mValueType = valueType;
67    }
68
69    /**
70     * Constructs a Keyframe object with the given time and value. The time defines the
71     * time, as a proportion of an overall animation's duration, at which the value will hold true
72     * for the animation. The value for the animation between keyframes will be calculated as
73     * an interpolation between the values at those keyframes.
74     *
75     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
76     * of time elapsed of the overall animation duration.
77     * @param value The value that the object will animate to as the animation time approaches
78     * the time in this keyframe, and the the value animated from as the time passes the time in
79     * this keyframe.
80     */
81    public Keyframe(float fraction, Object value) {
82        this(fraction, value, (value != null) ? value.getClass() : Object.class);
83    }
84
85    /**
86     * Constructs a Keyframe object with the given time and float value. The time defines the
87     * time, as a proportion of an overall animation's duration, at which the value will hold true
88     * for the animation. The value for the animation between keyframes will be calculated as
89     * an interpolation between the values at those keyframes.
90     *
91     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
92     * of time elapsed of the overall animation duration.
93     * @param value The value that the object will animate to as the animation time approaches
94     * the time in this keyframe, and the the value animated from as the time passes the time in
95     * this keyframe.
96     */
97    public Keyframe(float fraction, Float value) {
98        this(fraction, value, Float.class);
99    }
100
101    /**
102     * Constructs a Keyframe object with the given time and integer value. The time defines the
103     * time, as a proportion of an overall animation's duration, at which the value will hold true
104     * for the animation. The value for the animation between keyframes will be calculated as
105     * an interpolation between the values at those keyframes.
106     *
107     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
108     * of time elapsed of the overall animation duration.
109     * @param value The value that the object will animate to as the animation time approaches
110     * the time in this keyframe, and the the value animated from as the time passes the time in
111     * this keyframe.
112     */
113    public Keyframe(float fraction, Integer value) {
114        this(fraction, value, Integer.class);
115    }
116
117    /**
118     * Constructs a Keyframe object with the given time and double value. The time defines the
119     * time, as a proportion of an overall animation's duration, at which the value will hold true
120     * for the animation. The value for the animation between keyframes will be calculated as
121     * an interpolation between the values at those keyframes.
122     *
123     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
124     * of time elapsed of the overall animation duration.
125     * @param value The value that the object will animate to as the animation time approaches
126     * the time in this keyframe, and the the value animated from as the time passes the time in
127     * this keyframe.
128     */
129    public Keyframe(float fraction, Double value) {
130        this(fraction, value, Double.class);
131    }
132
133    /**
134     * Constructs a Keyframe object with the given time and integer value. The time defines the
135     * time, as a proportion of an overall animation's duration, at which the value will hold true
136     * for the animation. The value for the animation between keyframes will be calculated as
137     * an interpolation between the values at those keyframes.
138     *
139     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
140     * of time elapsed of the overall animation duration.
141     * @param value The value that the object will animate to as the animation time approaches
142     * the time in this keyframe, and the the value animated from as the time passes the time in
143     * this keyframe.
144     */
145    public Keyframe(float fraction, int value) {
146        this(fraction, value, int.class);
147    }
148
149    /**
150     * Constructs a Keyframe object with the given time and float value. The time defines the
151     * time, as a proportion of an overall animation's duration, at which the value will hold true
152     * for the animation. The value for the animation between keyframes will be calculated as
153     * an interpolation between the values at those keyframes.
154     *
155     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
156     * of time elapsed of the overall animation duration.
157     * @param value The value that the object will animate to as the animation time approaches
158     * the time in this keyframe, and the the value animated from as the time passes the time in
159     * this keyframe.
160     */
161    public Keyframe(float fraction, float value) {
162        this(fraction, value, float.class);
163    }
164
165    /**
166     * Constructs a Keyframe object with the given time and double value. The time defines the
167     * time, as a proportion of an overall animation's duration, at which the value will hold true
168     * for the animation. The value for the animation between keyframes will be calculated as
169     * an interpolation between the values at those keyframes.
170     *
171     * @param fraction The time, expressed as a value between 0 and 1, representing the fraction
172     * of time elapsed of the overall animation duration.
173     * @param value The value that the object will animate to as the animation time approaches
174     * the time in this keyframe, and the the value animated from as the time passes the time in
175     * this keyframe.
176     */
177    public Keyframe(float fraction, double value) {
178        this(fraction, value, double.class);
179    }
180
181    /**
182     * Gets the value for this Keyframe.
183     *
184     * @return The value for this Keyframe.
185     */
186    public Object getValue() {
187        return mValue;
188    }
189
190    /**
191     * Sets the value for this Keyframe.
192     *
193     * @param value value for this Keyframe.
194     */
195    public void setValue(Object value) {
196        mValue = value;
197    }
198
199    /**
200     * Gets the time for this keyframe, as a fraction of the overall animation duration.
201     *
202     * @return The time associated with this keyframe, as a fraction of the overall animation
203     * duration. This should be a value between 0 and 1.
204     */
205    public float getFraction() {
206        return mFraction;
207    }
208
209    /**
210     * Sets the time for this keyframe, as a fraction of the overall animation duration.
211     *
212     * @param fraction time associated with this keyframe, as a fraction of the overall animation
213     * duration. This should be a value between 0 and 1.
214     */
215    public void setFraction(float fraction) {
216        mFraction = fraction;
217    }
218
219    /**
220     * Gets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
221     * that there is no interpolation, which is the same as linear interpolation.
222     *
223     * @return The optional interpolator for this Keyframe.
224     */
225    public TimeInterpolator getInterpolator() {
226        return mInterpolator;
227    }
228
229    /**
230     * Sets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
231     * that there is no interpolation, which is the same as linear interpolation.
232     *
233     * @return The optional interpolator for this Keyframe.
234     */
235    public void setInterpolator(TimeInterpolator interpolator) {
236        mInterpolator = interpolator;
237    }
238
239    /**
240     * Gets the type of keyframe. This information is used by ValueAnimator to determine the type of
241     * {@link TypeEvaluator} to use when calculating values between keyframes. The type is based
242     * on the type of Keyframe created.
243     *
244     * @return The type of the value stored in the Keyframe.
245     */
246    public Class getType() {
247        return mValueType;
248    }
249
250    @Override
251    public Keyframe clone() {
252        Keyframe kfClone = new Keyframe(mFraction, mValue, mValueType);
253        kfClone.setInterpolator(mInterpolator);
254        return kfClone;
255    }
256}
257