WindowInsetsCompat

Added in 1.1.0

public class WindowInsetsCompat


Describes a set of insets for window content.

WindowInsetsCompats are immutable and may be expanded to include more inset types in the future. To adjust insets, use one of the supplied clone methods to obtain a new WindowInsetsCompat instance with the adjusted properties.

Summary

Nested types

public final class WindowInsetsCompat.Builder

Builder for WindowInsetsCompat.

public final class WindowInsetsCompat.Side

Class that defines different sides for insets.

public final class WindowInsetsCompat.Type

Class that defines different types of sources causing window insets.

Constants

static final @NonNull WindowInsetsCompat

A WindowInsetsCompat instance for which isConsumed returns true.

Public constructors

Constructs a new WindowInsetsCompat, copying all values from a source WindowInsetsCompat.

Public methods

@NonNull WindowInsetsCompat

This method is deprecated.

Consuming of different parts individually of a WindowInsetsCompat instance is deprecated, since WindowInsetsCompat contains many different insets.

@NonNull WindowInsetsCompat

This method is deprecated.

Consuming of different parts individually of a WindowInsetsCompat instance is deprecated, since WindowInsetsCompat contains many different insets.

@NonNull WindowInsetsCompat

This method is deprecated.

Consuming of different parts individually of a WindowInsetsCompat instance is deprecated, since WindowInsetsCompat contains many different insets.

boolean
@Nullable DisplayCutoutCompat

Returns the display cutout if there is one.

@NonNull Insets
getInsets(int typeMask)

Returns the insets of a specific set of windows causing insets, denoted by the typeMask bit mask of Types.

@NonNull Insets

Returns the insets a specific set of windows can cause, denoted by the typeMask bit mask of Types, regardless of whether that type is currently visible or not.

@NonNull Insets

This method is deprecated.

Use getInsets with mandatorySystemGestures instead.

@Nullable Rect

Returns a Rect representing the bounds of the system privacy indicator, for the current orientation, in the window space coordinates.

@Nullable RoundedCornerCompat
getRoundedCorner(int position)

Returns the RoundedCornerCompat of the given position if there is one.

int

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

int

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

int

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

int

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

@NonNull Insets

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

@NonNull Insets

This method is deprecated.

Use getInsets with systemGestures instead.

int

This method is deprecated.

Use getInsets with systemBars instead.

int

This method is deprecated.

Use getInsets with systemBars instead.

int

This method is deprecated.

Use getInsets with systemBars instead.

int

This method is deprecated.

Use getInsets with systemBars instead.

@NonNull Insets

This method is deprecated.

Use getInsets with systemBars instead.

@NonNull Insets

This method is deprecated.

Use getInsets with tappableElement instead.

boolean

Returns true if this WindowInsets has any non-zero insets.

boolean

This method is deprecated.

Use getInsetsIgnoringVisibility with systemBars instead.

boolean

This method is deprecated.

Use getInsets with systemBars instead.

int
@NonNull WindowInsetsCompat
inset(@NonNull Insets insets)

Returns a copy of this instance inset in the given directions.

@NonNull WindowInsetsCompat
inset(
    @IntRange(from = 0) int left,
    @IntRange(from = 0) int top,
    @IntRange(from = 0) int right,
    @IntRange(from = 0) int bottom
)

Returns a copy of this instance inset in the given directions.

boolean

Check if these insets have been fully consumed.

boolean

Returns true if the associated window has a round shape.

boolean
isVisible(int typeMask)

Returns whether a set of windows that may cause insets is currently visible on screen, regardless of whether it actually overlaps with this window.

@NonNull WindowInsetsCompat
replaceSystemWindowInsets(@NonNull Rect systemWindowInsets)

This method is deprecated.

use WindowInsetsCompat.Builder with setSystemWindowInsets instead.

@NonNull WindowInsetsCompat
replaceSystemWindowInsets(int left, int top, int right, int bottom)

This method is deprecated.

use WindowInsetsCompat.Builder with setSystemWindowInsets instead.

@Nullable WindowInsets
@RequiresApi(value = 20)
toWindowInsets()

Return the source WindowInsets instance used in this WindowInsetsCompat.

static @NonNull WindowInsetsCompat

Wrap an instance of WindowInsets into a WindowInsetsCompat.

static @NonNull WindowInsetsCompat

Wrap an instance of WindowInsets into a WindowInsetsCompat.

Constants

CONSUMED

