actionbarsherlock/src/com/actionbarsherlock/internal/nineoldandroids/animation/Animator.java

   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
  17 package com.actionbarsherlock.internal.nineoldandroids.animation;
  18
  19 import java.util.ArrayList;
  20
  21 import android.view.animation.Interpolator;
  22
  23 /**
  24  * This is the superclass for classes which provide basic support for animations which can be
  25  * started, ended, and have <code>AnimatorListeners</code> added to them.
  26  */
  27 public abstract class Animator implements Cloneable {
  28
  29
  30     /**
  31      * The set of listeners to be sent events through the life of an animation.
  32      */
  33     ArrayList<AnimatorListener> mListeners = null;
  34
  35     /**
  36      * Starts this animation. If the animation has a nonzero startDelay, the animation will start
  37      * running after that delay elapses. A non-delayed animation will have its initial
  38      * value(s) set immediately, followed by calls to
  39      * {@link AnimatorListener#onAnimationStart(Animator)} for any listeners of this animator.
  40      *
  41      * <p>The animation started by calling this method will be run on the thread that called
  42      * this method. This thread should have a Looper on it (a runtime exception will be thrown if
  43      * this is not the case). Also, if the animation will animate
  44      * properties of objects in the view hierarchy, then the calling thread should be the UI
  45      * thread for that view hierarchy.</p>
  46      *
  47      */
  48     public void start() {
  49     }
  50
  51     /**
  52      * Cancels the animation. Unlike {@link #end()}, <code>cancel()</code> causes the animation to
  53      * stop in its tracks, sending an
  54      * {@link android.animation.Animator.AnimatorListener#onAnimationCancel(Animator)} to
  55      * its listeners, followed by an
  56      * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} message.
  57      *
  58      * <p>This method must be called on the thread that is running the animation.</p>
  59      */
  60     public void cancel() {
  61     }
  62
  63     /**
  64      * Ends the animation. This causes the animation to assign the end value of the property being
  65      * animated, then calling the
  66      * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} method on
  67      * its listeners.
  68      *
  69      * <p>This method must be called on the thread that is running the animation.</p>
  70      */
  71     public void end() {
  72     }
  73
  74     /**
  75      * The amount of time, in milliseconds, to delay starting the animation after
  76      * {@link #start()} is called.
  77      *
  78      * @return the number of milliseconds to delay running the animation
  79      */
  80     public abstract long getStartDelay();
  81
  82     /**
  83      * The amount of time, in milliseconds, to delay starting the animation after
  84      * {@link #start()} is called.
  85
  86      * @param startDelay The amount of the delay, in milliseconds
  87      */
  88     public abstract void setStartDelay(long startDelay);
  89
  90
  91     /**
  92      * Sets the length of the animation.
  93      *
  94      * @param duration The length of the animation, in milliseconds.
  95      */
  96     public abstract Animator setDuration(long duration);
  97
  98     /**
  99      * Gets the length of the animation.
 100      *
 101      * @return The length of the animation, in milliseconds.
 102      */
 103     public abstract long getDuration();
 104
 105     /**
 106      * The time interpolator used in calculating the elapsed fraction of this animation. The
 107      * interpolator determines whether the animation runs with linear or non-linear motion,
 108      * such as acceleration and deceleration. The default value is
 109      * {@link android.view.animation.AccelerateDecelerateInterpolator}
 110      *
 111      * @param value the interpolator to be used by this animation
 112      */
 113     public abstract void setInterpolator(/*Time*/Interpolator value);
 114
 115     /**
 116      * Returns whether this Animator is currently running (having been started and gone past any
 117      * initial startDelay period and not yet ended).
 118      *
 119      * @return Whether the Animator is running.
 120      */
 121     public abstract boolean isRunning();
 122
 123     /**
 124      * Returns whether this Animator has been started and not yet ended. This state is a superset
 125      * of the state of {@link #isRunning()}, because an Animator with a nonzero
 126      * {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during the
 127      * delay phase, whereas {@link #isRunning()} will return true only after the delay phase
 128      * is complete.
 129      *
 130      * @return Whether the Animator has been started and not yet ended.
 131      */
 132     public boolean isStarted() {
 133         // Default method returns value for isRunning(). Subclasses should override to return a
 134         // real value.
 135         return isRunning();
 136     }
 137
 138     /**
 139      * Adds a listener to the set of listeners that are sent events through the life of an
 140      * animation, such as start, repeat, and end.
 141      *
 142      * @param listener the listener to be added to the current set of listeners for this animation.
 143      */
 144     public void addListener(AnimatorListener listener) {
 145         if (mListeners == null) {
 146             mListeners = new ArrayList<AnimatorListener>();
 147         }
 148         mListeners.add(listener);
 149     }
 150
 151     /**
 152      * Removes a listener from the set listening to this animation.
 153      *
 154      * @param listener the listener to be removed from the current set of listeners for this
 155      *                 animation.
 156      */
 157     public void removeListener(AnimatorListener listener) {
 158         if (mListeners == null) {
 159             return;
 160         }
 161         mListeners.remove(listener);
 162         if (mListeners.size() == 0) {
 163             mListeners = null;
 164         }
 165     }
 166
 167     /**
 168      * Gets the set of {@link android.animation.Animator.AnimatorListener} objects that are currently
 169      * listening for events on this <code>Animator</code> object.
 170      *
 171      * @return ArrayList<AnimatorListener> The set of listeners.
 172      */
 173     public ArrayList<AnimatorListener> getListeners() {
 174         return mListeners;
 175     }
 176
 177     /**
 178      * Removes all listeners from this object. This is equivalent to calling
 179      * <code>getListeners()</code> followed by calling <code>clear()</code> on the
 180      * returned list of listeners.
 181      */
 182     public void removeAllListeners() {
 183         if (mListeners != null) {
 184             mListeners.clear();
 185             mListeners = null;
 186         }
 187     }
 188
 189     @Override
 190     public Animator clone() {
 191         try {
 192             final Animator anim = (Animator) super.clone();
 193             if (mListeners != null) {
 194                 ArrayList<AnimatorListener> oldListeners = mListeners;
 195                 anim.mListeners = new ArrayList<AnimatorListener>();
 196                 int numListeners = oldListeners.size();
 197                 for (int i = 0; i < numListeners; ++i) {
 198                     anim.mListeners.add(oldListeners.get(i));
 199                 }
 200             }
 201             return anim;
 202         } catch (CloneNotSupportedException e) {
 203            throw new AssertionError();
 204         }
 205     }
 206
 207     /**
 208      * This method tells the object to use appropriate information to extract
 209      * starting values for the animation. For example, a AnimatorSet object will pass
 210      * this call to its child objects to tell them to set up the values. A
 211      * ObjectAnimator object will use the information it has about its target object
 212      * and PropertyValuesHolder objects to get the start values for its properties.
 213      * An ValueAnimator object will ignore the request since it does not have enough
 214      * information (such as a target object) to gather these values.
 215      */
 216     public void setupStartValues() {
 217     }
 218
 219     /**
 220      * This method tells the object to use appropriate information to extract
 221      * ending values for the animation. For example, a AnimatorSet object will pass
 222      * this call to its child objects to tell them to set up the values. A
 223      * ObjectAnimator object will use the information it has about its target object
 224      * and PropertyValuesHolder objects to get the start values for its properties.
 225      * An ValueAnimator object will ignore the request since it does not have enough
 226      * information (such as a target object) to gather these values.
 227      */
 228     public void setupEndValues() {
 229     }
 230
 231     /**
 232      * Sets the target object whose property will be animated by this animation. Not all subclasses
 233      * operate on target objects (for example, {@link ValueAnimator}, but this method
 234      * is on the superclass for the convenience of dealing generically with those subclasses
 235      * that do handle targets.
 236      *
 237      * @param target The object being animated
 238      */
 239     public void setTarget(Object target) {
 240     }
 241
 242     /**
 243      * <p>An animation listener receives notifications from an animation.
 244      * Notifications indicate animation related events, such as the end or the
 245      * repetition of the animation.</p>
 246      */
 247     public static interface AnimatorListener {
 248         /**
 249          * <p>Notifies the start of the animation.</p>
 250          *
 251          * @param animation The started animation.
 252          */
 253         void onAnimationStart(Animator animation);
 254
 255         /**
 256          * <p>Notifies the end of the animation. This callback is not invoked
 257          * for animations with repeat count set to INFINITE.</p>
 258          *
 259          * @param animation The animation which reached its end.
 260          */
 261         void onAnimationEnd(Animator animation);
 262
 263         /**
 264          * <p>Notifies the cancellation of the animation. This callback is not invoked
 265          * for animations with repeat count set to INFINITE.</p>
 266          *
 267          * @param animation The animation which was canceled.
 268          */
 269         void onAnimationCancel(Animator animation);
 270
 271         /**
 272          * <p>Notifies the repetition of the animation.</p>
 273          *
 274          * @param animation The animation which was repeated.
 275          */
 276         void onAnimationRepeat(Animator animation);
 277     }
 278 }