ActivityOptions

public class ActivityOptions
extends Object

java.lang.Object
   ↳ android.app.ActivityOptions


Helper class for building an options Bundle that can be used with Context.startActivity(Intent, Bundle) and related methods.

Summary

Constants

String EXTRA_USAGE_TIME_REPORT

A long in the extras delivered by requestUsageTimeReport(PendingIntent) that contains the total time (in ms) the user spent in the app flow.

String EXTRA_USAGE_TIME_REPORT_PACKAGES

A Bundle in the extras delivered by requestUsageTimeReport(PendingIntent) that contains detailed information about the time spent in each package associated with the app; each key is a package name, whose value is a long containing the time (in ms).

int MODE_BACKGROUND_ACTIVITY_START_ALLOWED

Allow the PendingIntent to use the background activity start privileges.

int MODE_BACKGROUND_ACTIVITY_START_DENIED

Deny the PendingIntent to use the background activity start privileges.

int MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED

No explicit value chosen.

Public methods

Rect getLaunchBounds()

Returns the bounds that should be used to launch the activity.

int getLaunchDisplayId()

Gets the id of the display where activity should be launched.

boolean getLockTaskMode()

Gets whether the activity is to be launched into LockTask mode.

int getPendingIntentBackgroundActivityStartMode()

Get the mode for allowing or denying the senders privileges to start background activities to the PendingIntent.

int getPendingIntentCreatorBackgroundActivityStartMode()

Returns the mode to start background activities granted by the creator of the PendingIntent.

int getSplashScreenStyle()

Gets the style can be used for cold-launching an activity.

boolean isPendingIntentBackgroundActivityLaunchAllowed()

This method was deprecated in API level 34. use getPendingIntentBackgroundActivityStartMode() since for apps targeting Build.VERSION_CODES.UPSIDE_DOWN_CAKE or higher this value might not match the actual behavior if the value was not explicitly set.

boolean isShareIdentityEnabled()

Returns whether the launching app has opted-in to sharing its identity with the launched activity.

static ActivityOptions makeBasic()

Create a basic ActivityOptions that has no special animation associated with it.

static ActivityOptions makeClipRevealAnimation(View source, int startX, int startY, int width, int height)

Create an ActivityOptions specifying an animation where the new activity is revealed from a small originating area of the screen to its final full representation.

static ActivityOptions makeCustomAnimation(Context context, int enterResId, int exitResId)

Create an ActivityOptions specifying a custom animation to run when the activity is displayed.

static ActivityOptions makeCustomAnimation(Context context, int enterResId, int exitResId, int backgroundColor)

Create an ActivityOptions specifying a custom animation to run when the activity is displayed.

static ActivityOptions makeLaunchIntoPip(PictureInPictureParams pictureInPictureParams)

Creates an ActivityOptions instance that launch into picture-in-picture.

static ActivityOptions makeScaleUpAnimation(View source, int startX, int startY, int width, int height)

Create an ActivityOptions specifying an animation where the new activity is scaled from a small originating area of the screen to its final full representation.

static ActivityOptions makeSceneTransitionAnimation(Activity activity, View sharedElement, String sharedElementName)

Create an ActivityOptions to transition between Activities using cross-Activity scene animations.

static ActivityOptions makeSceneTransitionAnimation(Activity activity, Pair...<ViewString> sharedElements)

Create an ActivityOptions to transition between Activities using cross-Activity scene animations.

static ActivityOptions makeTaskLaunchBehind()

If set along with Intent.FLAG_ACTIVITY_NEW_DOCUMENT then the task being launched will not be presented to the user but will instead be only available through the recents task list.

static ActivityOptions makeThumbnailScaleUpAnimation(View source, Bitmap thumbnail, int startX, int startY)

Create an ActivityOptions specifying an animation where a thumbnail is scaled from a given position to the new activity window that is being started.

void requestUsageTimeReport(PendingIntent receiver)

Ask the system track that time the user spends in the app being launched, and report it back once done.

ActivityOptions setAppVerificationBundle(Bundle bundle)

Set the Bundle that is provided to the app installer for additional verification if the call to Context#startActivity results in an app being installed.

ActivityOptions setLaunchBounds(Rect screenSpacePixelRect)

Sets the bounds (window size and position) that the activity should be launched in.

ActivityOptions setLaunchDisplayId(int launchDisplayId)

Sets the id of the display where the activity should be launched.

ActivityOptions setLockTaskEnabled(boolean lockTaskMode)