Added in 1.5.0
public static final @NonNull WindowInsetsCompat CONSUMED

A WindowInsetsCompat instance for which isConsumed returns true.

This can be used during insets dispatch in the view hierarchy by returning this value from View.onApplyWindowInsets(WindowInsets) or onApplyWindowInsets to stop dispatch the insets to its children to avoid traversing the entire view hierarchy.

The application should return this instance once it has taken care of all insets on a certain level in the view hierarchy, and doesn't need to dispatch to its children anymore for better performance.

See also
isConsumed

Public constructors

WindowInsetsCompat

Added in 1.1.0
public WindowInsetsCompat(@Nullable WindowInsetsCompat src)

Constructs a new WindowInsetsCompat, copying all values from a source WindowInsetsCompat.

Parameters
@Nullable WindowInsetsCompat src

source from which values are copied

Public methods

consumeDisplayCutout

Added in 1.1.0
Deprecated in 1.5.0
public @NonNull WindowInsetsCompat consumeDisplayCutout()

Returns a copy of this WindowInsets with the cutout fully consumed.

When running on platforms with API 27 and below, this method is a no-op.

Returns
@NonNull WindowInsetsCompat

A modified copy of this WindowInsets

consumeStableInsets

Added in 1.1.0
Deprecated in 1.5.0
public @NonNull WindowInsetsCompat consumeStableInsets()

Returns a copy of this WindowInsets with the stable insets fully consumed.

When running on platforms with API 20 and below, this method always returns null.

Returns
@NonNull WindowInsetsCompat

A modified copy of this WindowInsetsCompat

consumeSystemWindowInsets

Added in 1.1.0
Deprecated in 1.5.0
public @NonNull WindowInsetsCompat consumeSystemWindowInsets()

Returns a copy of this WindowInsets with the system window insets fully consumed.

When running on platforms with API 19 and below, this method always returns null.

Returns
@NonNull WindowInsetsCompat

A modified copy of this WindowInsets

equals

public boolean equals(Object o)

getDisplayCutout

Added in 1.1.0
public @Nullable DisplayCutoutCompat getDisplayCutout()

Returns the display cutout if there is one.

When running on platforms with API 27 and below, this method always returns null.

Returns
@Nullable DisplayCutoutCompat

the display cutout or null if there is none

getInsets

Added in 1.5.0
public @NonNull Insets getInsets(int typeMask)

Returns the insets of a specific set of windows causing insets, denoted by the typeMask bit mask of Types. When running on devices with API Level 29 and before, the returned insets are an approximation based on the information available. This is especially true for the IME type, which currently only works when running on devices with SDK level 23 and above.

Parameters
int typeMask

Bit mask of Types to query the insets for.

Returns
@NonNull Insets

The insets.

getInsetsIgnoringVisibility

Added in 1.5.0
public @NonNull Insets getInsetsIgnoringVisibility(int typeMask)

Returns the insets a specific set of windows can cause, denoted by the typeMask bit mask of Types, regardless of whether that type is currently visible or not.

The insets represents the area of a a window that that may be partially or fully obscured by the system window identified by typeMask. 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 inset returned here will still provide the inset associated with the status bar being shown.

When running on devices with API Level 29 and before, the returned insets are an approximation based on the information available. This is especially true for the IME type, which currently only works when running on devices with SDK level 23 and above.
Parameters
int typeMask

Bit mask of Types to query the insets for.

Returns
@NonNull Insets

The insets.

Throws
java.lang.IllegalArgumentException

If the caller tries to query ime. Insets are not available if the IME isn't visible as the height of the IME is dynamic depending on the EditorInfo of the currently focused view, as well as the UI state of the IME.

getMandatorySystemGestureInsets

Added in 1.2.0
Deprecated in 1.5.0
public @NonNull Insets getMandatorySystemGestureInsets()

Returns the mandatory system gesture insets.

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.

getPrivacyIndicatorBounds

public @Nullable Rect getPrivacyIndicatorBounds()

Returns a Rect representing the bounds of the system privacy indicator, for the current orientation, in the window space coordinates. This method returns null if the system component doesn't have such indicators or the bounds have been consumed.

getRoundedCorner

Added in 1.16.0
public @Nullable RoundedCornerCompat getRoundedCorner(int position)

Returns the RoundedCornerCompat of the given position if there is one.

Parameters
int position

the position of the rounded corner on the display. The value should be one of the following: POSITION_TOP_LEFT, POSITION_TOP_RIGHT, POSITION_BOTTOM_RIGHT, POSITION_BOTTOM_LEFT.

