ActivityEmbeddingController

class ActivityEmbeddingController

The controller that allows checking the current Activity embedding status.

Summary

Public companion functions
ActivityEmbeddingController
getInstance(context: Context)

Obtains an instance of ActivityEmbeddingController.

Public functions
Flow<EmbeddedActivityWindowInfo>

A Flow of EmbeddedActivityWindowInfo that reports the change to the embedded window related info of the activity.
Unit

Finishes a set of activityStacks from the lowest to the highest z-order regardless of the order of activityStack passed in the input parameter.
ActivityStack?

Returns the ActivityStack that this activity is part of when it is being organized in the embedding container and associated with a SplitInfo.
Unit

Triggers calculator functions set through SplitController.setSplitAttributesCalculator and OverlayController.setOverlayAttributesCalculator to update attributes for visible activityStacks.
Boolean

Checks if the activity is embedded and its presentation may be customized by the host process of the task this activity is associated with.
Unit
@RequiresWindowSdkExtension(version = 5)
setEmbeddingConfiguration(
    embeddingConfiguration: EmbeddingConfiguration
)

Sets the EmbeddingConfiguration of the Activity Embedding environment that defines how the embedded Activities behaves.

Public companion functions

getInstance

Added in 1.1.0
fun getInstance(context: Context): ActivityEmbeddingController

Obtains an instance of ActivityEmbeddingController.

Parameters
context: Context

the Context to initialize the controller with

Public functions

embeddedActivityWindowInfo

Added in 1.4.0-alpha01
@RequiresWindowSdkExtension(version = 6)
fun embeddedActivityWindowInfo(activity: Activity): Flow<EmbeddedActivityWindowInfo>

A Flow of EmbeddedActivityWindowInfo that reports the change to the embedded window related info of the activity.

The Flow will immediately be invoked with the latest value upon registration if the activity is currently embedded as EmbeddedActivityWindowInfo.isEmbedded is true.

When the activity is embedded, the Flow will be invoked when EmbeddedActivityWindowInfo is changed. When the activity is not embedded, the Flow will not be triggered unless the activity is becoming non-embedded from embedded.

Note that this API is only supported on the device with WindowSdkExtensions.extensionVersion equal to or larger than 6. If WindowSdkExtensions.extensionVersion is less than 6, this Flow will not be invoked.

Parameters
activity: Activity

the Activity that is interested in getting the embedded window info.
Returns
Flow<EmbeddedActivityWindowInfo>

a Flow of EmbeddedActivityWindowInfo of the activity.

finishActivityStacks

Added in 1.4.0-alpha01
@RequiresWindowSdkExtension(version = 5)
fun finishActivityStacks(activityStacks: Set<ActivityStack>): Unit

Finishes a set of activityStacks from the lowest to the highest z-order regardless of the order of activityStack passed in the input parameter.

If a remaining activityStack from a split participates in other splits with other activityStacks, the remaining activityStack might split with other activityStacks. For example, if activityStack A splits with activityStack B and C, and activityStack C covers activityStack B, finishing activityStack C might make the split of activityStack A and B show.

If all split-associated activityStacks are finished, the remaining activityStack will be expanded to fill the parent task container. This is useful to expand the primary container as the sample linked below shows.

Note that it's caller's responsibility to check whether this API is supported by checking WindowSdkExtensions.extensionVersion is greater than or equal to 5. If not, an alternative approach to finishing all containers above a particular activity can be to launch it again with flag android.content.Intent.FLAG_ACTIVITY_CLEAR_TOP.

import androidx.window.embedding.ActivityEmbeddingController
import androidx.window.embedding.SplitController

SplitController.getInstance(primaryActivity).splitInfoList(primaryActivity).collect {
    splitInfoList ->
    // Find all associated secondary ActivityStacks
    val associatedSecondaryActivityStacks =
        splitInfoList.mapTo(mutableSetOf()) { splitInfo -> splitInfo.secondaryActivityStack }
    // Finish them all.
    ActivityEmbeddingController.getInstance(primaryActivity)
        .finishActivityStacks(associatedSecondaryActivityStacks)
}
Parameters
activityStacks: Set<ActivityStack>

The set of ActivityStack to be finished.
Throws
kotlin.UnsupportedOperationException

if extension version is less than 5.

getActivityStack

Added in 1.2.0
fun getActivityStack(activity: Activity): ActivityStack?

Returns the ActivityStack that this activity is part of when it is being organized in the embedding container and associated with a SplitInfo. Returns null if there is no such ActivityStack.

Started from WindowSdkExtensions.extensionVersion 5, this method can also obtain standalone ActivityStack, which is not associated with any SplitInfo. For example, an ActivityStack launched with ActivityRule.alwaysExpand, or an overlay ActivityStack launched by setLaunchingActivityStack with OverlayCreateParams.

Parameters
activity: Activity

The Activity to check.
Returns
ActivityStack?

the ActivityStack that this activity is part of, or null if there is no such ActivityStack.

invalidateVisibleActivityStacks

Added in 1.4.0-alpha01
@RequiresWindowSdkExtension(version = 3)
fun invalidateVisibleActivityStacks(): Unit

Triggers calculator functions set through SplitController.setSplitAttributesCalculator and OverlayController.setOverlayAttributesCalculator to update attributes for visible activityStacks.

This method can be used when the application wants to update the embedding presentation based on the application state.

This method is not needed for changes that are driven by window and device state changes or new activity starts, because those will invoke the calculator functions automatically.

Visible activityStacks are usually the last element of SplitInfo list which was received from the callback registered in SplitController.splitInfoList and an active overlay ActivityStack if exists.

The call will be no-op if there is no visible activityStacks or there's no calculator set.

Throws
kotlin.UnsupportedOperationException

if WindowSdkExtensions.extensionVersion is less than 3.
See also
setOverlayAttributesCalculator
setSplitAttributesCalculator

isActivityEmbedded

Added in 1.1.0
fun isActivityEmbedded(activity: Activity): Boolean

Checks if the activity is embedded and its presentation may be customized by the host process of the task this activity is associated with.

Parameters
activity: Activity

the Activity to check.

setEmbeddingConfiguration

Added in 1.4.0-alpha01
@RequiresWindowSdkExtension(version = 5)
fun setEmbeddingConfiguration(
    embeddingConfiguration: EmbeddingConfiguration
): Unit

Sets the EmbeddingConfiguration of the Activity Embedding environment that defines how the embedded Activities behaves.

The EmbeddingConfiguration can be supported only if the vendor API level of the target device is equals or higher than required API level. Otherwise, it would be no-op when setting the EmbeddingConfiguration on a target device that has lower API level.

In addition, the existing configuration in the library won't be overwritten if the properties of the given embeddingConfiguration are undefined. Only the configuration properties that are explicitly set will be updated.

Note that it is recommended to be configured in the androidx.startup.Initializer or android.app.Application.onCreate, so that the EmbeddingConfiguration is applied early in the application startup, before any activities complete initialization. The EmbeddingConfiguration updates afterward may or may not apply to already running activities.

Parameters
embeddingConfiguration: EmbeddingConfiguration

The EmbeddingConfiguration