Sets whether the activity is to be launched into LockTask mode.

void setPendingIntentBackgroundActivityLaunchAllowed(boolean allowed)

This method was deprecated in API level 34. use #setPendingIntentBackgroundActivityStartMode(int) to set the full range of states

ActivityOptions setPendingIntentBackgroundActivityStartMode(int state)

Sets the mode for allowing or denying the senders privileges to start background activities to the PendingIntent.

ActivityOptions setPendingIntentCreatorBackgroundActivityStartMode(int mode)

Allow a PendingIntent to use the privilege of its creator to start background activities.

ActivityOptions setShareIdentityEnabled(boolean shareIdentity)

Sets whether the identity of the launching app should be shared with the activity.

ActivityOptions setSplashScreenStyle(int style)

Sets the preferred splash screen style of the opening activities.

Bundle toBundle()

Returns the created options as a Bundle, which can be passed to Context.startActivity(Intent, Bundle) and related methods.

void update(ActivityOptions otherOptions)

Update the current values in this ActivityOptions from those supplied in otherOptions.

Inherited methods

Constants

EXTRA_USAGE_TIME_REPORT

Added in API level 23
public static final String EXTRA_USAGE_TIME_REPORT

A long in the extras delivered by requestUsageTimeReport(PendingIntent) that contains the total time (in ms) the user spent in the app flow.

Constant Value: "android.activity.usage_time"

EXTRA_USAGE_TIME_REPORT_PACKAGES

Added in API level 23
public static final String EXTRA_USAGE_TIME_REPORT_PACKAGES

A Bundle in the extras delivered by requestUsageTimeReport(PendingIntent) that contains detailed information about the time spent in each package associated with the app; each key is a package name, whose value is a long containing the time (in ms).

Constant Value: "android.usage_time_packages"

MODE_BACKGROUND_ACTIVITY_START_ALLOWED

Added in API level 34
public static final int MODE_BACKGROUND_ACTIVITY_START_ALLOWED

Allow the PendingIntent to use the background activity start privileges.

Constant Value: 1 (0x00000001)

MODE_BACKGROUND_ACTIVITY_START_DENIED

Added in API level 34
public static final int MODE_BACKGROUND_ACTIVITY_START_DENIED

Deny the PendingIntent to use the background activity start privileges.

Constant Value: 2 (0x00000002)

MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED

Added in API level 34
public static final int MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED

No explicit value chosen. The system will decide whether to grant privileges.

Constant Value: 0 (0x00000000)

Public methods

getLaunchBounds

Added in API level 24
public Rect getLaunchBounds ()

Returns the bounds that should be used to launch the activity.

Returns
Rect Bounds used to launch the activity. This value may be null.

getLaunchDisplayId

Added in API level 26
public int getLaunchDisplayId ()

Gets the id of the display where activity should be launched.

Returns
int The id of the display where activity should be launched, Display.INVALID_DISPLAY if not set.

getLockTaskMode

Added in API level 28
public boolean getLockTaskMode ()

Gets whether the activity is to be launched into LockTask mode.

Returns
boolean true if the activity is to be launched into LockTask mode.

getPendingIntentBackgroundActivityStartMode

Added in API level 34
public int getPendingIntentBackgroundActivityStartMode ()

Get the mode for allowing or denying the senders privileges to start background activities to the PendingIntent.

Returns
int Value is android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED, android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED, or android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_DENIED

getPendingIntentCreatorBackgroundActivityStartMode

Added in API level 34
public int getPendingIntentCreatorBackgroundActivityStartMode ()

Returns the mode to start background activities granted by the creator of the PendingIntent.

Returns
int the mode currently set Value is android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED, android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED, or android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_DENIED

getSplashScreenStyle

Added in API level 33
public int getSplashScreenStyle ()

Gets the style can be used for cold-launching an activity.

Returns
int Value is android.window.SplashScreen.SPLASH_SCREEN_STYLE_UNDEFINED, SplashScreen.SPLASH_SCREEN_STYLE_SOLID_COLOR, or SplashScreen.SPLASH_SCREEN_STYLE_ICON

isPendingIntentBackgroundActivityLaunchAllowed

Added in API level 33
Deprecated in API level 34
public boolean isPendingIntentBackgroundActivityLaunchAllowed ()

This method was deprecated in API level 34.
use getPendingIntentBackgroundActivityStartMode() since for apps targeting Build.VERSION_CODES.UPSIDE_DOWN_CAKE or higher this value might not match the actual behavior if the value was not explicitly set.