Returns
@Nullable RoundedCornerCompat

the rounded corner of the given position. Returns null if there is none or the rounded corner area is not inside the bounds of the window.

getStableInsetBottom

Added in 1.1.0
Deprecated in 1.5.0
public int getStableInsetBottom()

Returns the bottom stable inset in pixels.

The stable inset represents the area of a full-screen window that may 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.

When running on platforms with API 20 and below, this method always returns 0.

Returns
int

The bottom stable inset

getStableInsetLeft

Added in 1.1.0
Deprecated in 1.5.0
public int getStableInsetLeft()

Returns the left stable inset in pixels.

The stable inset represents the area of a full-screen window that may 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.

When running on platforms with API 20 and below, this method always returns 0.

Returns
int

The left stable inset

getStableInsetRight

Added in 1.1.0
Deprecated in 1.5.0
public int getStableInsetRight()

Returns the right stable inset in pixels.

The stable inset represents the area of a full-screen window that may 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.

When running on platforms with API 20 and below, this method always returns 0.

Returns
int

The right stable inset

getStableInsetTop

Added in 1.1.0
Deprecated in 1.5.0
public int getStableInsetTop()

Returns the top stable inset in pixels.

The stable inset represents the area of a full-screen window that may 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.

When running on platforms with API 20 and below, this method always returns 0.

getStableInsets

Added in 1.2.0
Deprecated in 1.5.0
public @NonNull Insets getStableInsets()

Returns the stable insets in pixels.

The stable inset represents the area of a full-screen window that may 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.

Returns
@NonNull Insets

The stable insets

getSystemGestureInsets

Added in 1.2.0
Deprecated in 1.5.0
public @NonNull Insets getSystemGestureInsets()

Returns the system gesture insets.

The system gesture insets represent the area of a window where 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.

An app can declare priority over system gestures with setSystemGestureExclusionRects outside of the mandatory system gesture insets.

getSystemWindowInsetBottom

Added in 1.1.0
Deprecated in 1.5.0
public int getSystemWindowInsetBottom()

Returns the bottom system window inset in pixels.

The system window inset represents the area of a full-screen window that is partially or fully obscured by the status bar, navigation bar, IME or other system windows.

When running on platforms with API 19 and below, this method always returns 0.

Returns
int

The bottom system window inset

getSystemWindowInsetLeft

Added in 1.1.0
Deprecated in 1.5.0
public int getSystemWindowInsetLeft()

Returns the left system window inset in pixels.

The system window inset represents the area of a full-screen window that is partially or fully obscured by the status bar, navigation bar, IME or other system windows.

When running on platforms with API 19 and below, this method always returns 0.

Returns
int

The left system window inset

getSystemWindowInsetRight

Added in 1.1.0
Deprecated in 1.5.0
public int getSystemWindowInsetRight()

Returns the right system window inset in pixels.

The system window inset represents the area of a full-screen window that is partially or fully obscured by the status bar, navigation bar, IME or other system windows.

When running on platforms with API 19 and below, this method always returns 0.

Returns
int

The right system window inset

getSystemWindowInsetTop

Added in 1.1.0
Deprecated in 1.5.0
public int getSystemWindowInsetTop()

Returns the top system window inset in pixels.

The system window inset represents the area of a full-screen window that is partially or fully obscured by the status bar, navigation bar, IME or other system windows.

When running on platforms with API 19 and below, this method always returns 0.

Returns
int

The top system window inset

getSystemWindowInsets

Added in 1.2.0
Deprecated in 1.5.0
public @NonNull Insets getSystemWindowInsets()

Returns the system window insets in pixels.

The system window inset represents the area of a full-screen window that is partially or fully obscured by the status bar, navigation bar, IME or other system windows.

Returns
@NonNull Insets

The system window insets

getTappableElementInsets

Added in 1.2.0
Deprecated in 1.5.0
public @NonNull Insets getTappableElementInsets()

Returns the tappable element insets.

The tappable element insets represent how much tappable elements must at least be inset to remain both tappable and visually unobstructed by persistent system windows.

This may be smaller than getSystemWindowInsets if the system window is largely transparent and lets through simple taps (but not necessarily more complex gestures).

hasInsets

Added in 1.1.0
public boolean hasInsets()

Returns true if this WindowInsets has any non-zero insets.

When running on platforms with API 19 and below, this method always returns false.

Returns