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