Get PendingIntent activity is allowed to be started in the background if the caller can start background activities.

Returns
boolean

isShareIdentityEnabled

Added in API level 34
public boolean isShareIdentityEnabled ()

Returns whether the launching app has opted-in to sharing its identity with the launched activity.

Returns
boolean true if the launching app has opted-in to sharing its identity

makeBasic

Added in API level 23
public static ActivityOptions makeBasic ()

Create a basic ActivityOptions that has no special animation associated with it. Other options can still be set.

Returns
ActivityOptions

makeClipRevealAnimation

Added in API level 23
public static ActivityOptions makeClipRevealAnimation (View source, 
                int startX, 
                int startY, 
                int width, 
                int height)

Create an ActivityOptions specifying an animation where the new activity is revealed from a small originating area of the screen to its final full representation.

Parameters
source View: The View that the new activity is animating from. This defines the coordinate space for startX and startY.

startX int: The x starting location of the new activity, relative to source.

startY int: The y starting location of the activity, relative to source.

width int: The initial width of the new activity.

height int: The initial height of the new activity.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeCustomAnimation

Added in API level 16
public static ActivityOptions makeCustomAnimation (Context context, 
                int enterResId, 
                int exitResId)

Create an ActivityOptions specifying a custom animation to run when the activity is displayed.

Parameters
context Context: Who is defining this. This is the application that the animation resources will be loaded from.

enterResId int: A resource ID of the animation resource to use for the incoming activity. Use 0 for no animation.

exitResId int: A resource ID of the animation resource to use for the outgoing activity. Use 0 for no animation.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeCustomAnimation

Added in API level 33
public static ActivityOptions makeCustomAnimation (Context context, 
                int enterResId, 
                int exitResId, 
                int backgroundColor)

Create an ActivityOptions specifying a custom animation to run when the activity is displayed.

Parameters
context Context: Who is defining this. This is the application that the animation resources will be loaded from. This value cannot be null.

enterResId int: A resource ID of the animation resource to use for the incoming activity. Use 0 for no animation.

exitResId int: A resource ID of the animation resource to use for the outgoing activity. Use 0 for no animation.

backgroundColor int: The background color to use for the background during the animation if the animation requires a background. Set to 0 to not override the default color.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. This value cannot be null.

makeLaunchIntoPip

Added in API level 33
public static ActivityOptions makeLaunchIntoPip (PictureInPictureParams pictureInPictureParams)

Creates an ActivityOptions instance that launch into picture-in-picture. This is normally used by a Host activity to start another activity that will directly enter picture-in-picture upon its creation.

Parameters
pictureInPictureParams PictureInPictureParams: PictureInPictureParams for launching the Activity to picture-in-picture mode. This value cannot be null.

Returns
ActivityOptions This value cannot be null.

makeScaleUpAnimation

Added in API level 16
public static ActivityOptions makeScaleUpAnimation (View source, 
                int startX, 
                int startY, 
                int width, 
                int height)

Create an ActivityOptions specifying an animation where the new activity is scaled from a small originating area of the screen to its final full representation.

If the Intent this is being used with has not set its Intent.setSourceBounds, those bounds will be filled in for you based on the initial bounds passed in here.

Parameters
source View: The View that the new activity is animating from. This defines the coordinate space for startX and startY.

startX int: The x starting location of the new activity, relative to source.

startY int: The y starting location of the activity, relative to source.

width int: The initial width of the new activity.

height int: The initial height of the new activity.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeSceneTransitionAnimation

Added in API level 21
public static ActivityOptions makeSceneTransitionAnimation (Activity activity, 
                View sharedElement, 
                String sharedElementName)

Create an ActivityOptions to transition between Activities using cross-Activity scene animations. This method carries the position of one shared element to the started Activity. The position of sharedElement will be used as the epicenter for the exit Transition. The position of the shared element in the launched Activity will be the epicenter of its entering Transition.

This requires Window.FEATURE_ACTIVITY_TRANSITIONS to be enabled on the calling Activity to cause an exit transition. The same must be in the called Activity to get an entering transition.

Parameters
activity Activity: The Activity whose window contains the shared elements.

sharedElement View: The View to transition to the started Activity.

sharedElementName String: The shared element name as used in the target Activity. This must not be null.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeSceneTransitionAnimation

Added in API level 21
public static ActivityOptions makeSceneTransitionAnimation (Activity activity, 
                Pair...<ViewString> sharedElements)

