WindowAreaController

@ExperimentalWindowApi
abstract class WindowAreaController

Known direct subclasses
WindowAreaControllerCallbackAdapter

An adapter for WindowAreaController to provide callback APIs.

An interface to provide the information and behavior around moving windows between displays or display areas on a device.

Summary

Public companion functions
WindowAreaController

Provides an instance of WindowAreaController.

Public functions
abstract Unit
presentContentOnWindowArea(
    token: Binder,
    activity: Activity,
    executor: Executor,
    windowAreaPresentationSessionCallback: WindowAreaPresentationSessionCallback
)

Starts a presentation session on the WindowAreaInfo identified by the token and sends updates through the WindowAreaPresentationSessionCallback.
abstract Unit
transferActivityToWindowArea(
    token: Binder,
    activity: Activity,
    executor: Executor,
    windowAreaSessionCallback: WindowAreaSessionCallback
)

Starts a transfer session where the calling Activity is moved to the window area identified by the token.

Public properties
abstract Flow<List<WindowAreaInfo>>

Flow of the list of current WindowAreaInfos that are currently available to be interacted with.

Public companion functions

getOrCreate

Added in 1.2.0
fun getOrCreate(): WindowAreaController

Provides an instance of WindowAreaController.

Public functions

presentContentOnWindowArea

Added in 1.2.0
abstract fun presentContentOnWindowArea(
    token: Binder,
    activity: Activity,
    executor: Executor,
    windowAreaPresentationSessionCallback: WindowAreaPresentationSessionCallback
): Unit

Starts a presentation session on the WindowAreaInfo identified by the token and sends updates through the WindowAreaPresentationSessionCallback.

If a presentation session is attempted to be started without it being available, WindowAreaPresentationSessionCallback.onSessionEnded will be called immediately with an IllegalStateException.

Only the top visible application can request to start a presentation session.

The presentation session will stay active until the presentation provided through WindowAreaPresentationSessionCallback.onSessionStarted is closed. The WindowAreaInfo.Type may provide different triggers to close the session such as if the calling application is no longer in the foreground, or there is a device state change that makes the window area unavailable to be presented on. One example scenario is if a TYPE_REAR_FACING window area is being presented to on a foldable device that is open and has 2 screens. If the device is closed and the internal display is turned off, the session would be ended and WindowAreaPresentationSessionCallback.onSessionEnded is called to notify that the session has been ended. The session may end prematurely if the device gets to a critical thermal level, or if power saver mode is enabled.

Parameters
token: Binder

Binder token to identify which WindowAreaInfo is to be presented on
activity: Activity

An Activity that will present content on the Rear Display.
executor: Executor

Executor used to provide updates to windowAreaPresentationSessionCallback.
windowAreaPresentationSessionCallback: WindowAreaPresentationSessionCallback

to be notified of updates to the lifecycle of the currently enabled rear display presentation.
See also
windowAreaInfos

transferActivityToWindowArea

Added in 1.2.0
abstract fun transferActivityToWindowArea(
    token: Binder,
    activity: Activity,
    executor: Executor,
    windowAreaSessionCallback: WindowAreaSessionCallback
): Unit

Starts a transfer session where the calling Activity is moved to the window area identified by the token. Updates on the session are provided through the WindowAreaSessionCallback. Attempting to start a transfer session when the WindowAreaInfo does not return WindowAreaCapability.Status.WINDOW_AREA_STATUS_AVAILABLE will result in WindowAreaSessionCallback.onSessionEnded containing an IllegalStateException

Only the top visible application can request to start a transfer session.

The calling Activity will likely go through a configuration change since the window area it will be transferred to is usually different from the current area the Activity is in. The callback is retained during the lifetime of the session. If an Activity is captured in the callback and it does not handle the configuration change then it will be leaked. Consider using an androidx.lifecycle.ViewModel since that is meant to outlive the Activity lifecycle. If the Activity does override configuration changes, it is safe to have the Activity handle the WindowAreaSessionCallback. This guarantees that the calling Activity will continue to receive WindowAreaSessionCallback.onSessionEnded and keep a handle to the WindowAreaSession provided through WindowAreaSessionCallback.onSessionStarted.

The windowAreaSessionCallback provided will receive a call to WindowAreaSessionCallback.onSessionStarted after the Activity has been transferred to the window area. The transfer session will stay active until the session provided through WindowAreaSessionCallback.onSessionStarted is closed. Depending on the WindowAreaInfo.Type there may be other triggers that end the session, such as if a device state change makes the window area unavailable. One example of this is if the Activity is currently transferred to the TYPE_REAR_FACING window area of a foldable device, the session will be ended when the device is closed. When this occurs, WindowAreaSessionCallback.onSessionEnded is called.

Parameters
token: Binder

Binder token identifying the window area to be transferred to.
activity: Activity

Base Activity making the call to transferActivityToWindowArea.
executor: Executor

Executor used to provide updates to windowAreaSessionCallback.
windowAreaSessionCallback: WindowAreaSessionCallback

to be notified when the rear display session is started and ended.
See also
windowAreaInfos

Public properties

windowAreaInfos

Added in 1.2.0
abstract val windowAreaInfos: Flow<List<WindowAreaInfo>>

Flow of the list of current WindowAreaInfos that are currently available to be interacted with.

If WindowSdkExtensions.extensionVersion is less than 2, the flow will return empty WindowAreaInfo list flow.