Android 12 Developer Preview is here! Try it out, and give us your feedback!

WindowInsetsControllerCompat

public final class WindowInsetsControllerCompat
extends Object

java.lang.Object
   ↳ androidx.core.view.WindowInsetsControllerCompat

Provide simple controls of windows that generate insets. For SDKs >= 30, this class is a simple wrapper around WindowInsetsController. For lower SDKs, this class aims to behave as close as possible to the original implementation.

Summary

Nested classes

interface WindowInsetsControllerCompat.OnControllableInsetsChangedListener

Listener to be notified when the set of controllable WindowInsetsCompat.Type controlled by a WindowInsetsController changes. 

Constants

int BEHAVIOR_SHOW_BARS_BY_SWIPE

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

int BEHAVIOR_SHOW_BARS_BY_TOUCH

The default option for setSystemBarsBehavior(int).

int BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

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

Public constructors

WindowInsetsControllerCompat(Window window, View view)

Public methods

void addOnControllableInsetsChangedListener(WindowInsetsControllerCompat.OnControllableInsetsChangedListener listener)

Adds a WindowInsetsController.OnControllableInsetsChangedListener to the window insets controller.

void controlWindowInsetsAnimation(int types, long durationMillis, Interpolator interpolator, CancellationSignal cancellationSignal, WindowInsetsAnimationControlListenerCompat listener)

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 using WindowInsetsAnimationControllerCompat.setInsetsAndAlpha(Insets, float, float) in the controller provided by the given listener.

int getSystemBarsBehavior()

Retrieves the requested behavior of system bars.

void hide(int types)

Makes a set of windows causing insets disappear.

boolean isAppearanceLightNavigationBars()

Checks if the foreground of the navigation bar is set to light.

boolean isAppearanceLightStatusBars()

Checks if the foreground of the status bar is set to light.

void removeOnControllableInsetsChangedListener(WindowInsetsControllerCompat.OnControllableInsetsChangedListener listener)

Removes a WindowInsetsController.OnControllableInsetsChangedListener from the window insets controller.

void setAppearanceLightNavigationBars(boolean isLight)

If true, changes the foreground color of the navigation bars to light so that the items on the bar can be read clearly.

void setAppearanceLightStatusBars(boolean isLight)

If true, changes the foreground color of the status bars to light so that the items on the bar can be read clearly.

void setSystemBarsBehavior(int behavior)

Controls the behavior of system bars.

void show(int types)

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

static WindowInsetsControllerCompat toWindowInsetsControllerCompat(WindowInsetsController insetsController)

Wrap a WindowInsetsController into a WindowInsetsControllerCompat for compatibility purpose.

Inherited methods

Constants

BEHAVIOR_SHOW_BARS_BY_SWIPE

public static final int BEHAVIOR_SHOW_BARS_BY_SWIPE

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationControllerCompat.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.

Constant Value: 1 (0x00000001)

BEHAVIOR_SHOW_BARS_BY_TOUCH

public static final int BEHAVIOR_SHOW_BARS_BY_TOUCH

The default 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 WindowInsetsAnimationControllerCompat.setInsetsAndAlpha(Insets, float, float).

Constant Value: 0 (0x00000000)

BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

public static final int BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

Option for setSystemBarsBehavior(int): Window would like to remain interactive when hiding navigation bars by calling hide(int) or WindowInsetsAnimationControllerCompat.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.

Constant Value: 2 (0x00000002)

Public constructors

WindowInsetsControllerCompat

public WindowInsetsControllerCompat (Window window, 
                View view)

Parameters
window Window

view View

Public methods

addOnControllableInsetsChangedListener

public void addOnControllableInsetsChangedListener (WindowInsetsControllerCompat.OnControllableInsetsChangedListener listener)

Adds a WindowInsetsController.OnControllableInsetsChangedListener to the window insets controller.

Parameters
listener WindowInsetsControllerCompat.OnControllableInsetsChangedListener: The listener to add.

controlWindowInsetsAnimation

public void controlWindowInsetsAnimation (int types, 
                long durationMillis, 
                Interpolator interpolator, 
                CancellationSignal cancellationSignal, 
                WindowInsetsAnimationControlListenerCompat listener)

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 using WindowInsetsAnimationControllerCompat.setInsetsAndAlpha(Insets, float, float) in the controller provided by the given listener.

This method only works on API >= 30 since there is no way to control the window in the system on prior APIs.

Parameters
types int: The WindowInsetsCompat.Types the application has requested to control.
durationMillis long: Duration of animation in TimeUnit.MILLISECONDS, or -1 if the animation doesn't have a predetermined duration. This value will be passed to WindowInsetsAnimationCompat.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 WindowInsetsAnimationCompat.getInterpolator() and used to calculate WindowInsetsAnimationCompat.getInterpolatedFraction().
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.
listener WindowInsetsAnimationControlListenerCompat: The WindowInsetsAnimationControlListener that gets called when the windows are ready to be controlled, among other callbacks.

getSystemBarsBehavior

public int getSystemBarsBehavior ()

Retrieves the requested behavior of system bars.

Returns
int the system bar behavior controlled by this window.

hide

public void hide (int types)

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(WindowInsets) and checking visibility with WindowInsets.isVisible(int).

Parameters
types int: A bitmask of WindowInsetsCompat.Type specifying what windows the app would like to make disappear.

isAppearanceLightNavigationBars

public boolean isAppearanceLightNavigationBars ()

Checks if the foreground of the navigation bar is set to light.

This method always returns false on API < 26.

Returns
boolean true if the foreground is light

isAppearanceLightStatusBars

public boolean isAppearanceLightStatusBars ()

Checks if the foreground of the status bar is set to light.

This method always returns false on API < 23.

Returns
boolean true if the foreground is light

removeOnControllableInsetsChangedListener

public void removeOnControllableInsetsChangedListener (WindowInsetsControllerCompat.OnControllableInsetsChangedListener listener)

Removes a WindowInsetsController.OnControllableInsetsChangedListener from the window insets controller.

Parameters
listener WindowInsetsControllerCompat.OnControllableInsetsChangedListener: The listener to remove.

setAppearanceLightNavigationBars

public void setAppearanceLightNavigationBars (boolean isLight)

If true, changes the foreground color of the navigation bars to light so that the items on the bar can be read clearly. If false, reverts to the default appearance.

This method has no effect on API < 26.

Parameters
isLight boolean

setAppearanceLightStatusBars

public void setAppearanceLightStatusBars (boolean isLight)

If true, changes the foreground color of the status bars to light so that the items on the bar can be read clearly. If false, reverts to the default appearance.

This method has no effect on API < 23.

Parameters
isLight boolean

setSystemBarsBehavior

public void setSystemBarsBehavior (int behavior)

Controls the behavior of system bars.

Parameters
behavior int: Determines how the bars behave when being hidden by the application.

show

public void show (int types)

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(WindowInsets) and checking visibility with WindowInsets.isVisible(int).

Parameters
types int: A bitmask of WindowInsetsCompat.Type specifying what windows the app would like to make appear on screen.

toWindowInsetsControllerCompat

public static WindowInsetsControllerCompat toWindowInsetsControllerCompat (WindowInsetsController insetsController)

Wrap a WindowInsetsController into a WindowInsetsControllerCompat for compatibility purpose.

Parameters
insetsController WindowInsetsController: The WindowInsetsController to wrap.
Returns
WindowInsetsControllerCompat The provided WindowInsetsControllerCompat wrapped into a WindowInsetsControllerCompat