AppTask

WINDOWING_LAYER_NORMAL_APP

static val WINDOWING_LAYER_NORMAL_APP: Int

The windowing layer for normal application windows.

If an application does not explicitly request a windowing layer for its task, it is considered to be in this layer.

Requesting this layer using AppTask.requestWindowingLayer is typically done to exit a previously requested layer.

Value: 1

WINDOWING_LAYER_PINNED

static val WINDOWING_LAYER_PINNED: Int

The windowing layer for pinned windows. These windows are typically displayed above normal application windows.

To ensure system integrity and a consistent user experience, the system imposes several restrictions on tasks using this layer. These may include, but are not limited to:

• Forcing the task to be completely opaque and display system decorations.
• Strictly limiting the number of tasks in this layer (e.g., only one at a time).
• Limiting the application's control over the task's size and position.
• Limiting the maximum window size to which the user can resize the task.
• Making the task non-movable programmatically (including restrictions on workarounds like resizing).
• Providing users with immediate settings access to disable the feature.
• Providing users with a way to close the window.
• The task may be finished by the system if it can no longer be hosted on this layer due to windowing changes.
• The available display modes may be limited for tasks on this layer. These may include, but are not limited to: Picture-in-Picture mode, Split-screen mode, and fullscreen.

This layer might be shared with Picture-in-Picture (PiP) tasks; therefore, tasks on this layer might be dismissed when another enters PiP.

The task's window on this layer has the following requirements:

• Must be opaque.
• Must have affordances to close the window and to allow users to disable showing and running tasks on this layer, per app.
• Must have a minimum size of 220dp according to the established Multi-windows CDD requirements.
• The task cannot change to another layer unless requested by the app with a call to AppTask.requestWindowingLayer.

Value: 2

WINDOWING_LAYER_REQUEST_GRANTED

static val WINDOWING_LAYER_REQUEST_GRANTED: Int

The request to change the windowing layer was granted.

Value: 0

WINDOWING_LAYER_REQUEST_REJECTED

static val WINDOWING_LAYER_REQUEST_REJECTED: Int

The request to change the windowing layer was rejected.

This result implies the system is in a state where the request cannot be fulfilled, but the request itself was valid.

Value: 1

WINDOWING_LAYER_UNDEFINED

static val WINDOWING_LAYER_UNDEFINED: Int

The windowing layer is not specified. The system will use a WINDOWING_LAYER_NORMAL_APP layer.

Value: 0

finishAndRemoveTask

open fun finishAndRemoveTask(): Unit

Finishes all activities in this task and removes it from the recent tasks list.

getTaskInfo

open fun getTaskInfo(): ActivityManager.RecentTaskInfo?

Get the RecentTaskInfo associated with this task.

moveTaskTo

open fun moveTaskTo(
    location: TaskLocation, 
    executor: Executor, 
    callback: OutcomeReceiver<TaskLocation!, Exception!>
): Unit

Repositions the task to the specified TaskLocation.

If the TaskLocation's bounds are invalid (i.e. too small or not fully inside the target display), the request will be rejected.

When the repositioning request is approved or rejected, the callback will be invoked. If the request is approved, the callback will receive a TaskLocation containing the new display ID and bounds of the task. The final display ID and bounds may be adjusted to the closest acceptable states from the requested ones at the system's discretion.

If the request is rejected, the callback will receive an exception with a descriptive message accessible via Exception.getMessage(). This exception will be one of the following:

• SecurityException if the requester doesn't hold the permission required to use this method;
• SecurityException if this task cannot be placed as requested due to violation of the Background Activity Launch (BAL) policy;
• IllegalStateException if the task is not in a state that allows it to change its TaskLocation programmatically at runtime of the request;
• SecurityException if this task cannot be placed on the target display requested. This can happen when the display is not trusted and not owned by the calling app;
• IllegalArgumentException if the TaskLocation provided does not include a valid display ID or the bounds provided are not fully contained inside the given display or the bounds provided are smaller than the minimum size defined in the CDD in either direction.

It is allowed to move a task to a display with which the call of android.app.ActivityManager#isTaskMoveAllowedOnDisplay() returns false, but the task won't be allowed to be programmatically moved again until users take actions to make the same task movable again.

If the task stays on its original display, its z-order will not be affected. Otherwise, if the task moves to a different display, it will become focused.
Requires android.Manifest.permission#REPOSITION_SELF_WINDOWS

moveToFront

open fun moveToFront(): Unit

Bring this task to the foreground. If it contains activities, they will be brought to the foreground with it and their instances re-created if needed. If it doesn't contain activities, the root activity of the task will be re-launched.

requestWindowingLayer

open fun requestWindowingLayer(
    layer: Int, 
    executor: Executor, 
    callback: OutcomeReceiver<Int!, Exception!>
): Unit

Requests the windowing layer for this task. This can be used to affect the Z-ordering of the activity's window relative to other windows.

The task will be moved to the requested layer if possible. When the request is approved or rejected, the callback will be invoked. If rejected, the callback will receive an exception with a descriptive message accessible via Exception.getMessage().

If the request is rejected due to a system state, the callback will receive AppTask.WINDOWING_LAYER_REQUEST_REJECTED. If the request is granted, the callback will receive AppTask.WINDOWING_LAYER_REQUEST_GRANTED.

To ensure system integrity and a consistent user experience, the system might impose restrictions on tasks requesting a specific layer. See AppTask.WINDOWING_LAYER_PINNED for implications when requesting the pinned layer.

If AppTask.WINDOWING_LAYER_PINNED is requested, android.app.AppOpsManager#OPSTR_PICTURE_IN_PICTURE must be allowed and the android.Manifest.permission#USE_PINNED_WINDOWING_LAYER permission must be granted.

If the request fails due to a developer error (such as missing permissions or invalid arguments), OutcomeReceiver.onError will be invoked with a Exception describing the error.

setExcludeFromRecents

open fun setExcludeFromRecents(exclude: Boolean): Unit

Modify the Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS flag in the root Intent of this AppTask.

startActivity

open fun startActivity(
    context: Context!, 
    intent: Intent!, 
    options: Bundle!
): Unit

Start an activity in this task. Brings the task to the foreground. If this task is not currently active (that is, its id < 0), then a new activity for the given Intent will be launched as the root of the task and the task brought to the foreground. Otherwise, if this task is currently active and the Intent does not specify an activity to launch in a new task, then a new activity for the given Intent will be launched on top of the task and the task brought to the foreground. If this task is currently active and the Intent specifies Intent.FLAG_ACTIVITY_NEW_TASK or would otherwise be launched in to a new task, then the activity not launched but this task be brought to the foreground and a new intent delivered to the top activity if appropriate.

In other words, you generally want to use an Intent here that does not specify Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_NEW_DOCUMENT, and let the system do the right thing.