Add new wallpaper features for insets and offsets.

Issue #17394151: WallpaperService / Engines need to get notified
of WindowInsets

Issue #17394203 Wallpapers need a system API to be shifted in order
to support burn in protection

Adds a new API on WallpaperManager to set additional offsets to
make wallpapers extend beyond the display size.

Insets are now reported to wallpapers, to use as they may.  This
includes information about the above offsets, so they can place
their content within the visible area.  And to help with this, also
expose the stable offsets APIs in WindowInsets which is also very
useful information for the wallpaper.

Another new API on WallpaperManager to set a raw offset to apply
to the wallpaper window, forcing it to move on the screen regardless
of what the wallpaper is drawing.

Fix wallpapers when used with overscan enabled, so they still extend
out across the entire screen.  Conveniently, the above new window
insets information is very useful for this case as well!

And a new wallpaper test app for all this stuff.

Change-Id: I287ee36581283dd34607609fcd3170d99d120d8e

1 files changed, 48 insertions, 6 deletions

diff --git a/core/java/android/view/WindowInsets.java b/core/java/android/view/WindowInsets.java
index 571a8f0..24c3c1a 100644
--- a/core/java/android/view/WindowInsets.java
+++ b/core/java/android/view/WindowInsets.java
@@ -378,35 +378,75 @@ public final class WindowInsets {
     }
 
     /**
-     * @hide
+     * Returns the top stable inset in pixels.
+     *
+     * <p>The stable inset represents the area of a full-screen window that <b>may</b> be
+     * partially or fully obscured by the system UI elements.  This value does not change
+     * based on the visibility state of those elements; for example, if the status bar is
+     * normally shown, but temporarily hidden, the stable inset will still provide the inset
+     * associated with the status bar being shown.</p>
+     *
+     * @return The top stable inset
      */
     public int getStableInsetTop() {
         return mStableInsets.top;
     }
 
     /**
-     * @hide
+     * Returns the left stable inset in pixels.
+     *
+     * <p>The stable inset represents the area of a full-screen window that <b>may</b> be
+     * partially or fully obscured by the system UI elements.  This value does not change
+     * based on the visibility state of those elements; for example, if the status bar is
+     * normally shown, but temporarily hidden, the stable inset will still provide the inset
+     * associated with the status bar being shown.</p>
+     *
+     * @return The left stable inset
      */
     public int getStableInsetLeft() {
         return mStableInsets.left;
     }
 
     /**
-     * @hide
+     * Returns the right stable inset in pixels.
+     *
+     * <p>The stable inset represents the area of a full-screen window that <b>may</b> be
+     * partially or fully obscured by the system UI elements.  This value does not change
+     * based on the visibility state of those elements; for example, if the status bar is
+     * normally shown, but temporarily hidden, the stable inset will still provide the inset
+     * associated with the status bar being shown.</p>
+     *
+     * @return The right stable inset
      */
     public int getStableInsetRight() {
         return mStableInsets.right;
     }
 
     /**
-     * @hide
+     * Returns the bottom stable inset in pixels.
+     *
+     * <p>The stable inset represents the area of a full-screen window that <b>may</b> be
+     * partially or fully obscured by the system UI elements.  This value does not change
+     * based on the visibility state of those elements; for example, if the status bar is
+     * normally shown, but temporarily hidden, the stable inset will still provide the inset
+     * associated with the status bar being shown.</p>
+     *
+     * @return The bottom stable inset
      */
     public int getStableInsetBottom() {
         return mStableInsets.bottom;
     }
 
     /**
-     * @hide
+     * Returns true if this WindowInsets has nonzero stable insets.
+     *
+     * <p>The stable inset represents the area of a full-screen window that <b>may</b> be
+     * partially or fully obscured by the system UI elements.  This value does not change
+     * based on the visibility state of those elements; for example, if the status bar is
+     * normally shown, but temporarily hidden, the stable inset will still provide the inset
+     * associated with the status bar being shown.</p>
+     *
+     * @return true if any of the stable inset values are nonzero
      */
     public boolean hasStableInsets() {
         return mStableInsets.top != 0 || mStableInsets.left != 0 || mStableInsets.right != 0
@@ -414,7 +454,9 @@ public final class WindowInsets {
     }
 
     /**
-     * @hide
+     * Returns a copy of this WindowInsets with the stable insets fully consumed.
+     *
+     * @return A modified copy of this WindowInsets
      */
     public WindowInsets consumeStableInsets() {
         final WindowInsets result = new WindowInsets(this);