FileDocCategorySizeDatePackage
Animation.javaAPI DocAndroid 1.5 API31926Wed May 06 22:41:56 BST 2009android.view.animation

Animation

public abstract class Animation extends Object implements Cloneable
Abstraction for an Animation that can be applied to Views, Surfaces, or other objects. See the {@link android.view.animation animation package description file}.

Fields Summary
public static final int
INFINITE
Repeat the animation indefinitely.
public static final int
RESTART
When the animation reaches the end and the repeat count is INFINTE_REPEAT or a positive value, the animation restarts from the beginning.
public static final int
REVERSE
When the animation reaches the end and the repeat count is INFINTE_REPEAT or a positive value, the animation plays backward (and then forward again).
public static final int
START_ON_FIRST_FRAME
Can be used as the start time to indicate the start time should be the current time when {@link #getTransformation(long, Transformation)} is invoked for the first animation frame. This can is useful for short animations.
public static final int
ABSOLUTE
The specified dimension is an absolute number of pixels.
public static final int
RELATIVE_TO_SELF
The specified dimension holds a float and should be multiplied by the height or width of the object being animated.
public static final int
RELATIVE_TO_PARENT
The specified dimension holds a float and should be multiplied by the height or width of the parent of the object being animated.
public static final int
ZORDER_NORMAL
Requests that the content being animated be kept in its current Z order.
public static final int
ZORDER_TOP
Requests that the content being animated be forced on top of all other content for the duration of the animation.
public static final int
ZORDER_BOTTOM
Requests that the content being animated be forced under all other content for the duration of the animation.
boolean
mEnded
Set by {@link #getTransformation(long, Transformation)} when the animation ends.
boolean
mStarted
Set by {@link #getTransformation(long, Transformation)} when the animation starts.
boolean
mCycleFlip
Set by {@link #getTransformation(long, Transformation)} when the animation repeats in REVERSE mode.
boolean
mInitialized
This value must be set to true by {@link #initialize(int, int, int, int)}. It indicates the animation was successfully initialized and can be played.
boolean
mFillBefore
Indicates whether the animation transformation should be applied before the animation starts.
boolean
mFillAfter
Indicates whether the animation transformation should be applied after the animation ends.
boolean
mFillEnabled
Indicates whether fillAfter should be taken into account.
long
mStartTime
The time in milliseconds at which the animation must start;
long
mStartOffset
The delay in milliseconds after which the animation must start. When the start offset is > 0, the start time of the animation is startTime + startOffset.
long
mDuration
The duration of one animation cycle in milliseconds.
int
mRepeatCount
The number of times the animation must repeat. By default, an animation repeats indefinitely.
int
mRepeated
Indicates how many times the animation was repeated.
int
mRepeatMode
The behavior of the animation when it repeats. The repeat mode is either {@link #RESTART} or {@link #REVERSE}.
Interpolator
mInterpolator
The interpolator used by the animation to smooth the movement.
AnimationListener
mListener
The animation listener to be notified when the animation starts, ends or repeats.
private int
mZAdjustment
Desired Z order mode during animation.
private boolean
mMore
private boolean
mOneMoreTime
android.graphics.RectF
mPreviousRegion
android.graphics.RectF
mRegion
Transformation
mTransformation
Transformation
mPreviousTransformation
Constructors Summary
public Animation()
Creates a new animation with a duration of 0ms, the default interpolator, with fillBefore set to true and fillAfter set to false


                               
      
        ensureInterpolator();
public Animation(android.content.Context context, android.util.AttributeSet attrs)
Creates a new animation whose parameters come from the specified context and attributes set.

param
context the application environment
param
attrs the set of attributes holding the animation parameters

        TypedArray a = context.obtainStyledAttributes(attrs, com.android.internal.R.styleable.Animation);

        setDuration((long) a.getInt(com.android.internal.R.styleable.Animation_duration, 0));
        setStartOffset((long) a.getInt(com.android.internal.R.styleable.Animation_startOffset, 0));
        
        setFillEnabled(a.getBoolean(com.android.internal.R.styleable.Animation_fillEnabled, mFillEnabled));
        setFillBefore(a.getBoolean(com.android.internal.R.styleable.Animation_fillBefore, mFillBefore));
        setFillAfter(a.getBoolean(com.android.internal.R.styleable.Animation_fillAfter, mFillAfter));

        final int resID = a.getResourceId(com.android.internal.R.styleable.Animation_interpolator, 0);
        if (resID > 0) {
            setInterpolator(context, resID);
        }

        setRepeatCount(a.getInt(com.android.internal.R.styleable.Animation_repeatCount, mRepeatCount));
        setRepeatMode(a.getInt(com.android.internal.R.styleable.Animation_repeatMode, RESTART));

        setZAdjustment(a.getInt(com.android.internal.R.styleable.Animation_zAdjustment, ZORDER_NORMAL));
        
        ensureInterpolator();

        a.recycle();
Methods Summary
protected voidapplyTransformation(float interpolatedTime, Transformation t)
Helper for getTransformation. Subclasses should implement this to apply their transforms given an interpolation value. Implementations of this method should always replace the specified Transformation or document they are doing otherwise.

param
interpolatedTime The value of the normalized time (0.0 to 1.0) after it has been run through the interpolation function.
param
t The Transofrmation object to fill in with the current transforms.
protected android.view.animation.Animationclone()

        final Animation animation = (Animation) super.clone();
        animation.mPreviousRegion = new RectF();
        animation.mRegion = new RectF();
        animation.mTransformation = new Transformation();
        animation.mPreviousTransformation = new Transformation();
        return animation;
public longcomputeDurationHint()
Compute a hint at how long the entire animation may last, in milliseconds. Animations can be written to cause themselves to run for a different duration than what is computed here, but generally this should be accurate.

        return (getStartOffset() + getDuration()) * (getRepeatCount() + 1);
protected voidensureInterpolator()
Gurantees that this animation has an interpolator. Will use a AccelerateDecelerateInterpolator is nothing else was specified.

        if (mInterpolator == null) {
            mInterpolator = new AccelerateDecelerateInterpolator();
        }
public longgetDuration()
How long this animation should last

return
the duration in milliseconds of the animation
attr
ref android.R.styleable#Animation_duration

        return mDuration;
public booleangetFillAfter()
If fillAfter is true, this animation will apply its transformation after the end time of the animation.

return
true if the animation applies its transformation after it ends
attr
ref android.R.styleable#Animation_fillAfter

        return mFillAfter;
public booleangetFillBefore()
If fillBefore is true, this animation will apply its transformation before the start time of the animation.

return
true if the animation applies its transformation before it starts
attr
ref android.R.styleable#Animation_fillBefore

        return mFillBefore;
public InterpolatorgetInterpolator()
Gets the acceleration curve type for this animation.

return
the {@link Interpolator} associated to this animation
attr
ref android.R.styleable#Animation_interpolator

        return mInterpolator;
public voidgetInvalidateRegion(int left, int top, int right, int bottom, android.graphics.RectF invalidate, Transformation transformation)

param
left
param
top
param
right
param
bottom
param
invalidate
param
transformation
hide


        final RectF tempRegion = mRegion;
        final RectF previousRegion = mPreviousRegion;

        invalidate.set(left, top, right, bottom);
        transformation.getMatrix().mapRect(invalidate);
        // Enlarge the invalidate region to account for rounding errors
        invalidate.inset(-1.0f, -1.0f);
        tempRegion.set(invalidate);
        invalidate.union(previousRegion);

        previousRegion.set(tempRegion);

        final Transformation tempTransformation = mTransformation;
        final Transformation previousTransformation = mPreviousTransformation;

        tempTransformation.set(transformation);
        transformation.set(previousTransformation);
        previousTransformation.set(tempTransformation);
public intgetRepeatCount()
Defines how many times the animation should repeat. The default value is 0.

return
the number of times the animation should repeat, or {@link #INFINITE}
attr
ref android.R.styleable#Animation_repeatCount

        return mRepeatCount;
public intgetRepeatMode()
Defines what this animation should do when it reaches the end.

return
either one of {@link #REVERSE} or {@link #RESTART}
attr
ref android.R.styleable#Animation_repeatMode

        return mRepeatMode;
public longgetStartOffset()
When this animation should start, relative to StartTime

return
the start offset in milliseconds
attr
ref android.R.styleable#Animation_startOffset

        return mStartOffset;
public longgetStartTime()
When this animation should start. If the animation has not startet yet, this method might return {@link #START_ON_FIRST_FRAME}.

return
the time in milliseconds when the animation should start or {@link #START_ON_FIRST_FRAME}

        return mStartTime;
public booleangetTransformation(long currentTime, Transformation outTransformation)
Gets the transformation to apply at a specified point in time. Implementations of this method should always replace the specified Transformation or document they are doing otherwise.

param
currentTime Where we are in the animation. This is wall clock time.
param
outTransformation A tranformation object that is provided by the caller and will be filled in by the animation.
return
True if the animation is still running

        if (mStartTime == -1) {
            mStartTime = currentTime;
        }

        final long startOffset = getStartOffset();
        final long duration = mDuration;
        float normalizedTime;
        if (duration != 0) {
            normalizedTime = ((float) (currentTime - (mStartTime + startOffset))) /
                    (float) duration;
        } else {
            // time is a step-change with a zero duration
            normalizedTime = currentTime < mStartTime ? 0.0f : 1.0f;
        }

        final boolean expired = normalizedTime >= 1.0f;
        mMore = !expired;

        if (!mFillEnabled) normalizedTime = Math.max(Math.min(normalizedTime, 1.0f), 0.0f);

        if ((normalizedTime >= 0.0f || mFillBefore) && (normalizedTime <= 1.0f || mFillAfter)) {
            if (!mStarted) {
                if (mListener != null) {
                    mListener.onAnimationStart(this);
                }
                mStarted = true;
            }

            if (mFillEnabled) normalizedTime = Math.max(Math.min(normalizedTime, 1.0f), 0.0f);

            if (mCycleFlip) {
                normalizedTime = 1.0f - normalizedTime;
            }

            final float interpolatedTime = mInterpolator.getInterpolation(normalizedTime);
            applyTransformation(interpolatedTime, outTransformation);
        }

        if (expired) {
            if (mRepeatCount == mRepeated) {
                if (!mEnded) {
                    if (mListener != null) {
                        mListener.onAnimationEnd(this);
                    }
                    mEnded = true;
                }
            } else {
                if (mRepeatCount > 0) {
                    mRepeated++;
                }

                if (mRepeatMode == REVERSE) {
                    mCycleFlip = !mCycleFlip;
                }

                mStartTime = -1;
                mMore = true;

                if (mListener != null) {
                    mListener.onAnimationRepeat(this);
                }
            }
        }

        if (!mMore && mOneMoreTime) {
            mOneMoreTime = false;
            return true;
        }

        return mMore;
public intgetZAdjustment()
Returns the Z ordering mode to use while running the animation as previously set by {@link #setZAdjustment}.

return
Returns one of {@link #ZORDER_NORMAL}, {@link #ZORDER_TOP}, or {@link #ZORDER_BOTTOM}.
attr
ref android.R.styleable#Animation_zAdjustment

        return mZAdjustment;
public booleanhasEnded()

Indicates whether this animation has ended or not.

return
true if the animation has ended, false otherwise

        return mEnded;
public booleanhasStarted()

Indicates whether this animation has started or not.

return
true if the animation has started, false otherwise

        return mStarted;
public voidinitialize(int width, int height, int parentWidth, int parentHeight)
Initialize this animation with the dimensions of the object being animated as well as the objects parents. (This is to support animation sizes being specifed relative to these dimensions.)

Objects that interpret a Animations should call this method when the sizes of the object being animated and its parent are known, and before calling {@link #getTransformation}.

param
width Width of the object being animated
param
height Height of the object being animated
param
parentWidth Width of the animated object's parent
param
parentHeight Height of the animated object's parent

        reset();
        mInitialized = true;
public voidinitializeInvalidateRegion(int left, int top, int right, int bottom)

param
left
param
top
param
right
param
bottom
hide

        final RectF region = mPreviousRegion;
        region.set(left, top, right, bottom);
        // Enlarge the invalidate region to account for rounding errors
        region.inset(-1.0f, -1.0f);
        if (mFillBefore) {
            final Transformation previousTransformation = mPreviousTransformation;
            applyTransformation(0.0f, previousTransformation);
        }
public booleanisFillEnabled()
If fillEnabled is true, this animation will apply fillBefore and fillAfter.

return
true if the animation will take fillBefore and fillAfter into account
attr
ref android.R.styleable#Animation_fillEnabled

        return mFillEnabled;
public booleanisInitialized()
Whether or not the animation has been initialized.

return
Has this animation been initialized.
see
#initialize(int, int, int, int)

        return mInitialized;
public voidreset()
Reset the initialization state of this animation.

see
#initialize(int, int, int, int)

        mPreviousRegion.setEmpty();
        mPreviousTransformation.clear();
        mInitialized = false;
        mCycleFlip = false;
        mRepeated = 0;
        mMore = true;
        mOneMoreTime = true;
protected floatresolveSize(int type, float value, int size, int parentSize)
Convert the information in the description of a size to an actual dimension

param
type One of Animation.ABSOLUTE, Animation.RELATIVE_TO_SELF, or Animation.RELATIVE_TO_PARENT.
param
value The dimension associated with the type parameter
param
size The size of the object being animated
param
parentSize The size of the parent of the object being animated
return
The dimension to use for the animation

        switch (type) {
            case ABSOLUTE:
                return value;
            case RELATIVE_TO_SELF:
                return size * value;
            case RELATIVE_TO_PARENT:
                return parentSize * value;
            default:
                return value;
        }
public voidrestrictDuration(long durationMillis)
Ensure that the duration that this animation will run is not longer than durationMillis. In addition to adjusting the duration itself, this ensures that the repeat count also will not make it run longer than the given time.

param
durationMillis The maximum duration the animation is allowed to run.

        // If we start after the duration, then we just won't run.
        if (mStartOffset > durationMillis) {
            mStartOffset = durationMillis;
            mDuration = 0;
            mRepeatCount = 0;
            return;
        }
        
        long dur = mDuration + mStartOffset;
        if (dur > durationMillis) {
            mDuration = durationMillis-mStartOffset;
            dur = durationMillis;
        }
        // If the duration is 0 or less, then we won't run.
        if (mDuration <= 0) {
            mDuration = 0;
            mRepeatCount = 0;
            return;
        }
        // Reduce the number of repeats to keep below the maximum duration.
        // The comparison between mRepeatCount and duration is to catch
        // overflows after multiplying them.
        if (mRepeatCount < 0 || mRepeatCount > durationMillis
                || (dur*mRepeatCount) > durationMillis) {
            // Figure out how many times to do the animation.  Subtract 1 since
            // repeat count is the number of times to repeat so 0 runs once.
            mRepeatCount = (int)(durationMillis/dur) - 1;
            if (mRepeatCount < 0) {
                mRepeatCount = 0;
            }
        }
public voidscaleCurrentDuration(float scale)
How much to scale the duration by.

param
scale The amount to scale the duration.

        mDuration = (long) (mDuration * scale);
public voidsetAnimationListener(android.view.animation.Animation$AnimationListener listener)

Binds an animation listener to this animation. The animation listener is notified of animation events such as the end of the animation or the repetition of the animation.

param
listener the animation listener to be notified

        mListener = listener;
public voidsetDuration(long durationMillis)
How long this animation should last. The duration cannot be negative.

param
durationMillis Duration in milliseconds
throw
java.lang.IllegalArgumentException if the duration is < 0
attr
ref android.R.styleable#Animation_duration

        if (durationMillis < 0) {
            throw new IllegalArgumentException("Animation duration cannot be negative");
        }
        mDuration = durationMillis;
public voidsetFillAfter(boolean fillAfter)
If fillAfter is true, the transformation that this animation performed will persist when it is finished. Defaults to false if not set. Note that this applies when using an {@link android.view.animation.AnimationSet AnimationSet} to chain animations. The transformation is not applied before the AnimationSet itself starts.

param
fillAfter true if the animation should apply its transformation after it ends
attr
ref android.R.styleable#Animation_fillAfter
see
#setFillEnabled(boolean)

        mFillAfter = fillAfter;
public voidsetFillBefore(boolean fillBefore)
If fillBefore is true, this animation will apply its transformation before the start time of the animation. Defaults to true if not set. Note that this applies when using an {@link android.view.animation.AnimationSet AnimationSet} to chain animations. The transformation is not applied before the AnimationSet itself starts.

param
fillBefore true if the animation should apply its transformation before it starts
attr
ref android.R.styleable#Animation_fillBefore
see
#setFillEnabled(boolean)

        mFillBefore = fillBefore;
public voidsetFillEnabled(boolean fillEnabled)
If fillEnabled is true, the animation will apply the value of fillBefore and fillAfter. Otherwise, fillBefore and fillAfter are ignored and the animation transformation is always applied.

param
fillEnabled true if the animation should take fillBefore and fillAfter into account
attr
ref android.R.styleable#Animation_fillEnabled
see
#setFillBefore(boolean)
see
#setFillAfter(boolean)

        mFillEnabled = fillEnabled;
public voidsetInterpolator(android.content.Context context, int resID)
Sets the acceleration curve for this animation. The interpolator is loaded as a resource from the specified context.

param
context The application environment
param
resID The resource identifier of the interpolator to load
attr
ref android.R.styleable#Animation_interpolator

        setInterpolator(AnimationUtils.loadInterpolator(context, resID));
public voidsetInterpolator(Interpolator i)
Sets the acceleration curve for this animation. Defaults to a linear interpolation.

param
i The interpolator which defines the acceleration curve
attr
ref android.R.styleable#Animation_interpolator

        mInterpolator = i;
public voidsetRepeatCount(int repeatCount)
Sets how many times the animation should be repeated. If the repeat count is 0, the animation is never repeated. If the repeat count is greater than 0 or {@link #INFINITE}, the repeat mode will be taken into account. The repeat count is 0 by default.

param
repeatCount the number of times the animation should be repeated
attr
ref android.R.styleable#Animation_repeatCount

        if (repeatCount < 0) {
            repeatCount = INFINITE;
        }
        mRepeatCount = repeatCount;
public voidsetRepeatMode(int repeatMode)
Defines what this animation should do when it reaches the end. This setting is applied only when the repeat count is either greater than 0 or {@link #INFINITE}. Defaults to {@link #RESTART}.

param
repeatMode {@link #RESTART} or {@link #REVERSE}
attr
ref android.R.styleable#Animation_repeatMode

        mRepeatMode = repeatMode;
public voidsetStartOffset(long startOffset)
When this animation should start relative to the start time. This is most useful when composing complex animations using an {@link AnimationSet } where some of the animations components start at different times.

param
startOffset When this Animation should start, in milliseconds from the start time of the root AnimationSet.
attr
ref android.R.styleable#Animation_startOffset

        mStartOffset = startOffset;
public voidsetStartTime(long startTimeMillis)
When this animation should start. When the start time is set to {@link #START_ON_FIRST_FRAME}, the animation will start the first time {@link #getTransformation(long, Transformation)} is invoked. The time passed to this method should be obtained by calling {@link AnimationUtils#currentAnimationTimeMillis()} instead of {@link System#currentTimeMillis()}.

param
startTimeMillis the start time in milliseconds

        mStartTime = startTimeMillis;
        mStarted = mEnded = false;
        mCycleFlip = false;
        mRepeated = 0;
        mMore = true;
public voidsetZAdjustment(int zAdjustment)
Set the Z ordering mode to use while running the animation.

param
zAdjustment The desired mode, one of {@link #ZORDER_NORMAL}, {@link #ZORDER_TOP}, or {@link #ZORDER_BOTTOM}.
attr
ref android.R.styleable#Animation_zAdjustment

        mZAdjustment = zAdjustment;
public voidstart()
Convenience method to start the animation the first time {@link #getTransformation(long, Transformation)} is invoked.

        setStartTime(-1);
public voidstartNow()
Convenience method to start the animation at the current time in milliseconds.

        setStartTime(AnimationUtils.currentAnimationTimeMillis());
public booleanwillChangeBounds()

Indicates whether or not this animation will affect the bounds of the animated view. For instance, a fade animation will not affect the bounds whereas a 200% scale animation will.

return
true if this animation will change the view's bounds

        // assume we will change the bounds
        return true;
public booleanwillChangeTransformationMatrix()

Indicates whether or not this animation will affect the transformation matrix. For instance, a fade animation will not affect the matrix whereas a scale animation will.

return
true if this animation will change the transformation matrix

        // assume we will change the matrix
        return true;