Added in API level 21

Summary: Constants | Methods | Inherited Methods

ActivityManager.AppTask

---

Kotlin |Java

public static class ActivityManager.AppTask
extends Object

java.lang.Object
↳	android.app.ActivityManager.AppTask

---

The AppTask allows you to manage your own application's tasks. See ActivityManager.getAppTasks()

Summary

Constants
int	WINDOWING_LAYER_NORMAL_APP The windowing layer for normal application windows.
int	WINDOWING_LAYER_PINNED The windowing layer for pinned windows.
int	WINDOWING_LAYER_REQUEST_GRANTED The request to change the windowing layer was granted.
int	WINDOWING_LAYER_REQUEST_REJECTED The request to change the windowing layer was rejected.
int	WINDOWING_LAYER_UNDEFINED The windowing layer is not specified.

Public methods
void	finishAndRemoveTask() Finishes all activities in this task and removes it from the recent tasks list.
ActivityManager.RecentTaskInfo	getTaskInfo() Get the RecentTaskInfo associated with this task.
void	moveTaskTo(TaskLocation location, Executor executor, OutcomeReceiver<TaskLocation, Exception> callback) Repositions the task to the specified TaskLocation.
void	moveToFront() Bring this task to the foreground.
void	requestWindowingLayer(int layer, Executor executor, OutcomeReceiver<Integer, Exception> callback) Requests the windowing layer for this task.
void	setExcludeFromRecents(boolean exclude) Modify the Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS flag in the root Intent of this AppTask.
void	startActivity(Context context, Intent intent, Bundle options) Start an activity in this task.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

WINDOWING_LAYER_NORMAL_APP

Added in API level 37

public static final int WINDOWING_LAYER_NORMAL_APP

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.

See also:

• AppTask.requestWindowingLayer

Constant Value: 1 (0x00000001)

WINDOWING_LAYER_PINNED

Added in API level 37

public static final int WINDOWING_LAYER_PINNED

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.

See also:

• AppTask.requestWindowingLayer

Constant Value: 2 (0x00000002)

WINDOWING_LAYER_REQUEST_GRANTED

Added in API level 37

public static final int WINDOWING_LAYER_REQUEST_GRANTED

The request to change the windowing layer was granted.

Constant Value: 0 (0x00000000)

WINDOWING_LAYER_REQUEST_REJECTED

Added in API level 37

public static final int WINDOWING_LAYER_REQUEST_REJECTED

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.

Constant Value: 1 (0x00000001)

WINDOWING_LAYER_UNDEFINED

Added in API level 37

public static final int WINDOWING_LAYER_UNDEFINED

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

Constant Value: 0 (0x00000000)

Public methods

finishAndRemoveTask

Added in API level 21

public void finishAndRemoveTask ()

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

getTaskInfo

Added in API level 21

public ActivityManager.RecentTaskInfo getTaskInfo ()

Get the RecentTaskInfo associated with this task.

Returns
ActivityManager.RecentTaskInfo	The RecentTaskInfo for this task, or null if the task no longer exists.

moveTaskTo

Added in API level 37

public void moveTaskTo (TaskLocation location, 
                Executor executor, 
                OutcomeReceiver<TaskLocation, Exception> callback)

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 ERROR(ActivityManager.isTaskMoveAllowedOnDisplay()/android.app.ActivityManager#isTaskMoveAllowedOnDisplay() 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 Manifest.permission.REPOSITION_SELF_WINDOWS

Parameters
location	TaskLocation: TaskLocation with the target display or Display.INVALID_DISPLAY if the target display is the current display, and the new desired bounds. This value cannot be null.
executor	Executor: an Executor used to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback	OutcomeReceiver: a callback to receive the result of the request. This value cannot be null.

moveToFront

Added in API level 21

public void moveToFront ()

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

Added in API level 37

public void requestWindowingLayer (int layer, 
                Executor executor, 
                OutcomeReceiver<Integer, Exception> callback)

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, AppOpsManager.OPSTR_PICTURE_IN_PICTURE must be allowed and the 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.

Parameters
layer	int: The ERROR(WindowingLayer/android.app.ActivityManager.AppTask.WindowingLayer WindowingLayer) to move the task to. Value is one of the following: WINDOWING_LAYER_UNDEFINED WINDOWING_LAYER_NORMAL_APP WINDOWING_LAYER_PINNED
executor	Executor: An Executor used to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback	OutcomeReceiver: A callback to receive the result of the request. This value cannot be null.

setExcludeFromRecents

Added in API level 21

public void setExcludeFromRecents (boolean exclude)

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

Parameters
exclude	boolean: If true, Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS will be set; otherwise, it will be cleared.

startActivity

Added in API level 21

public void startActivity (Context context, 
                Intent intent, 
                Bundle options)

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.

Parameters
context	Context
intent	Intent: The Intent describing the new activity to be launched on the task.
options	Bundle: Optional launch options.

See also:

• Activity.startActivity(android.content.Intent,android.os.Bundle)