ActivityEmbeddingController

@RequiresWindowSdkExtension(version = 6)
public final @NonNull Flow<@NonNull EmbeddedActivityWindowInfo> embeddedActivityWindowInfo(@NonNull Activity activity)

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.

@RequiresWindowSdkExtension(version = 5)
public final void finishActivityStacks(@NonNull Set<@NonNull ActivityStack> activityStacks)

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)
}

public final ActivityStack getActivityStack(@NonNull Activity activity)

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.

public static final @NonNull ActivityEmbeddingController getInstance(@NonNull Context context)

Obtains an instance of ActivityEmbeddingController.

@RequiresWindowSdkExtension(version = 3)
public final void invalidateVisibleActivityStacks()

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.

public final boolean isActivityEmbedded(@NonNull Activity activity)

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

@RequiresWindowSdkExtension(version = 5)
public final void setEmbeddingConfiguration(
    @NonNull EmbeddingConfiguration embeddingConfiguration
)

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.