# Print output for @column tags ?> WindowInsets - Android SDK | Android Developers

Most visited

Recently visited

WindowInsets

public final class WindowInsets
extends Object

java.lang.Object
   ↳ android.view.WindowInsets


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, WindowInsets instances were only immutable during a single layout pass (i.e. would return the same values between View#onApplyWindowInsets and View#onLayout, but could return other values otherwise). Starting with P, WindowInsets are always immutable and implement equality.

See also:

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 final WindowInsets 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 is deprecated. 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 is deprecated. 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 is deprecated. 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.

DisplayCutout getDisplayCutout()

Returns the display cutout if there is one.

Insets getInsets(int typeMask)

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

Insets getInsetsIgnoringVisibility(int typeMask)

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

Insets getMandatorySystemGestureInsets()

This method is deprecated. Use getInsets(int) with Type#mandatorySystemGestures() instead.

int getStableInsetBottom()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

int getStableInsetLeft()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

int getStableInsetRight()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

int getStableInsetTop()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

Insets getStableInsets()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

Insets getSystemGestureInsets()

This method is deprecated. Use getInsets(int) with Type#systemGestures() instead.

int getSystemWindowInsetBottom()

This method is deprecated. Use getInsets(int) with Type#systemBars() instead.

int getSystemWindowInsetLeft()

This method is deprecated. Use getInsets(int) with Type#systemBars() instead.

int getSystemWindowInsetRight()

This method is deprecated. Use getInsets(int) with Type#systemBars() instead.

int getSystemWindowInsetTop()

This method is deprecated. Use getInsets(int) with Type#systemBars() instead.

Insets getSystemWindowInsets()

This method is deprecated. Use getInsets(int) with Type#systemBars() instead.

Insets getTappableElementInsets()

This method is deprecated. Use getInsets(int) with Type#tappableElement() instead.

boolean hasInsets()

Returns true if this WindowInsets has any nonzero insets.

boolean hasStableInsets()

This method is deprecated. Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

boolean hasSystemWindowInsets()

This method is deprecated. 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 is deprecated. use Builder#Builder(WindowInsets) with Builder#setSystemWindowInsets(Insets) instead.

WindowInsets replaceSystemWindowInsets(Rect systemWindowInsets)

This method is deprecated. use Builder#Builder(WindowInsets) with Builder#setSystemWindowInsets(Insets) instead.

String toString()

Returns a string representation of the object.

Inherited methods

Fields

CONSUMED

public static final WindowInsets CONSUMED

A WindowInsets 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 OnApplyWindowInsetsListener#onApplyWindowInsets(View, WindowInsets) 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:

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 is deprecated.
Consuming of different parts individually of a WindowInsets instance is deprecated, since WindowInsets contains many different insets. Use 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 ()

This method is deprecated.
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.

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 ()

This method is deprecated.
Consuming of different parts individually of a WindowInsets instance is deprecated, since WindowInsets contains many different insets. Use CONSUMED instead to stop dispatching insets.

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 value x, x.equals(x) should return true.
  • It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
  • It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
  • It is consistent: for any non-null reference values x and y, multiple invocations of x.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.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Parameters
o Object: the reference object with which to compare.

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

getDisplayCutout

public DisplayCutout getDisplayCutout ()

Returns the display cutout if there is one.

Note: the display cutout will already be consumed during dispatch to View#onApplyWindowInsets, unless the window has requested a WindowManager.LayoutParams#layoutInDisplayCutoutMode other than WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER or WindowManager.LayoutParams#LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT.

Returns
DisplayCutout the display cutout or null if there is none

See also:

getInsets

public Insets getInsets (int typeMask)

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

Parameters
typeMask int: Bit mask of InsetsTypes to query the insets for. Value is either 0 or a combination of android.view.WindowInsets.Type.STATUS_BARS, android.view.WindowInsets.Type.NAVIGATION_BARS, android.view.WindowInsets.Type.CAPTION_BAR, android.view.WindowInsets.Type.IME, android.view.WindowInsets.Type.WINDOW_DECOR, android.view.WindowInsets.Type.SYSTEM_GESTURES, android.view.WindowInsets.Type.MANDATORY_SYSTEM_GESTURES, android.view.WindowInsets.Type.TAPPABLE_ELEMENT, and android.view.WindowInsets.Type.DISPLAY_CUTOUT

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 the typeMask bit mask of InsetsTypes, 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 InsetsTypes to query the insets for. Value is either 0 or a combination of android.view.WindowInsets.Type.STATUS_BARS, android.view.WindowInsets.Type.NAVIGATION_BARS, android.view.WindowInsets.Type.CAPTION_BAR, android.view.WindowInsets.Type.IME, android.view.WindowInsets.Type.WINDOW_DECOR, android.view.WindowInsets.Type.SYSTEM_GESTURES, android.view.WindowInsets.Type.MANDATORY_SYSTEM_GESTURES, android.view.WindowInsets.Type.TAPPABLE_ELEMENT, and android.view.WindowInsets.Type.DISPLAY_CUTOUT

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.

getMandatorySystemGestureInsets

public Insets getMandatorySystemGestureInsets ()

This method is deprecated.
Use getInsets(int) with Type#mandatorySystemGestures() instead.

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.

In contrast to regular system gestures, mandatory system gestures cannot be overriden by View#setSystemGestureExclusionRects.

Simple taps are guaranteed to reach the window even within the system gesture insets, as long as they are outside the system window insets.

When View#SYSTEM_UI_FLAG_LAYOUT_STABLE is requested, an inset will be returned even when the system gestures are inactive due to View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN or View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION.

This inset is consumed together with the system window insets by consumeSystemWindowInsets().

Returns
Insets This value cannot be null.

See also:

getStableInsetBottom

public int getStableInsetBottom ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() 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 ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

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.

Returns
int The left stable inset

getStableInsetRight

public int getStableInsetRight ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

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.

Returns
int The right stable inset

getStableInsetTop

public int getStableInsetTop ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

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.

Returns
int The top stable inset

getStableInsets

public Insets getStableInsets ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

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

getSystemGestureInsets

public Insets getSystemGestureInsets ()

This method is deprecated.
Use getInsets(int) with Type#systemGestures() instead.

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 View#setSystemGestureExclusionRects outside of the mandatory system gesture insets.

Note: the system will put a limit of 200dp on the vertical extent of the exclusions it takes into account. The limit does not apply while the navigation bar is View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY hidden, nor to the input method and Intent#CATEGORY_HOME.

Simple taps are guaranteed to reach the window even within the system gesture insets, as long as they are outside the system window insets.

When View#SYSTEM_UI_FLAG_LAYOUT_STABLE is requested, an inset will be returned even when the system gestures are inactive due to View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN or View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION.

This inset is consumed together with the system window insets by consumeSystemWindowInsets().

Returns
Insets This value cannot be null.

See also:

getSystemWindowInsetBottom

public int getSystemWindowInsetBottom ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() 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 ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() instead.

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 ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() instead.

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 ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() instead.

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 ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() instead.

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.

getTappableElementInsets

public Insets getTappableElementInsets ()

This method is deprecated.
Use getInsets(int) with Type#tappableElement() instead.

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

Note that generally, tappable elements should be aligned with the system window insets instead to avoid overlapping with the system bars.

When 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 View#SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN or View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION.

This inset is consumed together with the system window insets by consumeSystemWindowInsets().

Returns
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 ()

This method is deprecated.
Use getInsetsIgnoringVisibility(int) with Type#systemBars() instead.

Returns true if this WindowInsets has nonzero stable insets.

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

hasSystemWindowInsets

public boolean hasSystemWindowInsets ()

This method is deprecated.
Use getInsets(int) with Type#systemBars() instead.

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.

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(Object) 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(java.lang.Object) 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.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java™ programming language.)

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.

See also:

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.

See also:

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

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 Type.InsetsTypes to query visibility status. Value is either 0 or a combination of android.view.WindowInsets.Type.STATUS_BARS, android.view.WindowInsets.Type.NAVIGATION_BARS, android.view.WindowInsets.Type.CAPTION_BAR, android.view.WindowInsets.Type.IME, android.view.WindowInsets.Type.WINDOW_DECOR, android.view.WindowInsets.Type.SYSTEM_GESTURES, android.view.WindowInsets.Type.MANDATORY_SYSTEM_GESTURES, android.view.WindowInsets.Type.TAPPABLE_ELEMENT, and android.view.WindowInsets.Type.DISPLAY_CUTOUT

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 is deprecated.
use Builder#Builder(WindowInsets) with Builder#setSystemWindowInsets(Insets) 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 and later. Prior to 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)

This method is deprecated.
use Builder#Builder(WindowInsets) with Builder#setSystemWindowInsets(Insets) 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 and later. Prior to Q, the new values were applied regardless of whether they were consumed, and this method returns invalid non-zero consumed insets.

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. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.