WindowInsets | API reference | Android Developers (original) (raw)

public final class WindowInsets
extends [Object](/reference/java/lang/Object) ``

Describes a set of insets for window content.

WindowInsets 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 WindowInsets instance with the adjusted properties.

Note: Before [P](/reference/android/os/Build.VERSION%5FCODES#P), WindowInsets instances were only immutable during a single layout pass (i.e. would return the same values between[View.onApplyWindowInsets](/reference/android/view/View#onApplyWindowInsets%28android.view.WindowInsets%29) and [View.onLayout](/reference/android/view/View#onLayout%28boolean,%20int,%20int,%20int,%20int%29), but could return other values otherwise). Starting with [P](/reference/android/os/Build.VERSION%5FCODES#P), WindowInsets are always immutable and implement equality.

Summary

Nested classes
class	WindowInsets.Builder Builder for WindowInsets.
class	WindowInsets.Side Class that defines different sides for insets.
class	WindowInsets.Type Class that defines different types of sources causing window insets.

Fields
public static finalWindowInsets	CONSUMED A WindowInsets instance for which isConsumed() returns true.

Public constructors
WindowInsets(WindowInsets src) Construct a new WindowInsets, copying all values from a source WindowInsets.

Public methods
WindowInsets	consumeDisplayCutout() This method was deprecated in API level 30. Consuming of different parts individually of a WindowInsets instance is deprecated, since WindowInsets contains many different insets. Use CONSUMED instead to stop dispatching insets.
WindowInsets	consumeStableInsets() This method was deprecated in API level 30. Consuming of different parts individually of a WindowInsets instance is deprecated, since WindowInsets contains many different insets. Use CONSUMED instead to stop dispatching insets. On R, this method has no effect.
WindowInsets	consumeSystemWindowInsets() This method was deprecated in API level 30. Consuming of different parts individually of a WindowInsets instance is deprecated, since WindowInsets contains many different insets. Use CONSUMED instead to stop dispatching insets.
boolean	equals(Object o) Indicates whether some other object is "equal to" this one.
List<Rect>	getBoundingRects(int typeMask) Returns a list of Rects, each of which is the bounding rectangle for an area that is being partially or fully obscured inside the window.
List<Rect>	getBoundingRectsIgnoringVisibility(int typeMask) Returns a list of Rects, each of which is the bounding rectangle for an area that can be partially or fully obscured inside the window, regardless of whether that type is currently visible or not.
DisplayCutout	getDisplayCutout() Returns the display cutout if there is one.
DisplayShape	getDisplayShape() Returns the display shape in the coordinate space of the window.
Size	getFrame() Returns the assumed size of the window, relative to which the getInsets(int) andgetBoundingRects(int) have been calculated.
Insets	getInsets(int typeMask) Returns the insets of a specific set of windows causing insets, denoted by thetypeMask bit mask of Types.
Insets	getInsetsIgnoringVisibility(int typeMask) Returns the insets a specific set of windows can cause, denoted by thetypeMask bit mask of Types, regardless of whether that type is currently visible or not.
Insets	getMandatorySystemGestureInsets() This method was deprecated in API level 30. Use getInsets(int) with Type.mandatorySystemGestures() instead.
Rect	getPrivacyIndicatorBounds() Returns the Rect of the maximum bounds of the system privacy indicator, for the current orientation, in relative coordinates, or null if the bounds have not been loaded yet.
RoundedCorner	getRoundedCorner(int position) Returns the RoundedCorner of the given position if there is one.
int	getStableInsetBottom() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
int	getStableInsetLeft() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
int	getStableInsetRight() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
int	getStableInsetTop() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
Insets	getStableInsets() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
Insets	getSystemGestureInsets() This method was deprecated in API level 30. Use getInsets(int) with Type.systemGestures() instead.
int	getSystemWindowInsetBottom() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars() instead.
int	getSystemWindowInsetLeft() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars() instead.
int	getSystemWindowInsetRight() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars() instead.
int	getSystemWindowInsetTop() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars() instead.
Insets	getSystemWindowInsets() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars()
Insets	getTappableElementInsets() This method was deprecated in API level 30. Use getInsets(int) with Type.tappableElement() instead.
boolean	hasInsets() Returns true if this WindowInsets has any nonzero insets.
boolean	hasStableInsets() This method was deprecated in API level 30. Use getInsetsIgnoringVisibility(int) with Type.systemBars() instead.
boolean	hasSystemWindowInsets() This method was deprecated in API level 30. Use getInsets(int) with Type.systemBars() instead.
int	hashCode() Returns a hash code value for the object.
WindowInsets	inset(int left, int top, int right, int bottom) Returns a copy of this instance inset in the given directions.
WindowInsets	inset(Insets insets) Returns a copy of this instance inset in the given directions.
boolean	isConsumed() Check if these insets have been fully consumed.
boolean	isRound() 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.
WindowInsets	replaceSystemWindowInsets(int left, int top, int right, int bottom) This method was deprecated in API level 29. use Builder#Builder(WindowInsets) withBuilder.setSystemWindowInsets(Insets) instead.
WindowInsets	replaceSystemWindowInsets(Rect systemWindowInsets) This method was deprecated in API level 29. use Builder#Builder(WindowInsets) withBuilder.setSystemWindowInsets(Insets) instead.
String	toString() Returns a string representation of the object.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Fields

Public constructors

WindowInsets

public WindowInsets (WindowInsets src)

Construct a new WindowInsets, copying all values from a source WindowInsets.

Parameters
src	WindowInsets: Source to copy insets from

Public methods

consumeDisplayCutout

public WindowInsets consumeDisplayCutout ()

This method was deprecated in API level 30.
Consuming of different parts individually of a [WindowInsets](/reference/android/view/WindowInsets) instance is deprecated, since [WindowInsets](/reference/android/view/WindowInsets) contains many different insets. Use [CONSUMED](/reference/android/view/WindowInsets#CONSUMED) instead to stop dispatching insets.

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

Returns
WindowInsets	A modified copy of this WindowInsets. This value cannot be null.

consumeStableInsets

public WindowInsets consumeStableInsets ()

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

Returns
WindowInsets	A modified copy of this WindowInsets. This value cannot be null.

consumeSystemWindowInsets

public WindowInsets consumeSystemWindowInsets ()

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

Returns
WindowInsets	A modified copy of this WindowInsets. This value cannot be null.

equals

public boolean equals (Object o)

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference valuex, x.equals(x) should returntrue.
It is symmetric: for any non-null reference valuesx and y, x.equals(y) should return true if and only ify.equals(x) returns true.
It is transitive: for any non-null reference valuesx, y, and z, ifx.equals(y) returns true andy.equals(z) returns true, thenx.equals(z) should return true.
It is consistent: for any non-null reference valuesx and y, multiple invocations ofx.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x,x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters
o	Object: This value may be null.

Returns
boolean	true if this object is the same as the obj argument; false otherwise.

getBoundingRects

public List<Rect> getBoundingRects (int typeMask)

Returns a list of [Rect](/reference/android/graphics/Rect)s, each of which is the bounding rectangle for an area that is being partially or fully obscured inside the window.

May be used with or instead of [Insets](/reference/android/graphics/Insets) for finer avoidance of regions that may be partially obscuring the window but may be smaller than those provided by[getInsets(int)](/reference/android/view/WindowInsets#getInsets%28int%29).

The [Rect](/reference/android/graphics/Rect)s returned are always cropped to the bounds of the window frame and their coordinate values are relative to the [getFrame()](/reference/android/view/WindowInsets#getFrame%28%29), regardless of the window's position on screen.

If inset by [inset(Insets)](/reference/android/view/WindowInsets#inset%28android.graphics.Insets%29), bounding rects that intersect with the provided insets will be resized to only include the intersection with the remaining frame. Bounding rects may be completely removed if they no longer intersect with the new instance.

Parameters
typeMask	int: the insets type for which to obtain the bounding rectangles. Value is either 0 or a combination of the following:

Returns
List<Rect>	the bounding rectangles. This value cannot be null.

getBoundingRectsIgnoringVisibility

public List<Rect> getBoundingRectsIgnoringVisibility (int typeMask)

Returns a list of [Rect](/reference/android/graphics/Rect)s, each of which is the bounding rectangle for an area that can be partially or fully obscured inside the window, regardless of whether that type is currently visible or not.

The bounding rects represent areas of a window that may be partially or fully obscured by the type. 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 bounding rects returned here will provide the rects associated with the status bar being shown.

May be used with or instead of [Insets](/reference/android/graphics/Insets) for finer avoidance of regions that may be partially obscuring the window but may be smaller than those provided by[getInsetsIgnoringVisibility(int)](/reference/android/view/WindowInsets#getInsetsIgnoringVisibility%28int%29).

Parameters
typeMask	int: the insets type for which to obtain the bounding rectangles. Value is either 0 or a combination of the following:

Returns
List<Rect>	the bounding rectangles. This value cannot be null.

Throws
IllegalArgumentException	If the caller tries to query Type.ime(). Bounding rects are not available if the IME isn't visible as the height of the IME is dynamic depending on theEditorInfo of the currently focused view, as well as the UI state of the IME.

getDisplayShape

public DisplayShape getDisplayShape ()

Returns the display shape in the coordinate space of the window.

Returns
DisplayShape	the display shape. This value may be null.

getFrame

public Size getFrame ()

Returns the assumed size of the window, relative to which the [getInsets(int)](/reference/android/view/WindowInsets#getInsets%28int%29) and[getBoundingRects(int)](/reference/android/view/WindowInsets#getBoundingRects%28int%29) have been calculated.

May be used with [getBoundingRects(int)](/reference/android/view/WindowInsets#getBoundingRects%28int%29) to better understand their position within the window, such as the area between the edge of a bounding rect and the edge of the window.

Note: the size may not match the actual size of the window, which is determined during the layout pass - as [WindowInsets](/reference/android/view/WindowInsets) are dispatched before layout.

Caution: using this value in determining the actual window size may make the result of layout passes unstable and should be avoided.

Returns
Size	the assumed size of the window during the inset calculation. This value cannot be null.

getInsets

public Insets getInsets (int typeMask)

Returns the insets of a specific set of windows causing insets, denoted by thetypeMask bit mask of [Type](/reference/android/view/WindowInsets.Type)s.

Parameters
typeMask	int: Bit mask of Types to query the insets for. Value is either 0 or a combination of the following:

Returns
Insets	The insets. This value cannot be null.

getInsetsIgnoringVisibility

public Insets getInsetsIgnoringVisibility (int typeMask)

Returns the insets a specific set of windows can cause, denoted by thetypeMask bit mask of [Type](/reference/android/view/WindowInsets.Type)s, 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 type. 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.

Parameters
typeMask	int: Bit mask of Types to query the insets for. Value is either 0 or a combination of the following:

Returns
Insets	The insets. This value cannot be null.

Throws
IllegalArgumentException	If the caller tries to query Type.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.

getPrivacyIndicatorBounds

public Rect getPrivacyIndicatorBounds ()

Returns the [Rect](/reference/android/graphics/Rect) of the maximum bounds of the system privacy indicator, for the current orientation, in relative coordinates, or null if the bounds have not been loaded yet.

The privacy indicator bounds are determined by SystemUI, and subsequently loaded once the StatusBar window has been created and attached. The bounds for all rotations are calculated and loaded at once, and this value is only expected to ever change on display or font scale changes. As long as there is a StatusBar window, this value should not be expected to be null.

The privacy indicator shows over apps when an app uses the microphone or camera permissions, while an app is in immersive mode.

Returns
Rect	A rectangle representing the maximum bounds of the indicator

getStableInsetBottom

public int getStableInsetBottom ()

This method was deprecated in API level 30.
Use [getInsetsIgnoringVisibility(int)](/reference/android/view/WindowInsets#getInsetsIgnoringVisibility%28int%29) with [Type.systemBars()](/reference/android/view/WindowInsets.Type#systemBars%28%29) instead.

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.

Returns
int	The bottom stable inset

getStableInsetLeft

public int getStableInsetLeft ()

Returns the left stable inset in pixels.

Returns
int	The left stable inset

getStableInsetRight

public int getStableInsetRight ()

Returns the right stable inset in pixels.

Returns
int	The right stable inset

getStableInsetTop

public int getStableInsetTop ()

Returns the top stable inset in pixels.

Returns
int	The top stable inset

getStableInsets

public Insets getStableInsets ()

Returns the stable insets in pixels.

Returns
Insets	The stable insets. This value cannot be null.

getSystemWindowInsetBottom

public int getSystemWindowInsetBottom ()

This method was deprecated in API level 30.
Use [getInsets(int)](/reference/android/view/WindowInsets#getInsets%28int%29) with [Type.systemBars()](/reference/android/view/WindowInsets.Type#systemBars%28%29) instead.

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.

Returns
int	The bottom system window inset

getSystemWindowInsetLeft

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.

Returns
int	The left system window inset

getSystemWindowInsetRight

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.

Returns
int	The right system window inset

getSystemWindowInsetTop

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.

Returns
int	The top system window inset

getSystemWindowInsets

public 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
Insets	The system window insets. This value cannot be null.

hasInsets

public boolean hasInsets ()

Returns true if this WindowInsets has any nonzero insets.

Returns
boolean	true if any inset values are nonzero

hasStableInsets

public boolean hasStableInsets ()

Returns true if this WindowInsets has nonzero stable insets.

Returns
boolean	true if any of the stable inset values are nonzero

hasSystemWindowInsets

public boolean hasSystemWindowInsets ()

Returns true if this WindowInsets has nonzero system window insets.

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
boolean	true if any of the system window inset values are nonzero

hashCode

public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by[HashMap](/reference/java/util/HashMap).

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the [equals](/reference/java/lang/Object#equals%28java.lang.Object%29) method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the [equals](/reference/java/lang/Object#equals%28java.lang.Object%29) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns
int	a hash code value for this object.

inset

public WindowInsets inset (int left, int top, int right, int bottom)

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.

Example:

childView.dispatchApplyWindowInsets(insets.inset( childMarginLeft, childMarginTop, childMarginBottom, childMarginRight));

Parameters
left	int: the amount of insets to remove from the left. Must be non-negative. Value is 0 or greater
top	int: the amount of insets to remove from the top. Must be non-negative. Value is 0 or greater
right	int: the amount of insets to remove from the right. Must be non-negative. Value is 0 or greater
bottom	int: the amount of insets to remove from the bottom. Must be non-negative. Value is 0 or greater

Returns
WindowInsets	the inset insets. This value cannot be null.

inset

public WindowInsets inset (Insets insets)

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.

Example:

childView.dispatchApplyWindowInsets(insets.inset(childMargins));

Parameters
insets	Insets: the amount of insets to remove from all sides. This value cannot be null.

Returns
WindowInsets	This value cannot be null.

isConsumed

public boolean isConsumed ()

Check if these insets have been fully consumed.

Insets are considered "consumed" if the applicable consume* methods have been called such that all insets have been set to zero. This affects propagation of insets through the view hierarchy; insets that have not been fully consumed will continue to propagate down to child views.

The result of this method is equivalent to the return value of[View.fitSystemWindows(android.graphics.Rect)](/reference/android/view/View#fitSystemWindows%28android.graphics.Rect%29).

Returns
boolean	true if the insets have been fully consumed.

isRound

public boolean isRound ()

Returns true if the associated window has a round shape.

A round window's left, top, right and bottom edges reach all the way to the associated edges of the window but the corners may not be visible. Views responding to round insets should take care to not lay out critical elements within the corners where they may not be accessible.

Returns
boolean	True if the window is round

isVisible

public 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.

Parameters
typeMask	int: Bit mask of Types to query visibility status. Value is either 0 or a combination of the following:

Returns
boolean	true if and only if all windows included in typeMask are currently visible on screen.

replaceSystemWindowInsets

public WindowInsets replaceSystemWindowInsets (int left, int top, int right, int bottom)

This method was deprecated in API level 29.
use Builder#Builder(WindowInsets) with[Builder.setSystemWindowInsets(Insets)](/reference/android/view/WindowInsets.Builder#setSystemWindowInsets%28android.graphics.Insets%29) instead.

Returns a copy of this WindowInsets with selected system window insets replaced with new values.

Note: If the system window insets are already consumed, this method will return them unchanged on [Q](/reference/android/os/Build.VERSION%5FCODES#Q) and later. Prior to[Q](/reference/android/os/Build.VERSION%5FCODES#Q), the new values were applied regardless of whether they were consumed, and this method returns invalid non-zero consumed insets.

Parameters
left	int: New left inset in pixels
top	int: New top inset in pixels
right	int: New right inset in pixels
bottom	int: New bottom inset in pixels

Returns
WindowInsets	A modified copy of this WindowInsets. This value cannot be null.

replaceSystemWindowInsets

public WindowInsets replaceSystemWindowInsets (Rect systemWindowInsets)

Returns a copy of this WindowInsets with selected system window insets replaced with new values.

Parameters
systemWindowInsets	Rect: New system window insets. Each field is the inset in pixels for that edge

Returns
WindowInsets	A modified copy of this WindowInsets. This value cannot be null.

toString

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.