1 /*
2 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javafx.animation;
27
28 import javafx.beans.NamedArg;
29 import javafx.beans.value.WritableBooleanValue;
30 import javafx.beans.value.WritableDoubleValue;
31 import javafx.beans.value.WritableFloatValue;
32 import javafx.beans.value.WritableIntegerValue;
33 import javafx.beans.value.WritableLongValue;
34 import javafx.beans.value.WritableNumberValue;
35 import javafx.beans.value.WritableValue;
36
37 /**
38 * Defines a key value to be interpolated for a particular interval along the
39 * animation. A {@link KeyFrame}, which defines a specific point on a timeline,
40 * can hold multiple {@code KeyValues}. {@code KeyValue} is an immutable class.
41 * <p>
42 * A {@code KeyValue} is defined by a target, which is an implementation of
43 * {@link javafx.beans.value.WritableValue}, an end value and an
44 * {@link Interpolator}.
45 * <p>
46 * Most interpolators define the interpolation between two {@code KeyFrames}.
47 * (The only exception are tangent-interpolators.)
48 * The {@code KeyValue} of the second {@code KeyFrame} (in forward
49 * direction) specifies the interpolator to be used in the interval.
50 * <p>
51 * Tangent-interpolators define the interpolation to the left and to the right of
52 * a {@code KeyFrame} (see {@link Interpolator#TANGENT(javafx.util.Duration, double, javafx.util.Duration, double)
53 * Interpolator.TANGENT}).
54 * <p>
55 * By default, {@link Interpolator#LINEAR} is used in the interval.
56 *
57 * @see Timeline
58 * @see KeyFrame
59 * @see Interpolator
60 *
61 * @since JavaFX 2.0
62 */
63 public final class KeyValue {
64
65 private static final Interpolator DEFAULT_INTERPOLATOR = Interpolator.LINEAR;
66
67 /**
68 * @treatAsPrivate implementation detail
69 * @deprecated This is an internal API that is not intended for use and will be removed in the next version
70 * @since JavaFX 2.0
71 */
72 @Deprecated
73 public static enum Type {
74 BOOLEAN, DOUBLE, FLOAT, INTEGER, LONG, OBJECT
75 }
76
77 /**
78 * @treatAsPrivate implementation detail
79 * @deprecated This is an internal API that is not intended for use and will be removed in the next version
80 */
81 @Deprecated
82 public Type getType() {
83 return type;
84 }
85
86 private final Type type;
87
88 /**
89 * Returns the target of this {@code KeyValue}
90 *
91 * @return the target
92 */
93 public WritableValue<?> getTarget() {
94 return target;
95 }
96
97 private final WritableValue<?> target;
98
99 /**
100 * Returns the end value of this {@code KeyValue}
101 *
102 * @return the end value
103 */
104 public Object getEndValue() {
105 return endValue;
106 }
107
108 private final Object endValue;
109
110 /**
111 * {@link Interpolator} to be used for calculating the key value along the
112 * particular interval. By default, {@link Interpolator#LINEAR} is used.
113 */
114 public Interpolator getInterpolator() {
115 return interpolator;
116 }
117
118 private final Interpolator interpolator;
119
120 /**
121 * Creates a {@code KeyValue}.
122 *
123 * @param target
124 * the target
125 * @param endValue
126 * the end value
127 * @param interpolator
128 * the {@link Interpolator}
129 * @throws NullPointerException
130 * if {@code target} or {@code interpolator} are {@code null}
131 */
132 public <T> KeyValue(@NamedArg("target") WritableValue<T> target, @NamedArg("endValue") T endValue,
133 @NamedArg("interpolator") Interpolator interpolator) {
134 if (target == null) {
135 throw new NullPointerException("Target needs to be specified");
136 }
137 if (interpolator == null) {
138 throw new NullPointerException("Interpolator needs to be specified");
139 }
140
141 this.target = target;
142 this.endValue = endValue;
143 this.interpolator = interpolator;
144 this.type = (target instanceof WritableNumberValue) ? (target instanceof WritableDoubleValue) ? Type.DOUBLE
145 : (target instanceof WritableIntegerValue) ? Type.INTEGER
146 : (target instanceof WritableFloatValue) ? Type.FLOAT
147 : (target instanceof WritableLongValue) ? Type.LONG
148 : Type.OBJECT
149 : (target instanceof WritableBooleanValue) ? Type.BOOLEAN
150 : Type.OBJECT;
151 }
152
153 /**
154 * Creates a {@code KeyValue} that uses {@link Interpolator#LINEAR}.
155 *
156 * @param target
157 * the target
158 * @param endValue
159 * the end value
160 * @throws NullPointerException
161 * if {@code target} or {@code interpolator} are {@code null}
162 */
163 public <T> KeyValue(@NamedArg("target") WritableValue<T> target, @NamedArg("endValue") T endValue) {
164 this(target, endValue, DEFAULT_INTERPOLATOR);
165 }
166
167 /**
168 * Returns a string representation of this {@code KeyValue} object.
169 * @return a string representation of this {@code KeyValue} object.
170 */
171 @Override
172 public String toString() {
173 return "KeyValue [target=" + target + ", endValue=" + endValue
174 + ", interpolator=" + interpolator + "]";
175 }
176
177 /**
178 * Returns a hash code for this {@code KeyValue} object.
179 * @return a hash code for this {@code KeyValue} object.
180 */
181 @Override
182 public int hashCode() {
183 assert (target != null) && (interpolator != null);
184 final int prime = 31;
185 int result = 1;
186 result = prime * result + target.hashCode();
187 result = prime * result
188 + ((endValue == null) ? 0 : endValue.hashCode());
189 result = prime * result + interpolator.hashCode();
190 return result;
191 }
192
193 /**
194 * Indicates whether some other object is "equal to" this one.
195 * Two {@code KeyValues} are considered equal, if their {@link #getTarget()
196 * target}, {@link #getEndValue() endValue}, and {@link #getInterpolator()
197 * interpolator} are equal.
198 */
199 @Override
200 public boolean equals(Object obj) {
201 if (this == obj) {
202 return true;
203 }
204 if (obj instanceof KeyValue) {
205 final KeyValue keyValue = (KeyValue) obj;
206 assert (target != null) && (interpolator != null)
207 && (keyValue.target != null)
208 && (keyValue.interpolator != null);
209 return target.equals(keyValue.target)
210 && ((endValue == null) ? (keyValue.endValue == null)
211 : endValue.equals(keyValue.endValue))
212 && interpolator.equals(keyValue.interpolator);
213 }
214 return false;
215 }
216
217 }