Add API to show background behind animating windows

For the new style of Material 3 activity transitions (go/t-activity-transitions) we fully fade in and out activity windows to a solid background color (that of the activity's theme). This means we need to provide a way for activity transitions to show a solid background color behind the animating windows to fill any space that would otherwise be black. This ability should be available both to system transitions but also to apps that want to create transitions in a similar style without necessarily using exactly the system one.

The API provides a way to specify if a background should be shown behind
the animation or not. If a background is requested it is up to the
transition handler to drawn this background appropriately based on the
type of transition and task/activity info.

Test: atest CtsWindowManagerDeviceTestCases:AnimationBackgroundTests
Bug: 202844659
Change-Id: Iddee6583fb1ad83e3ec238a89030b8c284e04d03

core/api/current.txt

@@ -1314,6 +1314,7 @@ package android {
     field public static final int shouldDisableView = 16843246; // 0x10101ee
     field public static final int shouldUseDefaultUnfoldTransition = 16844364; // 0x101064c
     field public static final int showAsAction = 16843481; // 0x10102d9
+    field public static final int showBackground;
     field public static final int showClockAndComplications;
     field public static final int showDefault = 16843258; // 0x10101fa
     field public static final int showDividers = 16843561; // 0x1010329
@@ -52454,6 +52455,7 @@ package android.view.animation {
     method public int getRepeatCount();
     method public int getRepeatMode();
     method protected float getScaleFactor();
+    method public boolean getShowBackground();
     method public long getStartOffset();
     method public long getStartTime();
     method public boolean getTransformation(long, android.view.animation.Transformation);
@@ -52479,6 +52481,7 @@ package android.view.animation {
     method public void setInterpolator(android.view.animation.Interpolator);
     method public void setRepeatCount(int);
     method public void setRepeatMode(int);
+    method public void setShowBackground(boolean);
     method public void setStartOffset(long);
     method public void setStartTime(long);
     method public void setZAdjustment(int);

core/java/android/view/animation/Animation.java

@@ -209,6 +209,13 @@ public abstract class Animation implements Cloneable {
     private boolean mShowWallpaper;
     private boolean mHasRoundedCorners;
 
+    /**
+     * Whether to show a background behind the windows during the animation.
+     * @see #getShowBackground()
+     * @see #setShowBackground(boolean)
+     */
+    private boolean mShowBackground;
+
     private boolean mMore = true;
     private boolean mOneMoreTime = true;
 
@@ -266,6 +273,8 @@ public abstract class Animation implements Cloneable {
                 a.getBoolean(com.android.internal.R.styleable.Animation_showWallpaper, false));
         setHasRoundedCorners(
                 a.getBoolean(com.android.internal.R.styleable.Animation_hasRoundedCorners, false));
+        setShowBackground(
+                a.getBoolean(com.android.internal.R.styleable.Animation_showBackground, false));
 
         final int resID = a.getResourceId(com.android.internal.R.styleable.Animation_interpolator, 0);
 
@@ -697,6 +706,24 @@ public abstract class Animation implements Cloneable {
         mHasRoundedCorners = hasRoundedCorners;
     }
 
+    /**
+     * If showBackground is {@code true} and this animation is applied on a window, then the windows
+     * in the animation will animate with the background associated with this window behind them.
+     *
+     * The background comes from the {@link android.R.styleable#Theme_colorBackground} that is
+     * applied to this window through its theme.
+     *
+     * If multiple animating windows have showBackground set to {@code true} during an animation,
+     * the top most window with showBackground set to {@code true} and a valid background color
+     * takes precedence.
+     *
+     * @param showBackground Whether to show a background behind the windows during the animation.
+     * @attr ref android.R.styleable#Animation_showBackground
+     */
+    public void setShowBackground(boolean showBackground) {
+        mShowBackground = showBackground;
+    }
+
     /**
      * Gets the acceleration curve type for this animation.
      *
@@ -837,6 +864,24 @@ public abstract class Animation implements Cloneable {
         return mHasRoundedCorners;
     }
 
+    /**
+     * If showBackground is {@code true} and this animation is applied on a window, then the windows
+     * in the animation will animate with the background associated with this window behind them.
+     *
+     * The background comes from the {@link android.R.styleable#Theme_colorBackground} that is
+     * applied to this window through its theme.
+     *
+     * If multiple animating windows have showBackground set to {@code true} during an animation,
+     * the top most window with showBackground set to {@code true} and a valid background color
+     * takes precedence.
+     *
+     * @return if the background of this window should be shown behind the animating windows.
+     * @attr ref android.R.styleable#Animation_showBackground
+     */
+    public boolean getShowBackground() {
+        return mShowBackground;
+    }
+
     /**
      * <p>Indicates whether or not this animation will affect the transformation
      * matrix. For instance, a fade animation will not affect the matrix whereas

core/res/res/values/attrs.xml

@@ -6884,6 +6884,9 @@
         <!-- Special option for window animations: whether window should have rounded corners.
              @see ScreenDecorationsUtils#getWindowCornerRadius(Resources) -->
         <attr name="hasRoundedCorners" format="boolean" />
+        <!-- Special option for window animations: whether the window's background should be used as
+             a background to the animation. -->
+        <attr name="showBackground" format="boolean" />
     </declare-styleable>
 
     <declare-styleable name="AnimationSet">

core/res/res/values/public.xml

@@ -3254,6 +3254,7 @@
     <!-- @hide @SystemApi -->
     <public name="gameSessionService" />
     <public name="localeConfig" />
+    <public name="showBackground" />
   </staging-public-group>
 
   <staging-public-group type="id" first-id="0x01de0000">