Merge "Unhide WindowInsets#inset with insets argument" into rvc-dev am: 555a54a900

Change-Id: I432934d832f595b05d48cc80e1f321ba89a42341

api/current.txt

@@ -55488,6 +55488,7 @@ package android.view {
     method public boolean hasInsets();
     method @Deprecated public boolean hasStableInsets();
     method @Deprecated public boolean hasSystemWindowInsets();
+    method @NonNull public android.view.WindowInsets inset(@NonNull android.graphics.Insets);
     method @NonNull public android.view.WindowInsets inset(@IntRange(from=0) int, @IntRange(from=0) int, @IntRange(from=0) int, @IntRange(from=0) int);
     method public boolean isConsumed();
     method public boolean isRound();

core/java/android/view/WindowInsets.java

@@ -858,11 +858,21 @@ public final class WindowInsets {
     /**
      * Returns a copy of this instance inset in the given directions.
      *
+     * This is intended for dispatching insets to areas of the window that are smaller than the
+     * current area.
+     *
+     * <p>Example:
+     * <pre>
+     * childView.dispatchApplyWindowInsets(insets.inset(childMargins));
+     * </pre>
+     *
+     * @param insets the amount of insets to remove from all sides.
+     *
      * @see #inset(int, int, int, int)
-     * @hide
      */
     @NonNull
-    public WindowInsets inset(Insets insets) {
+    public WindowInsets inset(@NonNull Insets insets) {
+        Objects.requireNonNull(insets);
         return inset(insets.left, insets.top, insets.right, insets.bottom);
     }
 
@@ -884,6 +894,8 @@ public final class WindowInsets {
      * @param bottom the amount of insets to remove from the bottom. Must be non-negative.
      *
      * @return the inset insets
+     *
+     * @see #inset(Insets)
      */
     @NonNull
     public WindowInsets inset(@IntRange(from = 0) int left, @IntRange(from = 0) int top,