Spec-Zone .ru
спецификации, руководства, описания, API
001/*
002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.animation;
027
028import javafx.beans.value.WritableBooleanValue;
029import javafx.beans.value.WritableDoubleValue;
030import javafx.beans.value.WritableFloatValue;
031import javafx.beans.value.WritableIntegerValue;
032import javafx.beans.value.WritableLongValue;
033import javafx.beans.value.WritableNumberValue;
034import javafx.beans.value.WritableValue;
035
036/**
037 * Defines a key value to be interpolated for a particular interval along the
038 * animation. A {@link KeyFrame}, which defines a specific point on a timeline,
039 * can hold multiple {@code KeyValues}. {@code KeyValue} is an immutable class.
040 * <p>
041 * A {@code KeyValue} is defined by a target, which is an implementation of
042 * {@link javafx.beans.value.WritableValue}, an end value and an
043 * {@link Interpolator}.
044 * <p>
045 * Most interpolators define the interpolation between two {@code KeyFrames}.
046 * (The only exception are tangent-interpolators.)
047 * The {@code KeyValue} of the second {@code KeyFrame} (in forward
048 * direction) specifies the interpolator to be used in the interval.
049 * <p>
050 * Tangent-interpolators define the interpolation to the left and to the right of
051 * a {@code KeyFrame} (see {@link  Interpolator#TANGENT(javafx.util.Duration, double, javafx.util.Duration, double)
052 * Interpolator.TANGENT}).
053 * <p>
054 * By default, {@link Interpolator#LINEAR} is used in the interval.
055 * 
056 * @see Timeline
057 * @see KeyFrame
058 * @see Interpolator
059 * 
060 */
061public final class KeyValue {
062
063    private static final Interpolator DEFAULT_INTERPOLATOR = Interpolator.LINEAR;
064
065    /**
066     * @treatAsPrivate implementation detail
067     * @deprecated This is an internal API that is not intended for use and will be removed in the next version
068     */
069    @Deprecated
070    public static enum Type {
071        BOOLEAN, DOUBLE, FLOAT, INTEGER, LONG, OBJECT
072    }
073
074    /**
075     * @treatAsPrivate implementation detail
076     * @deprecated This is an internal API that is not intended for use and will be removed in the next version
077     */
078    @Deprecated
079    public Type getType() {
080        return type;
081    }
082
083    private final Type type;
084
085    /**
086     * Returns the target of this {@code KeyValue}
087     * 
088     * @return the target
089     */
090    public WritableValue<?> getTarget() {
091        return target;
092    }
093
094    private final WritableValue<?> target;
095
096    /**
097     * Returns the end value of this {@code KeyValue}
098     * 
099     * @return the end value
100     */
101    public Object getEndValue() {
102        return endValue;
103    }
104
105    private final Object endValue;
106
107    /**
108     * {@link Interpolator} to be used for calculating the key value along the
109     * particular interval. By default, {@link Interpolator#LINEAR} is used.
110     */
111    public Interpolator getInterpolator() {
112        return interpolator;
113    }
114
115    private final Interpolator interpolator;
116
117    /**
118     * Creates a {@code KeyValue}.
119     * 
120     * @param target
121     *            the target
122     * @param endValue
123     *            the end value
124     * @param interpolator
125     *            the {@link Interpolator}
126     * @throws NullPointerException
127     *             if {@code target} or {@code interpolator} are {@code null}
128     */
129    public <T> KeyValue(WritableValue<T> target, T endValue,
130            Interpolator interpolator) {
131        if (target == null) {
132            throw new NullPointerException("Target needs to be specified");
133        }
134        if (interpolator == null) {
135            throw new NullPointerException("Interpolator needs to be specified");
136        }
137
138        this.target = target;
139        this.endValue = endValue;
140        this.interpolator = interpolator;
141        this.type = (target instanceof WritableNumberValue) ? (target instanceof WritableDoubleValue) ? Type.DOUBLE
142                : (target instanceof WritableIntegerValue) ? Type.INTEGER
143                        : (target instanceof WritableFloatValue) ? Type.FLOAT
144                                : (target instanceof WritableLongValue) ? Type.LONG
145                                        : Type.OBJECT
146                : (target instanceof WritableBooleanValue) ? Type.BOOLEAN
147                        : Type.OBJECT;
148    }
149
150    /**
151     * Creates a {@code KeyValue} that uses {@link Interpolator#LINEAR}.
152     * 
153     * @param target
154     *            the target
155     * @param endValue
156     *            the end value
157     * @throws NullPointerException
158     *             if {@code target} or {@code interpolator} are {@code null}
159     */
160    public <T> KeyValue(WritableValue<T> target, T endValue) {
161        this(target, endValue, DEFAULT_INTERPOLATOR);
162    }
163
164    /**
165     * Returns a string representation of this {@code KeyValue} object.
166     * @return a string representation of this {@code KeyValue} object.
167     */ 
168    @Override
169    public String toString() {
170        return "KeyValue [target=" + target + ", endValue=" + endValue
171                + ", interpolator=" + interpolator + "]";
172    }
173
174    /**
175     * Returns a hash code for this {@code KeyValue} object.
176     * @return a hash code for this {@code KeyValue} object.
177     */ 
178    @Override
179    public int hashCode() {
180        assert (target != null) && (interpolator != null);
181        final int prime = 31;
182        int result = 1;
183        result = prime * result + target.hashCode();
184        result = prime * result
185                + ((endValue == null) ? 0 : endValue.hashCode());
186        result = prime * result + interpolator.hashCode();
187        return result;
188    }
189
190    /**
191     * Indicates whether some other object is "equal to" this one.
192     * Two {@code KeyValues} are considered equal, if their {@link #getTarget()
193     * target}, {@link #getEndValue() endValue}, and {@link #getInterpolator()
194     * interpolator} are equal.
195     */
196    @Override
197    public boolean equals(Object obj) {
198        if (this == obj) {
199            return true;
200        }
201        if (obj instanceof KeyValue) {
202            final KeyValue keyValue = (KeyValue) obj;
203            assert (target != null) && (interpolator != null)
204                    && (keyValue.target != null)
205                    && (keyValue.interpolator != null);
206            return target.equals(keyValue.target)
207                    && ((endValue == null) ? (keyValue.endValue == null)
208                            : endValue.equals(keyValue.endValue))
209                    && interpolator.equals(keyValue.interpolator);
210        }
211        return false;
212    }
213
214}