Create an ActivityOptions to transition between Activities using cross-Activity scene animations. This method carries the position of multiple shared elements to the started Activity. The position of the first element in sharedElements will be used as the epicenter for the exit Transition. The position of the associated shared element in the launched Activity will be the epicenter of its entering Transition.

This requires Window.FEATURE_ACTIVITY_TRANSITIONS to be enabled on the calling Activity to cause an exit transition. The same must be in the called Activity to get an entering transition.

Parameters
activity Activity: The Activity whose window contains the shared elements.

sharedElements Pair: The names of the shared elements to transfer to the called Activity and their associated Views. The Views must each have a unique shared element name.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeTaskLaunchBehind

Added in API level 21
public static ActivityOptions makeTaskLaunchBehind ()

If set along with Intent.FLAG_ACTIVITY_NEW_DOCUMENT then the task being launched will not be presented to the user but will instead be only available through the recents task list. In addition, the new task wil be affiliated with the launching activity's task. Affiliated tasks are grouped together in the recents task list.

This behavior is not supported for activities with launchMode values of singleInstance or singleTask.

Returns
ActivityOptions

makeThumbnailScaleUpAnimation

Added in API level 16
public static ActivityOptions makeThumbnailScaleUpAnimation (View source, 
                Bitmap thumbnail, 
                int startX, 
                int startY)

Create an ActivityOptions specifying an animation where a thumbnail is scaled from a given position to the new activity window that is being started.

If the Intent this is being used with has not set its Intent.setSourceBounds, those bounds will be filled in for you based on the initial thumbnail location and size provided here.

Parameters
source View: The View that this thumbnail is animating from. This defines the coordinate space for startX and startY.

thumbnail Bitmap: The bitmap that will be shown as the initial thumbnail of the animation.

startX int: The x starting location of the bitmap, relative to source.

startY int: The y starting location of the bitmap, relative to source.

Returns
ActivityOptions Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

requestUsageTimeReport

Added in API level 23
public void requestUsageTimeReport (PendingIntent receiver)

Ask the system track that time the user spends in the app being launched, and report it back once done. The report will be sent to the given receiver, with the extras EXTRA_USAGE_TIME_REPORT and EXTRA_USAGE_TIME_REPORT_PACKAGES filled in.

The time interval tracked is from launching this activity until the user leaves that activity's flow. They are considered to stay in the flow as long as new activities are being launched or returned to from the original flow, even if this crosses package or task boundaries. For example, if the originator starts an activity to view an image, and while there the user selects to share, which launches their email app in a new task, and they complete the share, the time during that entire operation will be included until they finally hit back from the original image viewer activity.

The user is considered to complete a flow once they switch to another activity that is not part of the tracked flow. This may happen, for example, by using the notification shade, launcher, or recents to launch or switch to another app. Simply going in to these navigation elements does not break the flow (although the launcher and recents stops time tracking of the session); it is the act of going somewhere else that completes the tracking.

Parameters
receiver PendingIntent: A broadcast receiver that willl receive the report.

setAppVerificationBundle

Added in API level 26
public ActivityOptions setAppVerificationBundle (Bundle bundle)

Set the Bundle that is provided to the app installer for additional verification if the call to Context#startActivity results in an app being installed. This Bundle is not provided to any other app besides the installer.

Parameters
bundle Bundle

Returns
ActivityOptions

setLaunchBounds

Added in API level 24
public ActivityOptions setLaunchBounds (Rect screenSpacePixelRect)

Sets the bounds (window size and position) that the activity should be launched in. Rect position should be provided in pixels and in screen coordinates. Set to null to explicitly launch fullscreen.

NOTE: This value is ignored on devices that don't have PackageManager.FEATURE_FREEFORM_WINDOW_MANAGEMENT or PackageManager.FEATURE_PICTURE_IN_PICTURE enabled.

Parameters
screenSpacePixelRect Rect: launch bounds or null for fullscreen

Returns
ActivityOptions this ActivityOptions instance

setLaunchDisplayId

Added in API level 26
public ActivityOptions setLaunchDisplayId (int launchDisplayId)

Sets the id of the display where the activity should be launched. An app can launch activities on public displays or displays where the app already has activities. Otherwise, trying to launch on a private display or providing an invalid display id will result in an exception.

Setting launch display id will be ignored on devices that don't have PackageManager.FEATURE_ACTIVITIES_ON_SECONDARY_DISPLAYS.

Parameters
launchDisplayId int: The id of the display where the activity should be launched.

