Added in API level 30

WindowInsetsController

interface WindowInsetsController
android.view.WindowInsetsController

Interface to control windows that generate insets.

Summary

Nested classes
abstract

Listener to be notified when the set of controllable WindowInsets.Type controlled by a WindowInsetsController changes.
Constants
static Int

When WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND is set, changes the foreground color of the caption bars so that the items on the bar can be read clearly on light backgrounds.
static Int

Changes the foreground color for light navigation bars so that the items on the bar can be read clearly.
static Int

Changes the foreground color for light status bars so that the items on the bar can be read clearly.
static Int

Makes the caption bar transparent.
static Int

The default option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).
static Int

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).
static Int

Option for setSystemBarsBehavior(int).
static Int

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).
Public methods
abstract Unit

Adds a OnControllableInsetsChangedListener to the window insets controller.
abstract Unit
controlWindowInsetsAnimation(types: Int, durationMillis: Long, interpolator: Interpolator?, cancellationSignal: CancellationSignal?, listener: WindowInsetsAnimationControlListener)

Lets the application control window inset animations in a frame-by-frame manner by modifying the position of the windows in the system causing insets directly.
abstract Int

Retrieves the requested appearance of system bars.
abstract Int

Retrieves the requested behavior of system bars.
abstract Unit
hide(types: Int)

Makes a set of windows causing insets disappear.
abstract Unit

Removes a OnControllableInsetsChangedListener from the window insets controller.
abstract Unit
setSystemBarsAppearance(appearance: Int, mask: Int)

Controls the appearance of system bars.
abstract Unit

Controls the behavior of system bars.
abstract Unit
show(types: Int)

Makes a set of windows that cause insets appear on screen.

Constants

APPEARANCE_LIGHT_CAPTION_BARS

Added in API level 35
static val APPEARANCE_LIGHT_CAPTION_BARS: Int

When WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND is set, changes the foreground color of the caption bars so that the items on the bar can be read clearly on light backgrounds.

Value: 256

APPEARANCE_LIGHT_NAVIGATION_BARS

Added in API level 30
static val APPEARANCE_LIGHT_NAVIGATION_BARS: Int

Changes the foreground color for light navigation bars so that the items on the bar can be read clearly.

Value: 16

APPEARANCE_LIGHT_STATUS_BARS

Added in API level 30
static val APPEARANCE_LIGHT_STATUS_BARS: Int

Changes the foreground color for light status bars so that the items on the bar can be read clearly.

Value: 8

APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND

Added in API level 35
static val APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND: Int

Makes the caption bar transparent.

Value: 128

BEHAVIOR_DEFAULT

Added in API level 31
static val BEHAVIOR_DEFAULT: Int

The default option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).

When system bars are hidden in this mode, they can be revealed with system gestures, such as swiping from the edge of the screen where the bar is hidden from.

When the gesture navigation is enabled, the system gestures can be triggered regardless the visibility of system bars.

Value: 1

BEHAVIOR_SHOW_BARS_BY_SWIPE

Added in API level 30
Deprecated in API level 31
static val BEHAVIOR_SHOW_BARS_BY_SWIPE: Int

Deprecated: Use BEHAVIOR_DEFAULT instead.

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).

When system bars are hidden in this mode, they can be revealed with system gestures, such as swiping from the edge of the screen where the bar is hidden from.

Value: 1

BEHAVIOR_SHOW_BARS_BY_TOUCH

Added in API level 30
Deprecated in API level 31
static val BEHAVIOR_SHOW_BARS_BY_TOUCH: Int

Deprecated: This is not supported on Android Build.VERSION_CODES#S and later. Use BEHAVIOR_DEFAULT or BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE instead.

Option for setSystemBarsBehavior(int). System bars will be forcibly shown on any user interaction on the corresponding display if navigation bars are hidden by hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).

Value: 0

BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

Added in API level 30
static val BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE: Int

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float).

When system bars are hidden in this mode, they can be revealed temporarily with system gestures, such as swiping from the edge of the screen where the bar is hidden from. These transient system bars will overlay app’s content, may have some degree of transparency, and will automatically hide after a short timeout.

Value: 2

Public methods

addOnControllableInsetsChangedListener

Added in API level 30
abstract fun addOnControllableInsetsChangedListener(listener: WindowInsetsController.OnControllableInsetsChangedListener): Unit

Adds a OnControllableInsetsChangedListener to the window insets controller.

Parameters
listener WindowInsetsController.OnControllableInsetsChangedListener: The listener to add. This value cannot be null.

controlWindowInsetsAnimation

Added in API level 30
abstract fun controlWindowInsetsAnimation(
    types: Int, 
    durationMillis: Long, 
    interpolator: Interpolator?, 
    cancellationSignal: CancellationSignal?, 
    listener: WindowInsetsAnimationControlListener
): Unit

Lets the application control window inset animations in a frame-by-frame manner by modifying the position of the windows in the system causing insets directly.

