WindowInsetsCompat
public
class
WindowInsetsCompat
extends Object
java.lang.Object | |
↳ | androidx.core.view.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 classes | |
---|---|
class |
WindowInsetsCompat.Builder
Builder for |
class |
WindowInsetsCompat.Type
Class that defines different types of sources causing window insets. |
Fields | |
---|---|
public
static
final
WindowInsetsCompat |
CONSUMED
A |
Public constructors | |
---|---|
WindowInsetsCompat(WindowInsetsCompat src)
Constructs a new WindowInsetsCompat, copying all values from a source WindowInsetsCompat. |
Public methods | |
---|---|
WindowInsetsCompat
|
consumeDisplayCutout()
This method is deprecated.
Consuming of different parts individually of a |
WindowInsetsCompat
|
consumeStableInsets()
This method is deprecated.
Consuming of different parts individually of a |
WindowInsetsCompat
|
consumeSystemWindowInsets()
This method is deprecated.
Consuming of different parts individually of a |
boolean
|
equals(Object o)
|
DisplayCutoutCompat
|
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
|
Insets
|
getInsetsIgnoringVisibility(int typeMask)
Returns the insets a specific set of windows can cause, denoted by the
|
Insets
|
getMandatorySystemGestureInsets()
This method is deprecated.
Use |
int
|
getStableInsetBottom()
This method is deprecated.
Use |
int
|
getStableInsetLeft()
This method is deprecated.
Use |
int
|
getStableInsetRight()
This method is deprecated.
Use |
int
|
getStableInsetTop()
This method is deprecated.
Use |
Insets
|
getStableInsets()
This method is deprecated.
Use |
Insets
|
getSystemGestureInsets()
This method is deprecated.
Use |
int
|
getSystemWindowInsetBottom()
This method is deprecated.
Use |
int
|
getSystemWindowInsetLeft()
This method is deprecated.
Use |
int
|
getSystemWindowInsetRight()
This method is deprecated.
Use |
int
|
getSystemWindowInsetTop()
This method is deprecated.
Use |
Insets
|
getSystemWindowInsets()
This method is deprecated.
Use |
Insets
|
getTappableElementInsets()
This method is deprecated.
Use |
boolean
|
hasInsets()
Returns true if this WindowInsets has any non-zero insets. |
boolean
|
hasStableInsets()
This method is deprecated.
Use |
boolean
|
hasSystemWindowInsets()
This method is deprecated.
Use |
int
|
hashCode()
|
WindowInsetsCompat
|
inset(int left, int top, int right, int bottom)
Returns a copy of this instance inset in the given directions. |
WindowInsetsCompat
|
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. |
WindowInsetsCompat
|
replaceSystemWindowInsets(int left, int top, int right, int bottom)
This method is deprecated.
use |
WindowInsetsCompat
|
replaceSystemWindowInsets(Rect systemWindowInsets)
This method is deprecated.
use |
WindowInsets
|
toWindowInsets()
Return the source |
static
WindowInsetsCompat
|
toWindowInsetsCompat(WindowInsets insets)
Wrap an instance of |
static
WindowInsetsCompat
|
toWindowInsetsCompat(WindowInsets insets, View view)
Wrap an instance of |
Inherited methods | |
---|---|
Fields
CONSUMED
public static final 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
OnApplyWindowInsetsListener.onApplyWindowInsets(View, WindowInsetsCompat)
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
WindowInsetsCompat
public WindowInsetsCompat (WindowInsetsCompat src)
Constructs a new WindowInsetsCompat, copying all values from a source WindowInsetsCompat.
Parameters | |
---|---|
src |
WindowInsetsCompat : source from which values are copied
|
Public methods
consumeDisplayCutout
public WindowInsetsCompat consumeDisplayCutout ()
This method is deprecated.
Consuming of different parts individually of a WindowInsetsCompat
instance is deprecated, since WindowInsetsCompat
contains many different insets. Use
CONSUMED
instead to stop dispatching insets.
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 | |
---|---|
WindowInsetsCompat |
A modified copy of this WindowInsets |
consumeStableInsets
public WindowInsetsCompat consumeStableInsets ()
This method is deprecated.
Consuming of different parts individually of a WindowInsetsCompat
instance is deprecated, since WindowInsetsCompat
contains many different insets. Use
CONSUMED
instead to stop dispatching insets.
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 | |
---|---|
WindowInsetsCompat |
A modified copy of this WindowInsetsCompat |
consumeSystemWindowInsets
public WindowInsetsCompat consumeSystemWindowInsets ()
This method is deprecated.
Consuming of different parts individually of a WindowInsetsCompat
instance is deprecated, since WindowInsetsCompat
contains many different insets. Use
CONSUMED
instead to stop dispatching insets.
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 | |
---|---|
WindowInsetsCompat |
A modified copy of this WindowInsets |
equals
public boolean equals (Object o)
Parameters | |
---|---|
o |
Object |
Returns | |
---|---|
boolean |
getDisplayCutout
public 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 | |
---|---|
DisplayCutoutCompat |
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 WindowInsetsCompat.Type
s.
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 | |
---|---|
typeMask |
int : Bit mask of WindowInsetsCompat.Type s to query the insets for. |
Returns | |
---|---|
Insets |
The insets. |
getInsetsIgnoringVisibility
public Insets getInsetsIgnoringVisibility (int typeMask)
Returns the insets a specific set of windows can cause, denoted by the
typeMask
bit mask of WindowInsetsCompat.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 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.
IME
type, which currently only works when running on devices with SDK level 23
and above.
Parameters | |
---|---|
typeMask |
int : Bit mask of WindowInsetsCompat.Type s to query the insets for. |
Returns | |
---|---|
Insets |
The insets. |
Throws | |
---|---|
IllegalArgumentException |
If the caller tries to query WindowInsetsCompat.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 WindowInsetsCompat.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.
Returns | |
---|---|
Insets |
getStableInsetBottom
public int getStableInsetBottom ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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.
When running on platforms with API 20 and below, this method always returns 0
.
Returns | |
---|---|
int |
The bottom stable inset |
getStableInsetLeft
public int getStableInsetLeft ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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.
When running on platforms with API 20 and below, this method always returns 0
.
Returns | |
---|---|
int |
The left stable inset |
getStableInsetRight
public int getStableInsetRight ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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.
When running on platforms with API 20 and below, this method always returns 0
.
Returns | |
---|---|
int |
The right stable inset |
getStableInsetTop
public int getStableInsetTop ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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.
When running on platforms with API 20 and below, this method always returns 0
.
Returns | |
---|---|
int |
getStableInsets
public Insets getStableInsets ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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 |
getSystemGestureInsets
public Insets getSystemGestureInsets ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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(List
outside of the
mandatory system gesture insets
.
Returns | |
---|---|
Insets |
See also:
getSystemWindowInsetBottom
public int getSystemWindowInsetBottom ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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.
When running on platforms with API 19 and below, this method always returns 0
.
Returns | |
---|---|
int |
The bottom system window inset |
getSystemWindowInsetLeft
public int getSystemWindowInsetLeft ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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.
When running on platforms with API 19 and below, this method always returns 0
.
Returns | |
---|---|
int |
The left system window inset |
getSystemWindowInsetRight
public int getSystemWindowInsetRight ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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.
When running on platforms with API 19 and below, this method always returns 0
.
Returns | |
---|---|
int |
The right system window inset |
getSystemWindowInsetTop
public int getSystemWindowInsetTop ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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.
When running on platforms with API 19 and below, this method always returns 0
.
Returns | |
---|---|
int |
The top system window inset |
getSystemWindowInsets
public Insets getSystemWindowInsets ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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 |
getTappableElementInsets
public Insets getTappableElementInsets ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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).
Returns | |
---|---|
Insets |
See also:
hasInsets
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 | |
---|---|
boolean |
true if any inset values are nonzero |
hasStableInsets
public boolean hasStableInsets ()
This method is deprecated.
Use getInsetsIgnoringVisibility(int)
with WindowInsetsCompat.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.
When running on platforms with API 20 and below, this method always returns false
.
Returns | |
---|---|
boolean |
true if any of the stable inset values are nonzero |
hasSystemWindowInsets
public boolean hasSystemWindowInsets ()
This method is deprecated.
Use getInsets(int)
with WindowInsetsCompat.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.
When running on platforms with API 19 and below, this method always returns false
.
Returns | |
---|---|
boolean |
true if any of the system window inset values are nonzero |
hashCode
public int hashCode ()
Returns | |
---|---|
int |
inset
public WindowInsetsCompat 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. |
top |
int : the amount of insets to remove from the top. Must be non-negative. |
right |
int : the amount of insets to remove from the right. Must be non-negative. |
bottom |
int : the amount of insets to remove from the bottom. Must be non-negative. |
Returns | |
---|---|
WindowInsetsCompat |
the inset insets |
inset
public WindowInsetsCompat 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. |
Returns | |
---|---|
WindowInsetsCompat |
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.
When running on platforms with API 19 and below, this method always returns false
.
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.
When running on devices with API Level 29 and before, the returned value is 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 | |
---|---|
typeMask |
int : Bit mask of WindowInsetsCompat.Type s to query visibility status. |
Returns | |
---|---|
boolean |
true if and only if all windows included in typeMask are currently
visible on screen.
|
replaceSystemWindowInsets
public WindowInsetsCompat replaceSystemWindowInsets (int left, int top, int right, int bottom)
This method is deprecated.
use WindowInsetsCompat.Builder
with
WindowInsetsCompat.Builder.setSystemWindowInsets(Insets)
instead.
Returns a copy of this WindowInsets with selected system window insets replaced with new values.
When running on platforms with API 19 and below, this method always returns null
.
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 | |
---|---|
WindowInsetsCompat |
A modified copy of this WindowInsets |
replaceSystemWindowInsets
public WindowInsetsCompat replaceSystemWindowInsets (Rect systemWindowInsets)
This method is deprecated.
use WindowInsetsCompat.Builder
with
WindowInsetsCompat.Builder.setSystemWindowInsets(Insets)
instead.
Returns a copy of this WindowInsets with selected system window insets replaced with new values.
When running on platforms with API 19 and below, this method always returns null
.
Parameters | |
---|---|
systemWindowInsets |
Rect : New system window insets. Each field is the inset in pixels
for that edge |
Returns | |
---|---|
WindowInsetsCompat |
A modified copy of this WindowInsets |
toWindowInsets
public WindowInsets toWindowInsets ()
Return the source WindowInsets
instance used in this WindowInsetsCompat
.
Returns | |
---|---|
WindowInsets |
the wrapped WindowInsets instance |
toWindowInsetsCompat
public static WindowInsetsCompat toWindowInsetsCompat (WindowInsets insets)
Wrap an instance of WindowInsets
into a WindowInsetsCompat
.
This version of the function does not allow the resulting WindowInsetsCompat
to be
aware of the root window insets and root view, meaning that the returned values for many of
the different inset WindowInsetsCompat.Type
s will be incorrect.
Prefer using toWindowInsetsCompat(WindowInsets, View)
instead.
Parameters | |
---|---|
insets |
WindowInsets : source insets to wrap |
Returns | |
---|---|
WindowInsetsCompat |
the wrapped instance |
toWindowInsetsCompat
public static WindowInsetsCompat toWindowInsetsCompat (WindowInsets insets, View view)
Wrap an instance of WindowInsets
into a WindowInsetsCompat
.
This version of the function allows the resulting WindowInsetsCompat
to be
aware of the root window insets and root view through the view
parameter. This is
required for many of the different inset WindowInsetsCompat.Type
s to return correct values when used
on devices running Android 10 and before.
Parameters | |
---|---|
insets |
WindowInsets : source insets to wrap |
view |
View : view to use as an entry point for obtaining root window information. This
view needs be attached to the window, otherwise it will be ignored. |
Returns | |
---|---|
WindowInsetsCompat |
the wrapped instance |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.