Merge "WindowInsets: Add mandatory system gesture and tappable element insets"
diff --git a/api/current.txt b/api/current.txt
index 79a909d..d48b561 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -51957,6 +51957,7 @@
method @NonNull public android.view.WindowInsets consumeStableInsets();
method @NonNull public android.view.WindowInsets consumeSystemWindowInsets();
method @Nullable public android.view.DisplayCutout getDisplayCutout();
+ method @NonNull public android.graphics.Insets getMandatorySystemGestureInsets();
method public int getStableInsetBottom();
method public int getStableInsetLeft();
method public int getStableInsetRight();
@@ -51968,6 +51969,7 @@
method public int getSystemWindowInsetRight();
method public int getSystemWindowInsetTop();
method @NonNull public android.graphics.Insets getSystemWindowInsets();
+ method @NonNull public android.graphics.Insets getTappableElementInsets();
method public boolean hasInsets();
method public boolean hasStableInsets();
method public boolean hasSystemWindowInsets();
@@ -51983,9 +51985,11 @@
ctor public WindowInsets.Builder(@NonNull android.view.WindowInsets);
method @NonNull public android.view.WindowInsets build();
method @NonNull public android.view.WindowInsets.Builder setDisplayCutout(@Nullable android.view.DisplayCutout);
+ method @NonNull public android.view.WindowInsets.Builder setMandatorySystemGestureInsets(@NonNull android.graphics.Insets);
method @NonNull public android.view.WindowInsets.Builder setStableInsets(@NonNull android.graphics.Insets);
method @NonNull public android.view.WindowInsets.Builder setSystemGestureInsets(@NonNull android.graphics.Insets);
method @NonNull public android.view.WindowInsets.Builder setSystemWindowInsets(@NonNull android.graphics.Insets);
+ method @NonNull public android.view.WindowInsets.Builder setTappableElementInsets(@NonNull android.graphics.Insets);
}
public interface WindowManager extends android.view.ViewManager {
diff --git a/core/java/android/view/InsetsState.java b/core/java/android/view/InsetsState.java
index 2d7e179..6129b38 100644
--- a/core/java/android/view/InsetsState.java
+++ b/core/java/android/view/InsetsState.java
@@ -145,7 +145,14 @@
// TODO: set system gesture insets based on actual system gesture area.
typeInsetsMap[Type.indexOf(Type.systemGestures())] = Insets.of(legacyContentInsets);
- typeMaxInsetsMap[Type.indexOf(Type.systemGestures())] = Insets.of(legacyContentInsets);
+ typeInsetsMap[Type.indexOf(Type.mandatorySystemGestures())] =
+ Insets.of(legacyContentInsets);
+ typeInsetsMap[Type.indexOf(Type.tappableElement())] = Insets.of(legacyContentInsets);
+
+ typeMaxInsetsMap[Type.indexOf(Type.systemGestures())] = Insets.of(legacyStableInsets);
+ typeMaxInsetsMap[Type.indexOf(Type.mandatorySystemGestures())] =
+ Insets.of(legacyStableInsets);
+ typeMaxInsetsMap[Type.indexOf(Type.tappableElement())] = Insets.of(legacyStableInsets);
}
for (int type = FIRST_TYPE; type <= LAST_TYPE; type++) {
InsetsSource source = mSources.get(type);
diff --git a/core/java/android/view/WindowInsets.java b/core/java/android/view/WindowInsets.java
index f1a992c..aac0e34 100644
--- a/core/java/android/view/WindowInsets.java
+++ b/core/java/android/view/WindowInsets.java
@@ -20,14 +20,18 @@
import static android.view.WindowInsets.Type.FIRST;
import static android.view.WindowInsets.Type.IME;
import static android.view.WindowInsets.Type.LAST;
+import static android.view.WindowInsets.Type.MANDATORY_SYSTEM_GESTURES;
import static android.view.WindowInsets.Type.SIDE_BARS;
import static android.view.WindowInsets.Type.SIZE;
import static android.view.WindowInsets.Type.SYSTEM_GESTURES;
+import static android.view.WindowInsets.Type.TAPPABLE_ELEMENT;
import static android.view.WindowInsets.Type.TOP_BAR;
import static android.view.WindowInsets.Type.all;
import static android.view.WindowInsets.Type.compatSystemInsets;
import static android.view.WindowInsets.Type.indexOf;
+import static android.view.WindowInsets.Type.mandatorySystemGestures;
import static android.view.WindowInsets.Type.systemGestures;
+import static android.view.WindowInsets.Type.tappableElement;
import android.annotation.IntDef;
import android.annotation.IntRange;
@@ -223,6 +227,8 @@
assignCompatInsets(typeInsetMap, insets);
// TODO: set system gesture insets based on actual system gesture area.
typeInsetMap[indexOf(systemGestures())] = Insets.of(insets);
+ typeInsetMap[indexOf(mandatorySystemGestures())] = Insets.of(insets);
+ typeInsetMap[indexOf(tappableElement())] = Insets.of(insets);
return typeInsetMap;
}
@@ -639,15 +645,22 @@
* priority and may consume some or all touch input, e.g. due to the a system bar
* occupying it, or it being reserved for touch-only gestures.
*
+ * <p>An app can declare priority over system gestures with
+ * {@link View#setSystemGestureExclusionRects} outside of the
+ * {@link #getMandatorySystemGestureInsets() mandatory system gesture insets}.
+ *
* <p>Simple taps are guaranteed to reach the window even within the system gesture insets,
- * as long as they are outside the {@link #getSystemWindowInsets() system window insets}.
+ * as long as they are outside the {@link #getTappableElementInsets() system window insets}.
*
* <p>When {@link View#SYSTEM_UI_FLAG_LAYOUT_STABLE} is requested, an inset will be returned
* even when the system gestures are inactive due to
* {@link View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN} or
* {@link View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION}.
*
- * <p>This inset does not affect the result of {@link #isConsumed()} and cannot be consumed.
+ * <p>This inset is consumed together with the {@link #getSystemWindowInsets()
+ * system window insets} by {@link #consumeSystemWindowInsets()}.
+ *
+ * @see #getMandatorySystemGestureInsets
*/
@NonNull
public Insets getSystemGestureInsets() {
@@ -655,6 +668,60 @@
}
/**
+ * Returns the mandatory system gesture insets.
+ *
+ * <p>The mandatory system gesture insets represent the area of a window where mandatory system
+ * gestures have priority and may consume some or all touch input, e.g. due to the a system bar
+ * occupying it, or it being reserved for touch-only gestures.
+ *
+ * <p>In contrast to {@link #getSystemGestureInsets regular system gestures}, <b>mandatory</b>
+ * system gestures cannot be overriden by {@link View#setSystemGestureExclusionRects}.
+ *
+ * <p>Simple taps are guaranteed to reach the window even within the system gesture insets,
+ * as long as they are outside the {@link #getTappableElementInsets() system window insets}.
+ *
+ * <p>When {@link View#SYSTEM_UI_FLAG_LAYOUT_STABLE} is requested, an inset will be returned
+ * even when the system gestures are inactive due to
+ * {@link View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN} or
+ * {@link View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION}.
+ *
+ * <p>This inset is consumed together with the {@link #getSystemWindowInsets()
+ * system window insets} by {@link #consumeSystemWindowInsets()}.
+ *
+ * @see #getSystemGestureInsets
+ */
+ @NonNull
+ public Insets getMandatorySystemGestureInsets() {
+ return getInsets(mTypeInsetsMap, MANDATORY_SYSTEM_GESTURES);
+ }
+
+ /**
+ * Returns the tappable element insets.
+ *
+ * <p>The tappable element insets represent how much tappable elements <b>must at least</b> be
+ * inset to remain both tappable and visually unobstructed by persistent system windows.
+ *
+ * <p>This may be smaller than {@link #getSystemWindowInsets()} if the system window is
+ * largely transparent and lets through simple taps (but not necessarily more complex gestures).
+ *
+ * <p>Note that generally, tappable elements <strong>should</strong> be aligned with the
+ * {@link #getSystemWindowInsets() system window insets} instead to avoid overlapping with the
+ * system bars.
+ *
+ * <p>When {@link View#SYSTEM_UI_FLAG_LAYOUT_STABLE} is requested, an inset will be returned
+ * even when the area covered by the inset would be tappable due to
+ * {@link View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN} or
+ * {@link View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION}.
+ *
+ * <p>This inset is consumed together with the {@link #getSystemWindowInsets()
+ * system window insets} by {@link #consumeSystemWindowInsets()}.
+ */
+ @NonNull
+ public Insets getTappableElementInsets() {
+ return getInsets(mTypeInsetsMap, TAPPABLE_ELEMENT);
+ }
+
+ /**
* Returns a copy of this WindowInsets with the stable insets fully consumed.
*
* @return A modified copy of this WindowInsets
@@ -895,6 +962,41 @@
}
/**
+ * Sets mandatory system gesture insets in pixels.
+ *
+ * <p>The mandatory system gesture insets represent the area of a window where mandatory
+ * system gestures have priority and may consume some or all touch input, e.g. due to the a
+ * system bar occupying it, or it being reserved for touch-only gestures.
+ *
+ * <p>In contrast to {@link #setSystemGestureInsets regular system gestures},
+ * <b>mandatory</b> system gestures cannot be overriden by
+ * {@link View#setSystemGestureExclusionRects}.
+ *
+ * @see #getMandatorySystemGestureInsets()
+ * @return itself
+ */
+ @NonNull
+ public Builder setMandatorySystemGestureInsets(@NonNull Insets insets) {
+ WindowInsets.setInsets(mTypeInsetsMap, MANDATORY_SYSTEM_GESTURES, insets);
+ return this;
+ }
+
+ /**
+ * Sets tappable element insets in pixels.
+ *
+ * <p>The tappable element insets represent how much tappable elements <b>must at least</b>
+ * be inset to remain both tappable and visually unobstructed by persistent system windows.
+ *
+ * @see #getTappableElementInsets()
+ * @return itself
+ */
+ @NonNull
+ public Builder setTappableElementInsets(@NonNull Insets insets) {
+ WindowInsets.setInsets(mTypeInsetsMap, TAPPABLE_ELEMENT, insets);
+ return this;
+ }
+
+ /**
* Sets the insets of a specific window type in pixels.
*
* <p>The insets represents the area of a a window that is partially or fully obscured by
@@ -1041,16 +1143,18 @@
*/
public static final class Type {
- static final int FIRST = 0x1;
+ static final int FIRST = 1 << 0;
static final int TOP_BAR = FIRST;
- static final int IME = 0x2;
- static final int SIDE_BARS = 0x4;
+ static final int IME = 1 << 1;
+ static final int SIDE_BARS = 1 << 2;
- static final int SYSTEM_GESTURES = 0x8;
+ static final int SYSTEM_GESTURES = 1 << 3;
+ static final int MANDATORY_SYSTEM_GESTURES = 1 << 4;
+ static final int TAPPABLE_ELEMENT = 1 << 5;
- static final int LAST = 0x10;
- static final int SIZE = 5;
+ static final int LAST = 1 << 6;
+ static final int SIZE = 7;
static final int WINDOW_DECOR = LAST;
static int indexOf(@InsetType int type) {
@@ -1063,8 +1167,12 @@
return 2;
case SYSTEM_GESTURES:
return 3;
- case WINDOW_DECOR:
+ case MANDATORY_SYSTEM_GESTURES:
return 4;
+ case TAPPABLE_ELEMENT:
+ return 5;
+ case WINDOW_DECOR:
+ return 6;
default:
throw new IllegalArgumentException("type needs to be >= FIRST and <= LAST,"
+ " type=" + type);
@@ -1076,7 +1184,8 @@
/** @hide */
@Retention(RetentionPolicy.SOURCE)
- @IntDef(flag = true, value = { TOP_BAR, IME, SIDE_BARS, WINDOW_DECOR, SYSTEM_GESTURES })
+ @IntDef(flag = true, value = { TOP_BAR, IME, SIDE_BARS, WINDOW_DECOR, SYSTEM_GESTURES,
+ MANDATORY_SYSTEM_GESTURES, TAPPABLE_ELEMENT})
public @interface InsetType {
}
@@ -1131,6 +1240,20 @@
}
/**
+ * @see #getMandatorySystemGestureInsets
+ */
+ public static @InsetType int mandatorySystemGestures() {
+ return MANDATORY_SYSTEM_GESTURES;
+ }
+
+ /**
+ * @see #getTappableElementInsets
+ */
+ public static @InsetType int tappableElement() {
+ return TAPPABLE_ELEMENT;
+ }
+
+ /**
* @return All system bars. Includes {@link #topBar()} as well as {@link #sideBars()}, but
* not {@link #ime()}.
*/