ActivityEmbeddingController.kt
/*
* Copyright 2022 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.window.embedding
import android.app.Activity
import android.app.ActivityOptions
import android.content.Context
import android.os.IBinder
import androidx.window.core.ExperimentalWindowApi
/** The controller that allows checking the current [Activity] embedding status. */
class ActivityEmbeddingController internal constructor(private val backend: EmbeddingBackend) {
/**
* Checks if the [activity] is embedded and its presentation may be customized by the host
* process of the task this [activity] is associated with.
*
* @param activity the [Activity] to check.
*/
// TODO(b/204399167) Migrate to a Flow
fun isActivityEmbedded(activity: Activity): Boolean =
backend.isActivityEmbedded(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].
*
* @param activity The [Activity] to check.
* @return the [ActivityStack] that this [activity] is part of, or `null` if there is no such
* [ActivityStack].
*/
@ExperimentalWindowApi
fun getActivityStack(activity: Activity): ActivityStack? =
backend.getActivityStack(activity)
/**
* Sets the launching [ActivityStack] to the given [android.app.ActivityOptions].
*
* @param options The [android.app.ActivityOptions] to be updated.
* @param token The token of the [ActivityStack] to be set.
*/
internal fun setLaunchingActivityStack(
options: ActivityOptions,
token: IBinder
): ActivityOptions {
return backend.setLaunchingActivityStack(options, token)
}
/**
* Finishes a set of [activityStacks][ActivityStack] from the lowest to the highest z-order
* regardless of the order of [ActivityStack] set.
*
* If the remaining [ActivityStack] from a split participates in other splits with other
* `activityStacks`, they might be showing instead. 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 associated `activityStacks` of a [ActivityStack] are finished, the [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 calling
* [isFinishingActivityStacksSupported]. 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].
*
* @param activityStacks The set of [ActivityStack] to be finished.
* @throws UnsupportedOperationException if this device doesn't support this API and
* [isFinishingActivityStacksSupported] returns `false`.
* @sample androidx.window.samples.embedding.expandPrimaryContainer
*/
@ExperimentalWindowApi
fun finishActivityStacks(activityStacks: Set<ActivityStack>) =
backend.finishActivityStacks(activityStacks)
/**
* Checks whether [finishActivityStacks] is supported.
*
* @return `true` if [finishActivityStacks] is supported on the device, `false` otherwise.
*/
@ExperimentalWindowApi
fun isFinishingActivityStacksSupported(): Boolean =
backend.isFinishActivityStacksSupported()
companion object {
/**
* Obtains an instance of [ActivityEmbeddingController].
*
* @param context the [Context] to initialize the controller with
*/
@JvmStatic
fun getInstance(context: Context): ActivityEmbeddingController {
val backend = EmbeddingBackend.getInstance(context)
return ActivityEmbeddingController(backend)
}
}
}