/*
|
* Copyright (C) 2011 The Android Open Source Project
|
*
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
* you may not use this file except in compliance with the License.
|
* You may obtain a copy of the License at
|
*
|
* http://www.apache.org/licenses/LICENSE-2.0
|
*
|
* Unless required by applicable law or agreed to in writing, software
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
* See the License for the specific language governing permissions and
|
* limitations under the License.
|
*/
|
|
package com.nineoldandroids.view;
|
|
import java.util.WeakHashMap;
|
import android.os.Build;
|
import android.view.View;
|
import android.view.animation.Interpolator;
|
import com.nineoldandroids.animation.Animator;
|
|
/**
|
* This class enables automatic and optimized animation of select properties on View objects.
|
* If only one or two properties on a View object are being animated, then using an
|
* {@link android.animation.ObjectAnimator} is fine; the property setters called by ObjectAnimator
|
* are well equipped to do the right thing to set the property and invalidate the view
|
* appropriately. But if several properties are animated simultaneously, or if you just want a
|
* more convenient syntax to animate a specific property, then ViewPropertyAnimator might be
|
* more well-suited to the task.
|
*
|
* <p>This class may provide better performance for several simultaneous animations, because
|
* it will optimize invalidate calls to take place only once for several properties instead of each
|
* animated property independently causing its own invalidation. Also, the syntax of using this
|
* class could be easier to use because the caller need only tell the View object which
|
* property to animate, and the value to animate either to or by, and this class handles the
|
* details of configuring the underlying Animator class and starting it.</p>
|
*
|
* <p>This class is not constructed by the caller, but rather by the View whose properties
|
* it will animate. Calls to {@link android.view.View#animate()} will return a reference
|
* to the appropriate ViewPropertyAnimator object for that View.</p>
|
*
|
*/
|
public abstract class ViewPropertyAnimator {
|
private static final WeakHashMap<View, ViewPropertyAnimator> ANIMATORS =
|
new WeakHashMap<View, ViewPropertyAnimator>(0);
|
|
/**
|
* This method returns a ViewPropertyAnimator object, which can be used to animate specific
|
* properties on this View.
|
*
|
* @param view View to animate.
|
* @return The ViewPropertyAnimator associated with this View.
|
*/
|
public static ViewPropertyAnimator animate(View view) {
|
ViewPropertyAnimator animator = ANIMATORS.get(view);
|
if (animator == null) {
|
final int version = Integer.valueOf(Build.VERSION.SDK);
|
if (version >= Build.VERSION_CODES.ICE_CREAM_SANDWICH) {
|
animator = new ViewPropertyAnimatorICS(view);
|
} else if (version >= Build.VERSION_CODES.HONEYCOMB) {
|
animator = new ViewPropertyAnimatorHC(view);
|
} else {
|
animator = new ViewPropertyAnimatorPreHC(view);
|
}
|
ANIMATORS.put(view, animator);
|
}
|
return animator;
|
}
|
|
|
/**
|
* Sets the duration for the underlying animator that animates the requested properties.
|
* By default, the animator uses the default value for ValueAnimator. Calling this method
|
* will cause the declared value to be used instead.
|
* @param duration The length of ensuing property animations, in milliseconds. The value
|
* cannot be negative.
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator setDuration(long duration);
|
|
/**
|
* Returns the current duration of property animations. If the duration was set on this
|
* object, that value is returned. Otherwise, the default value of the underlying Animator
|
* is returned.
|
*
|
* @see #setDuration(long)
|
* @return The duration of animations, in milliseconds.
|
*/
|
public abstract long getDuration();
|
|
/**
|
* Returns the current startDelay of property animations. If the startDelay was set on this
|
* object, that value is returned. Otherwise, the default value of the underlying Animator
|
* is returned.
|
*
|
* @see #setStartDelay(long)
|
* @return The startDelay of animations, in milliseconds.
|
*/
|
public abstract long getStartDelay();
|
|
/**
|
* Sets the startDelay for the underlying animator that animates the requested properties.
|
* By default, the animator uses the default value for ValueAnimator. Calling this method
|
* will cause the declared value to be used instead.
|
* @param startDelay The delay of ensuing property animations, in milliseconds. The value
|
* cannot be negative.
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator setStartDelay(long startDelay);
|
|
/**
|
* Sets the interpolator for the underlying animator that animates the requested properties.
|
* By default, the animator uses the default interpolator for ValueAnimator. Calling this method
|
* will cause the declared object to be used instead.
|
*
|
* @param interpolator The TimeInterpolator to be used for ensuing property animations.
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator setInterpolator(/*Time*/Interpolator interpolator);
|
|
/**
|
* Sets a listener for events in the underlying Animators that run the property
|
* animations.
|
*
|
* @param listener The listener to be called with AnimatorListener events.
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator setListener(Animator.AnimatorListener listener);
|
|
/**
|
* Starts the currently pending property animations immediately. Calling <code>start()</code>
|
* is optional because all animations start automatically at the next opportunity. However,
|
* if the animations are needed to start immediately and synchronously (not at the time when
|
* the next event is processed by the hierarchy, which is when the animations would begin
|
* otherwise), then this method can be used.
|
*/
|
public abstract void start();
|
|
/**
|
* Cancels all property animations that are currently running or pending.
|
*/
|
public abstract void cancel();
|
|
/**
|
* This method will cause the View's <code>x</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator x(float value);
|
|
/**
|
* This method will cause the View's <code>x</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator xBy(float value);
|
|
/**
|
* This method will cause the View's <code>y</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator y(float value);
|
|
/**
|
* This method will cause the View's <code>y</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator yBy(float value);
|
|
/**
|
* This method will cause the View's <code>rotation</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setRotation(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotation(float value);
|
|
/**
|
* This method will cause the View's <code>rotation</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setRotation(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotationBy(float value);
|
|
/**
|
* This method will cause the View's <code>rotationX</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setRotationX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotationX(float value);
|
|
/**
|
* This method will cause the View's <code>rotationX</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setRotationX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotationXBy(float value);
|
|
/**
|
* This method will cause the View's <code>rotationY</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setRotationY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotationY(float value);
|
|
/**
|
* This method will cause the View's <code>rotationY</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setRotationY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator rotationYBy(float value);
|
|
/**
|
* This method will cause the View's <code>translationX</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setTranslationX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator translationX(float value);
|
|
/**
|
* This method will cause the View's <code>translationX</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setTranslationX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator translationXBy(float value);
|
|
/**
|
* This method will cause the View's <code>translationY</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setTranslationY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator translationY(float value);
|
|
/**
|
* This method will cause the View's <code>translationY</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setTranslationY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator translationYBy(float value);
|
|
/**
|
* This method will cause the View's <code>scaleX</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setScaleX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator scaleX(float value);
|
|
/**
|
* This method will cause the View's <code>scaleX</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setScaleX(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator scaleXBy(float value);
|
|
/**
|
* This method will cause the View's <code>scaleY</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setScaleY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator scaleY(float value);
|
|
/**
|
* This method will cause the View's <code>scaleY</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setScaleY(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator scaleYBy(float value);
|
|
/**
|
* This method will cause the View's <code>alpha</code> property to be animated to the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The value to be animated to.
|
* @see View#setAlpha(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator alpha(float value);
|
|
/**
|
* This method will cause the View's <code>alpha</code> property to be animated by the
|
* specified value. Animations already running on the property will be canceled.
|
*
|
* @param value The amount to be animated by, as an offset from the current value.
|
* @see View#setAlpha(float)
|
* @return This object, allowing calls to methods in this class to be chained.
|
*/
|
public abstract ViewPropertyAnimator alphaBy(float value);
|
}
|
