content: /*
   * Copyright (C) 2010 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 android.animation;
  
  import android.annotation.Nullable;
  import android.annotation.UnsupportedAppUsage;
  import android.content.pm.ActivityInfo.Config;
  import android.content.res.ConstantState;
  
  import java.util.ArrayList;
  
  /**
   * This is the superclass for classes which provide basic support for animations which can be
   * started, ended, and have <code>AnimatorListeners</code> added to them.
   */
  public abstract class Animator implements Cloneable {
  
      /**
       * The value used to indicate infinite duration (e.g. when Animators repeat infinitely).
       */
      public static final long DURATION_INFINITE = -1;
      /**
       * The set of listeners to be sent events through the life of an animation.
       */
      ArrayList<AnimatorListener> mListeners = null;
  
      /**
       * The set of listeners to be sent pause/resume events through the life
       * of an animation.
       */
      ArrayList<AnimatorPauseListener> mPauseListeners = null;
  
      /**
       * Whether this animator is currently in a paused state.
       */
      boolean mPaused = false;
  
      /**
       * A set of flags which identify the type of configuration changes that can affect this
       * Animator. Used by the Animator cache.
       */
      @Config int mChangingConfigurations = 0;
  
      /**
       * If this animator is inflated from a constant state, keep a reference to it so that
       * ConstantState will not be garbage collected until this animator is collected
       */
      private AnimatorConstantState mConstantState;
  
      /**
       * Starts this animation. If the animation has a nonzero startDelay, the animation will start
       * running after that delay elapses. A non-delayed animation will have its initial
       * value(s) set immediately, followed by calls to
       * {@link AnimatorListener#onAnimationStart(Animator)} for any listeners of this animator.
       *
       * <p>The animation started by calling this method will be run on the thread that called
       * this method. This thread should have a Looper on it (a runtime exception will be thrown if
       * this is not the case). Also, if the animation will animate
       * properties of objects in the view hierarchy, then the calling thread should be the UI
       * thread for that view hierarchy.</p>
       *
       */
      public void start() {
      }
  
      /**
       * Cancels the animation. Unlike {@link #end()}, <code>cancel()</code> causes the animation to
       * stop in its tracks, sending an
       * {@link android.animation.Animator.AnimatorListener#onAnimationCancel(Animator)} to
       * its listeners, followed by an
       * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} message.
       *
       * <p>This method must be called on the thread that is running the animation.</p>
       */
      public void cancel() {
      }
  
      /**
       * Ends the animation. This causes the animation to assign the end value of the property being
       * animated, then calling the
       * {@link android.animation.Animator.AnimatorListener#onAnimationEnd(Animator)} method on
       * its listeners.
       *
       * <p>This method must be called on the thread that is running the animation.</p>
       */
      public void end() {
      }
  
      /**
       * Pauses a running animation. This method should only be called on the same thread on
       * which the animation was started. If the animation has not yet been {@link
       * #isStarted() started} or has since ended, then the call is ignored. Paused
       * animations can be resumed by calling {@link #resume()}.
       *
       * @see #resume()
       * @see #isPaused()
       * @see AnimatorPauseListener
       */
      public void pause() {
          if (isStarted() && !mPaused) {
              mPaused = true;
              if (mPauseListeners != null) {
                  ArrayList<AnimatorPauseListener> tmpListeners =
                          (ArrayList<AnimatorPauseListener>) mPauseListeners.clone();
                  int numListeners = tmpListeners.size();
                  for (int i = 0; i < numListeners; ++i) {
                      tmpListeners.get(i).onAnimationPause(this);
                  }
              }
          }
      }
  
      /**
       * Resumes a paused animation, causing the animator to pick up where it left off
       * when it was paused. This method should only be called on the same thread on
       * which the animation was started. Calls to resume() on an animator that is
       * not currently paused will be ignored.
       *
       * @see #pause()
       * @see #isPaused()
       * @see AnimatorPauseListener
       */
      public void resume() {
          if (mPaused) {
              mPaused = false;
              if (mPauseListeners != null) {
                  ArrayList<AnimatorPauseListener> tmpListeners =
                          (ArrayList<AnimatorPauseListener>) mPauseListeners.clone();
                  int numListeners = tmpListeners.size();
                  for (int i = 0; i < numListeners; ++i) {
                      tmpListeners.get(i).onAnimationResume(this);
                  }
              }
          }
      }
  
      /**
       * Returns whether this animator is currently in a paused state.
       *
       * @return True if the animator is currently paused, false otherwise.
       *
       * @see #pause()
       * @see #resume()
       */
      public boolean isPaused() {
          return mPaused;
      }
  
      /**
       * The amount of time, in milliseconds, to delay processing the animation
       * after {@link #start()} is called.
       *
       * @return the number of milliseconds to delay running the animation
       */
      public abstract long getStartDelay();
  
      /**
       * The amount of time, in milliseconds, to delay processing the animation
       * after {@link #start()} is called.
  
       * @param startDelay The amount of the delay, in milliseconds
       */
      public abstract void setStartDelay(long startDelay);
  
      /**
       * Sets the duration of the animation.
       *
       * @param duration The length of the animation, in milliseconds.
       */
      public abstract Animator setDuration(long duration);
  
      /**
       * Gets the duration of the animation.
       *
       * @return The length of the animation, in milliseconds.
       */
      public abstract long getDuration();
  
      /**
       * Gets the total duration of the animation, accounting for animation sequences, start delay,
       * and repeating. Return {@link #DURATION_INFINITE} if the duration is infinite.
       *
       * @return  Total time an animation takes to finish, starting from the time {@link #start()}
       *          is called. {@link #DURATION_INFINITE} will be returned if the animation or any
       *          child animation repeats infinite times.
       */
      public long getTotalDuration() {
          long duration = getDuration();
          if (duration == DURATION_INFINITE) {
              return DURATION_INFINITE;
          } else {
              return getStartDelay() + duration;
          }
      }
  
      /**
       * The time interpolator used in calculating the elapsed fraction of the
       * animation. The interpolator determines whether the animation runs with
       * linear or non-linear motion, such as acceleration and deceleration. The
       * default value is {@link android.view.animation.AccelerateDecelerateInterpolator}.
       *
       * @param value the interpolator to be used by this animation
       */
      public abstract void setInterpolator(TimeInterpolator value);
  
      /**
       * Returns the timing interpolator that this animation uses.
       *
       * @return The timing interpolator for this animation.
       */
      public TimeInterpolator getInterpolator() {
          return null;
      }
  
      /**
       * Returns whether this Animator is currently running (having been started and gone past any
       * initial startDelay period and not yet ended).
       *
       * @return Whether the Animator is running.
       */
      public abstract boolean isRunning();
  
      /**
       * Returns whether this Animator has been started and not yet ended. For reusable
       * Animators (which most Animators are, apart from the one-shot animator produced by
       * {@link android.view.ViewAnimationUtils#createCircularReveal(
       * android.view.View, int, int, float, float) createCircularReveal()}),
       * this state is a superset of {@link #isRunning()}, because an Animator with a
       * nonzero {@link #getStartDelay() startDelay} will return true for {@link #isStarted()} during
       * the delay phase, whereas {@link #isRunning()} will return true only after the delay phase
       * is complete. Non-reusable animators will always return true after they have been
       * started, because they cannot return to a non-started state.
       *
       * @return Whether the Animator has been started and not yet ended.
       */
      public boolean isStarted() {
          // Default method returns value for isRunning(). Subclasses should override to return a
          // real value.
          return isRunning();
      }
  
      /**
       * Adds a listener to the set of listeners that are sent events through the life of an
       * animation, such as start, repeat, and end.
       *
       * @param listener the listener to be added to the current set of listeners for this animation.
       */
      public void addListener(AnimatorListener listener) {
          if (mListeners == null) {
              mListeners = new ArrayList<AnimatorListener>();
          }
          mListeners.add(listener);
      }
  
      /**
       * Removes a listener from the set listening to this animation.
       *
       * @param listener the listener to be removed from the current set of listeners for this
       *                 animation.
       */
      public void removeListener(AnimatorListener listener) {
          if (mListeners == null) {
              return;
          }
          mListeners.remove(listener);
          if (mListeners.size() == 0) {
              mListeners = null;
          }
      }
  
      /**
       * Gets the set of {@link android.animation.Animator.AnimatorListener} objects that are currently
       * listening for events on this <code>Animator</code> object.
       *
       * @return ArrayList<AnimatorListener> The set of listeners.
       */
      public ArrayList<AnimatorListener> getListeners() {
          return mListeners;
      }
  
      /**
       * Adds a pause listener to this animator.
       *
       * @param listener the listener to be added to the current set of pause listeners
       * for this animation.
       */
      public void addPauseListener(AnimatorPauseListener listener) {
          if (mPauseListeners == null) {
              mPauseListeners = new ArrayList<AnimatorPauseListener>();
          }
          mPauseListeners.add(listener);
      }
  
      /**
       * Removes a pause listener from the set listening to this animation.
       *
       * @param listener the listener to be removed from the current set of pause
       * listeners for this animation.
       */
      public void removePauseListener(AnimatorPauseListener listener) {
          if (mPauseListeners == null) {
              return;
          }
          mPauseListeners.remove(listener);
          if (mPauseListeners.size() == 0) {
              mPauseListeners = null;
          }
      }
  
      /**
       * Removes all {@link #addListener(android.animation.Animator.AnimatorListener) listeners}
       * and {@link #addPauseListener(android.animation.Animator.AnimatorPauseListener)
       * pauseListeners} from this object.
       */
      public void removeAllListeners() {
          if (mListeners != null) {
              mListeners.clear();
              mListeners = null;
          }
          if (mPauseListeners != null) {
              mPauseListeners.clear();
              mPauseListeners = null;
          }
      }
  
      /**
       * Return a mask of the configuration parameters for which this animator may change, requiring
       * that it should be re-created from Resources. The default implementation returns whatever
       * value was provided through setChangingConfigurations(int) or 0 by default.
       *
       * @return Returns a mask of the changing configuration parameters, as defined by
       * {@link android.content.pm.ActivityInfo}.
       * @see android.content.pm.ActivityInfo
       * @hide
       */
      public @Config int getChangingConfigurations() {
          return mChangingConfigurations;
      }
  
      /**
       * Set a mask of the configuration parameters for which this animator may change, requiring
       * that it be re-created from resource.
       *
       * @param configs A mask of the changing configuration parameters, as
       * defined by {@link android.content.pm.ActivityInfo}.
       *
       * @see android.content.pm.ActivityInfo
       * @hide
       */
      public void setChangingConfigurations(@Config int configs) {
          mChangingConfigurations = configs;
      }
  
      /**
       * Sets the changing configurations value to the union of the current changing configurations
       * and the provided configs.
       * This method is called while loading the animator.
       * @hide
       */
      public void appendChangingConfigurations(@Config int configs) {
          mChangingConfigurations |= configs;
      }
  
      /**
       * Return a {@link android.content.res.ConstantState} instance that holds the shared state of
       * this Animator.
       * <p>
       * This constant state is used to create new instances of this animator when needed, instead
       * of re-loading it from resources. Default implementation creates a new
       * {@link AnimatorConstantState}. You can override this method to provide your custom logic or
       * return null if you don't want this animator to be cached.
       *
       * @return The ConfigurationBoundResourceCache.BaseConstantState associated to this Animator.
       * @see android.content.res.ConstantState
       * @see #clone()
       * @hide
       */
      public ConstantState<Animator> createConstantState() {
          return new AnimatorConstantState(this);
      }
  
      @Override
      public Animator clone() {
          try {
              final Animator anim = (Animator) super.clone();
              if (mListeners != null) {
                  anim.mListeners = new ArrayList<AnimatorListener>(mListeners);
              }
              if (mPauseListeners != null) {
                  anim.mPauseListeners = new ArrayList<AnimatorPauseListener>(mPauseListeners);
              }
              return anim;
          } catch (CloneNotSupportedException e) {
             throw new AssertionError();
          }
      }
  
      /**
       * This method tells the object to use appropriate information to extract
       * starting values for the animation. For example, a AnimatorSet object will pass
       * this call to its child objects to tell them to set up the values. A
       * ObjectAnimator object will use the information it has about its target object
       * and PropertyValuesHolder objects to get the start values for its properties.
       * A ValueAnimator object will ignore the request since it does not have enough
       * information (such as a target object) to gather these values.
       */
      public void setupStartValues() {
      }
  
      /**
       * This method tells the object to use appropriate information to extract
       * ending values for the animation. For example, a AnimatorSet object will pass
       * this call to its child objects to tell them to set up the values. A
       * ObjectAnimator object will use the information it has about its target object
       * and PropertyValuesHolder objects to get the start values for its properties.
       * A ValueAnimator object will ignore the request since it does not have enough
       * information (such as a target object) to gather these values.
       */
      public void setupEndValues() {
      }
  
      /**
       * Sets the target object whose property will be animated by this animation. Not all subclasses
       * operate on target objects (for example, {@link ValueAnimator}, but this method
       * is on the superclass for the convenience of dealing generically with those subclasses
       * that do handle targets.
       * <p>
       * <strong>Note:</strong> The target is stored as a weak reference internally to avoid leaking
       * resources by having animators directly reference old targets. Therefore, you should
       * ensure that animator targets always have a hard reference elsewhere.
       *
       * @param target The object being animated
       */
      public void setTarget(@Nullable Object target) {
      }
  
      // Hide reverse() and canReverse() for now since reverse() only work for simple
      // cases, like we don't support sequential, neither startDelay.
      // TODO: make reverse() works for all the Animators.
      /**
       * @hide
       */
      public boolean canReverse() {
          return false;
      }
  
      /**
       * @hide
       */
      @UnsupportedAppUsage
      public void reverse() {
          throw new IllegalStateException("Reverse is not supported");
      }
  
      // Pulse an animation frame into the animation.
      boolean pulseAnimationFrame(long frameTime) {
          // TODO: Need to find a better signal than this. There's a bug in SystemUI that's preventing
          // returning !isStarted() from working.
          return false;
      }
  
      /**
       * Internal use only.
       * This call starts the animation in regular or reverse direction without requiring them to
       * register frame callbacks. The caller will be responsible for all the subsequent animation
       * pulses. Specifically, the caller needs to call doAnimationFrame(...) for the animation on
       * every frame.
       *
       * @param inReverse whether the animation should play in reverse direction
       */
      void startWithoutPulsing(boolean inReverse) {
          if (inReverse) {
              reverse();
          } else {
              start();
          }
      }
  
      /**
       * Internal use only.
       * Skips the animation value to end/start, depending on whether the play direction is forward
       * or backward.
       *
       * @param inReverse whether the end value is based on a reverse direction. If yes, this is
       *                  equivalent to skip to start value in a forward playing direction.
       */
      void skipToEndValue(boolean inReverse) {}
  
  
      /**
       * Internal use only.
       *
       * Returns whether the animation has start/end values setup. For most of the animations, this
       * should always be true. For ObjectAnimators, the start values are setup in the initialization
       * of the animation.
       */
      boolean isInitialized() {
          return true;
      }
  
      /**
       * Internal use only.
       */
      void animateBasedOnPlayTime(long currentPlayTime, long lastPlayTime, boolean inReverse) {}
  
      /**
       * <p>An animation listener receives notifications from an animation.
       * Notifications indicate animation related events, such as the end or the
       * repetition of the animation.</p>
       */
      public static interface AnimatorListener {
  
          /**
           * <p>Notifies the start of the animation as well as the animation's overall play direction.
           * This method's default behavior is to call {@link #onAnimationStart(Animator)}. This
           * method can be overridden, though not required, to get the additional play direction info
           * when an animation starts. Skipping calling super when overriding this method results in
           * {@link #onAnimationStart(Animator)} not getting called.
           *
           * @param animation The started animation.
           * @param isReverse Whether the animation is playing in reverse.
           */
          default void onAnimationStart(Animator animation, boolean isReverse) {
              onAnimationStart(animation);
          }
  
          /**
           * <p>Notifies the end of the animation. This callback is not invoked
           * for animations with repeat count set to INFINITE.</p>
           *
           * <p>This method's default behavior is to call {@link #onAnimationEnd(Animator)}. This
           * method can be overridden, though not required, to get the additional play direction info
           * when an animation ends. Skipping calling super when overriding this method results in
           * {@link #onAnimationEnd(Animator)} not getting called.
           *
           * @param animation The animation which reached its end.
           * @param isReverse Whether the animation is playing in reverse.
           */
          default void onAnimationEnd(Animator animation, boolean isReverse) {
              onAnimationEnd(animation);
          }
  
          /**
           * <p>Notifies the start of the animation.</p>
           *
           * @param animation The started animation.
           */
          void onAnimationStart(Animator animation);
  
          /**
           * <p>Notifies the end of the animation. This callback is not invoked
           * for animations with repeat count set to INFINITE.</p>
           *
           * @param animation The animation which reached its end.
           */
          void onAnimationEnd(Animator animation);
  
          /**
           * <p>Notifies the cancellation of the animation. This callback is not invoked
           * for animations with repeat count set to INFINITE.</p>
           *
           * @param animation The animation which was canceled.
           */
          void onAnimationCancel(Animator animation);
  
          /**
           * <p>Notifies the repetition of the animation.</p>
           *
           * @param animation The animation which was repeated.
           */
          void onAnimationRepeat(Animator animation);
      }
  
      /**
       * A pause listener receives notifications from an animation when the
       * animation is {@link #pause() paused} or {@link #resume() resumed}.
       *
       * @see #addPauseListener(AnimatorPauseListener)
       */
      public static interface AnimatorPauseListener {
          /**
           * <p>Notifies that the animation was paused.</p>
           *
           * @param animation The animaton being paused.
           * @see #pause()
           */
          void onAnimationPause(Animator animation);
  
          /**
           * <p>Notifies that the animation was resumed, after being
           * previously paused.</p>
           *
           * @param animation The animation being resumed.
           * @see #resume()
           */
          void onAnimationResume(Animator animation);
      }
  
      /**
       * <p>Whether or not the Animator is allowed to run asynchronously off of
       * the UI thread. This is a hint that informs the Animator that it is
       * OK to run the animation off-thread, however the Animator may decide
       * that it must run the animation on the UI thread anyway.
       *
       * <p>Regardless of whether or not the animation runs asynchronously, all
       * listener callbacks will be called on the UI thread.</p>
       *
       * <p>To be able to use this hint the following must be true:</p>
       * <ol>
       * <li>The animator is immutable while {@link #isStarted()} is true. Requests
       *    to change duration, delay, etc... may be ignored.</li>
       * <li>Lifecycle callback events may be asynchronous. Events such as
       *    {@link Animator.AnimatorListener#onAnimationEnd(Animator)} or
       *    {@link Animator.AnimatorListener#onAnimationRepeat(Animator)} may end up delayed
       *    as they must be posted back to the UI thread, and any actions performed
       *    by those callbacks (such as starting new animations) will not happen
       *    in the same frame.</li>
       * <li>State change requests ({@link #cancel()}, {@link #end()}, {@link #reverse()}, etc...)
       *    may be asynchronous. It is guaranteed that all state changes that are
       *    performed on the UI thread in the same frame will be applied as a single
       *    atomic update, however that frame may be the current frame,
       *    the next frame, or some future frame. This will also impact the observed
       *    state of the Animator. For example, {@link #isStarted()} may still return true
       *    after a call to {@link #end()}. Using the lifecycle callbacks is preferred over
       *    queries to {@link #isStarted()}, {@link #isRunning()}, and {@link #isPaused()}
       *    for this reason.</li>
       * </ol>
       * @hide
       */
      public void setAllowRunningAsynchronously(boolean mayRunAsync) {
          // It is up to subclasses to support this, if they can.
      }
  
      /**
       * Creates a {@link ConstantState} which holds changing configurations information associated
       * with the given Animator.
       * <p>
       * When {@link #newInstance()} is called, default implementation clones the Animator.
       */
      private static class AnimatorConstantState extends ConstantState<Animator> {
  
          final Animator mAnimator;
          @Config int mChangingConf;
  
          public AnimatorConstantState(Animator animator) {
              mAnimator = animator;
              // ensure a reference back to here so that constante state is not gc'ed.
              mAnimator.mConstantState = this;
              mChangingConf = mAnimator.getChangingConfigurations();
          }
  
          @Override
          public @Config int getChangingConfigurations() {
              return mChangingConf;
          }
  
          @Override
          public Animator newInstance() {
              final Animator clone = mAnimator.clone();
              clone.mConstantState = this;
              return clone;
          }
      }
  }
  