WindowAreaControllerCallbackAdapter

@ExperimentalWindowApi
public final class WindowAreaControllerCallbackAdapter extends WindowAreaController

java.lang.Object
   ↳ androidx.window.area.WindowAreaController
     ↳ androidx.window.java.area.WindowAreaControllerCallbackAdapter

An adapter for WindowAreaController to provide callback APIs.

Summary

Public constructors

Public methods
final void

Registers a listener that is interested in the current list of WindowAreaInfo available to be interacted with.
@NonNull Flow<@NonNull List<@NonNull WindowAreaInfo>>

Flow of the list of current WindowAreaInfos that are currently available to be interacted with.
void
presentContentOnWindowArea(
    @NonNull Binder token,
    @NonNull Activity activity,
    @NonNull Executor executor,
    @NonNull WindowAreaPresentationSessionCallback windowAreaPresentationSessionCallback
)

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

Removes a listener of available WindowAreaInfo records.
void
transferActivityToWindowArea(
    @NonNull Binder token,
    @NonNull Activity activity,
    @NonNull Executor executor,
    @NonNull WindowAreaSessionCallback windowAreaSessionCallback
)

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

Public constructors

WindowAreaControllerCallbackAdapter

Added in 1.2.0
public WindowAreaControllerCallbackAdapter(
    @NonNull WindowAreaController controller
)

Public methods

addWindowAreaInfoListListener

Added in 1.2.0
public final void addWindowAreaInfoListListener(
    @NonNull Executor executor,
    @NonNull Consumer<@NonNull List<@NonNull WindowAreaInfo>> listener
)

Registers a listener that is interested in the current list of WindowAreaInfo available to be interacted with.

The listener will receive an initial value on registration, as soon as it becomes available.

Parameters
@NonNull Executor executor

to handle sending listener updates.
@NonNull Consumer<@NonNull List<@NonNull WindowAreaInfo>> listener

to receive updates to the list of WindowAreaInfo.
See also
transferActivityToWindowArea
presentContentOnWindowArea

getWindowAreaInfos

Added in 1.4.0-alpha05
public @NonNull Flow<@NonNull List<@NonNull WindowAreaInfo>> getWindowAreaInfos()

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.

presentContentOnWindowArea

Added in 1.4.0-alpha05
public void presentContentOnWindowArea(
    @NonNull Binder token,
    @NonNull Activity activity,
    @NonNull Executor executor,
    @NonNull WindowAreaPresentationSessionCallback windowAreaPresentationSessionCallback
)

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
@NonNull Binder token

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

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

Executor used to provide updates to windowAreaPresentationSessionCallback.
@NonNull WindowAreaPresentationSessionCallback windowAreaPresentationSessionCallback

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

removeWindowAreaInfoListListener

Added in 1.2.0
public final void removeWindowAreaInfoListListener(
    @NonNull Consumer<@NonNull List<@NonNull WindowAreaInfo>> listener
)

Removes a listener of available WindowAreaInfo records. If the listener is not present then this method is a no-op.

Parameters
@NonNull Consumer<@NonNull List<@NonNull WindowAreaInfo>> listener

to remove from receiving status updates.
See also
transferActivityToWindowArea
presentContentOnWindowArea

transferActivityToWindowArea

Added in 1.4.0-alpha05
public void transferActivityToWindowArea(
    @NonNull Binder token,
    @NonNull Activity activity,
    @NonNull Executor executor,
    @NonNull WindowAreaSessionCallback windowAreaSessionCallback
)

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
@NonNull Binder token

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

Base Activity making the call to transferActivityToWindowArea.
@NonNull Executor executor

Executor used to provide updates to windowAreaSessionCallback.
@NonNull WindowAreaSessionCallback windowAreaSessionCallback

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