Returns
ActivityOptions this ActivityOptions instance.

setLockTaskEnabled

Added in API level 28
public ActivityOptions setLockTaskEnabled (boolean lockTaskMode)

Sets whether the activity is to be launched into LockTask mode. Use this option to start an activity in LockTask mode. Note that only apps permitted by DevicePolicyManager can run in LockTask mode. Therefore, if DevicePolicyManager.isLockTaskPermitted(String) returns false for the package of the target activity, a SecurityException will be thrown during Context#startActivity(Intent, Bundle). This method doesn't affect activities that are already running \u2014 relaunch the activity to run in lock task mode. Defaults to false if not set.

Parameters
lockTaskMode boolean: true if the activity is to be launched into LockTask mode.

Returns
ActivityOptions this ActivityOptions instance.

setPendingIntentBackgroundActivityLaunchAllowed

Added in API level 33
Deprecated in API level 34
public void setPendingIntentBackgroundActivityLaunchAllowed (boolean allowed)

This method was deprecated in API level 34.
use #setPendingIntentBackgroundActivityStartMode(int) to set the full range of states

Set PendingIntent activity is allowed to be started in the background if the caller can start background activities.

Parameters
allowed boolean

setPendingIntentBackgroundActivityStartMode

Added in API level 34
public ActivityOptions setPendingIntentBackgroundActivityStartMode (int state)

Sets the mode for allowing or denying the senders privileges to start background activities to the PendingIntent. This is typically used in when executing PendingIntent#send(Context, int, Intent, PendingIntent.OnFinished, Handler, String, Bundle) or similar methods. A privileged sender of a PendingIntent should only grant MODE_BACKGROUND_ACTIVITY_START_ALLOWED if the PendingIntent is from a trusted source and/or executed on behalf the user.

Parameters
state int: Value is android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED, android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED, or android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_DENIED

Returns
ActivityOptions This value cannot be null.

setPendingIntentCreatorBackgroundActivityStartMode

Added in API level 34
public ActivityOptions setPendingIntentCreatorBackgroundActivityStartMode (int mode)

Allow a PendingIntent to use the privilege of its creator to start background activities.

Parameters
mode int: the mode being set Value is android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED, android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED, or android.app.ComponentOptions.MODE_BACKGROUND_ACTIVITY_START_DENIED

Returns
ActivityOptions This value cannot be null.

setShareIdentityEnabled

Added in API level 34
public ActivityOptions setShareIdentityEnabled (boolean shareIdentity)

Sets whether the identity of the launching app should be shared with the activity.

Use this option when starting an activity that needs to know the identity of the launching app; with this set to true, the activity will have access to the launching app's package name and uid.

Defaults to false if not set.

Note, even if the launching app does not explicitly enable sharing of its identity, if the activity is started with Activity#startActivityForResult, then Activity.getCallingPackage() will still return the launching app's package name to allow validation of the result's recipient. Also, an activity running within a package signed by the same key used to sign the platform (some system apps such as Settings will be signed with the platform's key) will have access to the launching app's identity.

Parameters
shareIdentity boolean: whether the launching app's identity should be shared with the activity

Returns
ActivityOptions this ActivityOptions instance. This value cannot be null.

setSplashScreenStyle

Added in API level 33
public ActivityOptions setSplashScreenStyle (int style)

Sets the preferred splash screen style of the opening activities. This only applies if the Activity or Process is not yet created.

Parameters
style int: Can be either SplashScreen#SPLASH_SCREEN_STYLE_ICON or SplashScreen#SPLASH_SCREEN_STYLE_SOLID_COLOR Value is android.window.SplashScreen.SPLASH_SCREEN_STYLE_UNDEFINED, SplashScreen.SPLASH_SCREEN_STYLE_SOLID_COLOR, or SplashScreen.SPLASH_SCREEN_STYLE_ICON

Returns
ActivityOptions This value cannot be null.

toBundle

Added in API level 16
public Bundle toBundle ()

Returns the created options as a Bundle, which can be passed to Context.startActivity(Intent, Bundle) and related methods. Note that the returned Bundle is still owned by the ActivityOptions object; you must not modify it, but can supply it to the startActivity methods that take an options Bundle.

Returns
Bundle

update

Added in API level 16
public void update (ActivityOptions otherOptions)

Update the current values in this ActivityOptions from those supplied in otherOptions. Any values defined in otherOptions replace those in the base options.

Parameters
otherOptions ActivityOptions