Parameters
types Int: The WindowInsets.Types the application has requested to control. 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, android.view.WindowInsets.Type.DISPLAY_CUTOUT, and android.view.WindowInsets.Type.SYSTEM_OVERLAYS
durationMillis Long: Duration of animation in java.util.concurrent.TimeUnit#MILLISECONDS, or -1 if the animation doesn't have a predetermined duration. This value will be passed to WindowInsetsAnimation#getDurationMillis()
interpolator Interpolator?: The interpolator used for this animation, or null if this animation doesn't follow an interpolation curve. This value will be passed to WindowInsetsAnimation#getInterpolator() and used to calculate WindowInsetsAnimation#getInterpolatedFraction().
listener WindowInsetsAnimationControlListener: The WindowInsetsAnimationControlListener that gets called when the windows are ready to be controlled, among other callbacks. This value cannot be null.
cancellationSignal CancellationSignal?: A cancellation signal that the caller can use to cancel the request to obtain control, or once they have control, to cancel the control. This value may be null.

getSystemBarsAppearance

Added in API level 30
abstract fun getSystemBarsAppearance(): Int

Retrieves the requested appearance of system bars.

Return
Int The requested bitmask of system bar appearance controlled by this window. Value is either 0 or a combination of android.view.WindowInsetsController.APPEARANCE_OPAQUE_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_OPAQUE_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_LOW_PROFILE_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_STATUS_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_NAVIGATION_BARS, android.view.WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND, android.view.WindowInsetsController#APPEARANCE_LIGHT_CAPTION_BARS, and android.view.WindowInsetsController.APPEARANCE_FORCE_LIGHT_NAVIGATION_BARS

getSystemBarsBehavior

Added in API level 30
abstract fun getSystemBarsBehavior(): Int

Retrieves the requested behavior of system bars.

Return
Int the system bar behavior controlled by this window. Value is android.view.WindowInsetsController#BEHAVIOR_DEFAULT, or android.view.WindowInsetsController#BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

hide

Added in API level 30
abstract fun hide(types: Int): Unit

Makes a set of windows causing insets disappear.

Note that if the window currently doesn't have control over a certain type, it will apply the change as soon as the window gains control. The app can listen to the event by observing View#onApplyWindowInsets and checking visibility with WindowInsets#isVisible.

Parameters
types Int: A bitmask of WindowInsets.Type specifying what windows the app would like to make disappear. 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, android.view.WindowInsets.Type.DISPLAY_CUTOUT, and android.view.WindowInsets.Type.SYSTEM_OVERLAYS

removeOnControllableInsetsChangedListener

Added in API level 30
abstract fun removeOnControllableInsetsChangedListener(listener: WindowInsetsController.OnControllableInsetsChangedListener): Unit

Removes a OnControllableInsetsChangedListener from the window insets controller.

Parameters
listener WindowInsetsController.OnControllableInsetsChangedListener: The listener to remove. This value cannot be null.

setSystemBarsAppearance

Added in API level 30
abstract fun setSystemBarsAppearance(
    appearance: Int, 
    mask: Int
): Unit

Controls the appearance of system bars.

For example, the following statement adds APPEARANCE_LIGHT_STATUS_BARS: 

setSystemBarsAppearance(APPEARANCE_LIGHT_STATUS_BARS, APPEARANCE_LIGHT_STATUS_BARS)
And the following statement clears it: 
setSystemBarsAppearance(0, APPEARANCE_LIGHT_STATUS_BARS)
Parameters
appearance Int: Bitmask of appearance flags. Value is either 0 or a combination of android.view.WindowInsetsController.APPEARANCE_OPAQUE_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_OPAQUE_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_LOW_PROFILE_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_STATUS_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_NAVIGATION_BARS, android.view.WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND, android.view.WindowInsetsController#APPEARANCE_LIGHT_CAPTION_BARS, and android.view.WindowInsetsController.APPEARANCE_FORCE_LIGHT_NAVIGATION_BARS
mask Int: Specifies which flags of appearance should be changed. Value is either 0 or a combination of android.view.WindowInsetsController.APPEARANCE_OPAQUE_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_OPAQUE_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_LOW_PROFILE_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_STATUS_BARS, android.view.WindowInsetsController#APPEARANCE_LIGHT_NAVIGATION_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_STATUS_BARS, android.view.WindowInsetsController.APPEARANCE_SEMI_TRANSPARENT_NAVIGATION_BARS, android.view.WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND, android.view.WindowInsetsController#APPEARANCE_LIGHT_CAPTION_BARS, and android.view.WindowInsetsController.APPEARANCE_FORCE_LIGHT_NAVIGATION_BARS

setSystemBarsBehavior

Added in API level 30
abstract fun setSystemBarsBehavior(behavior: Int): Unit

Controls the behavior of system bars.

Parameters
behavior Int: Determines how the bars behave when being hidden by the application. Value is android.view.WindowInsetsController#BEHAVIOR_DEFAULT, or android.view.WindowInsetsController#BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

show

Added in API level 30
abstract fun show(types: Int): Unit

Makes a set of windows that cause insets appear on screen.

Note that if the window currently doesn't have control over a certain type, it will apply the change as soon as the window gains control. The app can listen to the event by observing View#onApplyWindowInsets and checking visibility with WindowInsets#isVisible.

Parameters
types Int: A bitmask of WindowInsets.Type specifying what windows the app would like to make appear on screen. 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, android.view.WindowInsets.Type.DISPLAY_CUTOUT, and android.view.WindowInsets.Type.SYSTEM_OVERLAYS