Add API to query whether animators are enabled

Animators can be scaled to have zero duration globally in any device.
This can happen either via Developer Options (an uncommon path) or
Battery Saver mode (much more common for real users).
In general, this works fine; it just causes app animations to be jump-cuts
instead (which is the desired effect, either to make transitions faster
(Developer Options setting) or to optimize battery usage by rendering
fewer frames (Battery Saver mode).

But sometimes, choreographed animations can have undesired artifacts. For
example, an animation that calls an end listener to restart itself
will end up doing this almost constantly due to this effect. Other artifacts
can also occur, such as intermediate results in a complex choreography of
multiple animations can show several intermediate results in a way that is
confusing to the user.

For these cases, there is nothing that the platform can do to automatically
determine how to best handle the result. Instead, we surface this new
API to help developers discover this behavior and compensate accordingly.

Bug: 31052471 Animation playback is abnormally fast during Battery saver mode
Test: unit tests, CTS test upcoming

Change-Id: Id7ef1a9652ac5c6cdaca0c126756e82582d49b1c

4 files changed, 20 insertions, 0 deletions

diff --git a/api/current.txt b/api/current.txt
index 0a8965f7aeaf..491883bc0951 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -3265,6 +3265,7 @@ package android.animation {
   public class ValueAnimator extends android.animation.Animator {
     ctor public ValueAnimator();
     method public void addUpdateListener(android.animation.ValueAnimator.AnimatorUpdateListener);
+    method public static boolean areAnimatorsEnabled();
     method public float getAnimatedFraction();
     method public java.lang.Object getAnimatedValue();
     method public java.lang.Object getAnimatedValue(java.lang.String);
diff --git a/api/system-current.txt b/api/system-current.txt
index 2b5c33d09cca..519bfb81fead 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -3380,6 +3380,7 @@ package android.animation {
   public class ValueAnimator extends android.animation.Animator {
     ctor public ValueAnimator();
     method public void addUpdateListener(android.animation.ValueAnimator.AnimatorUpdateListener);
+    method public static boolean areAnimatorsEnabled();
     method public float getAnimatedFraction();
     method public java.lang.Object getAnimatedValue();
     method public java.lang.Object getAnimatedValue(java.lang.String);
diff --git a/api/test-current.txt b/api/test-current.txt
index 4de2c6173b2e..841fe431524d 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -3265,6 +3265,7 @@ package android.animation {
   public class ValueAnimator extends android.animation.Animator {
     ctor public ValueAnimator();
     method public void addUpdateListener(android.animation.ValueAnimator.AnimatorUpdateListener);
+    method public static boolean areAnimatorsEnabled();
     method public float getAnimatedFraction();
     method public java.lang.Object getAnimatedValue();
     method public java.lang.Object getAnimatedValue(java.lang.String);
diff --git a/core/java/android/animation/ValueAnimator.java b/core/java/android/animation/ValueAnimator.java
index a09c9204239e..ed7e89dff353 100644
--- a/core/java/android/animation/ValueAnimator.java
+++ b/core/java/android/animation/ValueAnimator.java
@@ -276,6 +276,23 @@ public class ValueAnimator extends Animator implements AnimationHandler.Animatio
     }
 
     /**
+     * Returns whether animators are currently enabled, system-wide. By default, all
+     * animators are enabled. This can change if either the user sets a Developer Option
+     * to set the animator duration scale to 0 or by Battery Savery mode being enabled
+     * (which disables all animations).
+     *
+     * <p>Developers should not typically need to call this method, but should an app wish
+     * to show a different experience when animators are disabled, this return value
+     * can be used as a decider of which experience to offer.
+     *
+     * @return boolean Whether animators are currently enabled. The default value is
+     * <code>true</code>.
+     */
+    public static boolean areAnimatorsEnabled() {
+        return !(sDurationScale == 0);
+    }
+
+    /**
      * Creates a new ValueAnimator object. This default constructor is primarily for
      * use internally; the factory methods which take parameters are more generally
      * useful.