WindowInsetsControllerCompat

Added in 1.5.0

public final class 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 types

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

Constants

static final int

The default option for setSystemBarsBehavior: Window would like to remain interactive when hiding navigation bars by calling hide or setInsetsAndAlpha.

static final int

This field is deprecated.

Use BEHAVIOR_DEFAULT instead.

static final int

This field is deprecated.

This is not supported on Android S and later.

static final int

Option for setSystemBarsBehavior: Window would like to remain interactive when hiding navigation bars by calling hide or setInsetsAndAlpha.

Public constructors

Public methods

void

Adds a WindowInsetsController.OnControllableInsetsChangedListener to the window insets controller.

void
controlWindowInsetsAnimation(
    int types,
    long durationMillis,
    @Nullable Interpolator interpolator,
    @Nullable CancellationSignal cancellationSignal,
    @NonNull 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 setInsetsAndAlpha in the controller provided by the given listener.

int

Retrieves the requested behavior of system bars.

void
hide(int types)

Makes a set of windows causing insets disappear.

boolean

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

boolean

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

void

Removes a WindowInsetsController.OnControllableInsetsChangedListener from the window insets controller.

void

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

void

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 @NonNull WindowInsetsControllerCompat

This method is deprecated.

Use getInsetsController instead

Constants

BEHAVIOR_DEFAULT

Added in 1.10.0
public static final int BEHAVIOR_DEFAULT = 1

The default option for setSystemBarsBehavior: Window would like to remain interactive when hiding navigation bars by calling hide or setInsetsAndAlpha.

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.

BEHAVIOR_SHOW_BARS_BY_SWIPE

Added in 1.5.0
Deprecated in 1.10.0
public static final int BEHAVIOR_SHOW_BARS_BY_SWIPE = 1

Option for setSystemBarsBehavior: Window would like to remain interactive when hiding navigation bars by calling hide or setInsetsAndAlpha.

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.

BEHAVIOR_SHOW_BARS_BY_TOUCH

Added in 1.5.0
Deprecated in 1.10.0
public static final int BEHAVIOR_SHOW_BARS_BY_TOUCH = 0

Option for setSystemBarsBehavior. System bars will be forcibly shown on any user interaction on the corresponding display if navigation bars are hidden by hide or setInsetsAndAlpha.

BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

Added in 1.5.0
public static final int BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE = 2

Option for setSystemBarsBehavior: Window would like to remain interactive when hiding navigation bars by calling hide or setInsetsAndAlpha.

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.

Public constructors

WindowInsetsControllerCompat

Added in 1.5.0
public WindowInsetsControllerCompat(@NonNull Window window, @NonNull View view)

Public methods

controlWindowInsetsAnimation

Added in 1.5.0
public void controlWindowInsetsAnimation(
    int types,
    long durationMillis,
    @Nullable Interpolator interpolator,
    @Nullable CancellationSignal cancellationSignal,
    @NonNull 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 setInsetsAndAlpha 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
int types

The WindowInsetsCompat.Types the application has requested to control.

long durationMillis

Duration of animation in MILLISECONDS, or -1 if the animation doesn't have a predetermined duration. This value will be passed to getDurationMillis

@Nullable 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 getInterpolator and used to calculate getInterpolatedFraction.

@Nullable 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.

@NonNull WindowInsetsAnimationControlListenerCompat listener

The WindowInsetsAnimationControlListener that gets called when the windows are ready to be controlled, among other callbacks.

getSystemBarsBehavior

Added in 1.5.0
public int getSystemBarsBehavior()

Retrieves the requested behavior of system bars.

Returns
int

the system bar behavior controlled by this window.

hide

Added in 1.5.0
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 onApplyWindowInsets and checking visibility with isVisible.

Parameters
int types

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

isAppearanceLightNavigationBars

Added in 1.5.0
public boolean isAppearanceLightNavigationBars()

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

This method always returns false on API <26.

If this value is being set in the theme (via windowLightNavigationBar), then the correct value will only be returned once attached to the window.

Once this method is called, modifying `systemUiVisibility` directly to change the appearance is undefined behavior.

Returns
boolean

true if the foreground is light

isAppearanceLightStatusBars

Added in 1.5.0
public boolean isAppearanceLightStatusBars()

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

This method always returns false on API <23.

If this value is being set in the theme (via windowLightStatusBar), then the correct value will only be returned once attached to the window.

Once this method is called, modifying `systemUiVisibility` directly to change the appearance is undefined behavior.

Returns
boolean

true if the foreground is light

setAppearanceLightNavigationBars

Added in 1.5.0
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.

Once this method is called, modifying `systemUiVisibility` directly to change the appearance is undefined behavior.

setAppearanceLightStatusBars

Added in 1.5.0
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.

Once this method is called, modifying `systemUiVisibility` directly to change the appearance is undefined behavior.

setSystemBarsBehavior

Added in 1.5.0
public void setSystemBarsBehavior(int behavior)

Controls the behavior of system bars.

Parameters
int behavior

Determines how the bars behave when being hidden by the application.

show

Added in 1.5.0
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 onApplyWindowInsets and checking visibility with isVisible.

Parameters
int types

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

toWindowInsetsControllerCompat

Added in 1.5.0
Deprecated in 1.8.0
@RequiresApi(value = 30)
public static @NonNull WindowInsetsControllerCompat toWindowInsetsControllerCompat(
    @NonNull WindowInsetsController insetsController
)

Wrap a WindowInsetsController into a WindowInsetsControllerCompat for compatibility purpose.

Parameters
@NonNull WindowInsetsController insetsController

The WindowInsetsController to wrap.