ActivityOptions
open class ActivityOptions
kotlin.Any | |
↳ | android.app.ActivityOptions |
Helper class for building an options Bundle that can be used with Context.startActivity(Intent, Bundle)
and related methods.
Summary
Constants | |
---|---|
static String |
A long in the extras delivered by |
static String |
A Bundle in the extras delivered by |
static Int |
Allow the |
static Int |
Deny the |
static Int |
No explicit value chosen. |
Public methods | |
---|---|
open Rect? |
Returns the bounds that should be used to launch the activity. |
open Int |
Gets the id of the display where activity should be launched. |
open Boolean |
Gets whether the activity is to be launched into LockTask mode. |
open Int |
Get the mode for allowing or denying the senders privileges to start background activities to the PendingIntent. |
open Int |
Returns the mode to start background activities granted by the creator of the |
open Int |
Gets the style can be used for cold-launching an activity. |
open Boolean |
Get PendingIntent activity is allowed to be started in the background if the caller can start background activities. |
open Boolean |
Returns whether the launching app has opted-in to sharing its identity with the launched activity. |
open static ActivityOptions! |
Create a basic ActivityOptions that has no special animation associated with it. |
open static ActivityOptions! |
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. |
open static ActivityOptions! |
makeCustomAnimation(context: Context!, enterResId: Int, exitResId: Int) Create an ActivityOptions specifying a custom animation to run when the activity is displayed. |
open static ActivityOptions |
makeCustomAnimation(context: Context, enterResId: Int, exitResId: Int, backgroundColor: Int) Create an ActivityOptions specifying a custom animation to run when the activity is displayed. |
open static ActivityOptions |
makeLaunchIntoPip(pictureInPictureParams: PictureInPictureParams) Creates an |
open static ActivityOptions! |
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. |
open static ActivityOptions! |
makeSceneTransitionAnimation(activity: Activity!, : View!, : String!) Create an ActivityOptions to transition between Activities using cross-Activity scene animations. |
open static ActivityOptions! |
makeSceneTransitionAnimation(activity: Activity!, vararg : Pair<View!, String!>!) Create an ActivityOptions to transition between Activities using cross-Activity scene animations. |
open static ActivityOptions! |
If set along with Intent. |
open static ActivityOptions! |
makeThumbnailScaleUpAnimation(source: View!, thumbnail: Bitmap!, startX: Int, startY: Int) Create an ActivityOptions specifying an animation where a thumbnail is scaled from a given position to the new activity window that is being started. |
open Unit |
requestUsageTimeReport(receiver: PendingIntent!) Ask the system track that time the user spends in the app being launched, and report it back once done. |
open ActivityOptions! |
setAppVerificationBundle(bundle: Bundle!) Set the |
open ActivityOptions! |
setLaunchBounds(screenSpacePixelRect: Rect?) Sets the bounds (window size and position) that the activity should be launched in. |
open ActivityOptions! |
setLaunchDisplayId(launchDisplayId: Int) Sets the id of the display where the activity should be launched. |
open ActivityOptions! |
setLockTaskEnabled(lockTaskMode: Boolean) Sets whether the activity is to be launched into LockTask mode. |
open Unit |
Set PendingIntent activity is allowed to be started in the background if the caller can start background activities. |
open ActivityOptions |
Sets the mode for allowing or denying the senders privileges to start background activities to the PendingIntent. |
open ActivityOptions |
Allow a |
open ActivityOptions |
Sets whether the identity of the launching app should be shared with the activity. |
open ActivityOptions |
setSplashScreenStyle(style: Int) Sets the preferred splash screen style of the opening activities. |
open Bundle! |
toBundle() Returns the created options as a Bundle, which can be passed to |
open Unit |
update(otherOptions: ActivityOptions!) Update the current values in this ActivityOptions from those supplied in otherOptions. |
Constants
EXTRA_USAGE_TIME_REPORT
static val EXTRA_USAGE_TIME_REPORT: String
A long in the extras delivered by requestUsageTimeReport
that contains the total time (in ms) the user spent in the app flow.
Value: "android.activity.usage_time"
EXTRA_USAGE_TIME_REPORT_PACKAGES
static val EXTRA_USAGE_TIME_REPORT_PACKAGES: String
A Bundle in the extras delivered by requestUsageTimeReport
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).
Value: "android.usage_time_packages"
MODE_BACKGROUND_ACTIVITY_START_ALLOWED
static val MODE_BACKGROUND_ACTIVITY_START_ALLOWED: Int
Allow the PendingIntent
to use the background activity start privileges.
Value: 1
MODE_BACKGROUND_ACTIVITY_START_DENIED
static val MODE_BACKGROUND_ACTIVITY_START_DENIED: Int
Deny the PendingIntent
to use the background activity start privileges.
Value: 2
MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED
static val MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED: Int
No explicit value chosen. The system will decide whether to grant privileges.
Value: 0
Public methods
getLaunchBounds
open fun getLaunchBounds(): Rect?
Returns the bounds that should be used to launch the activity.
Return | |
---|---|
Rect? |
Bounds used to launch the activity. This value may be null . |
See Also
getLaunchDisplayId
open fun getLaunchDisplayId(): Int
Gets the id of the display where activity should be launched.
Return | |
---|---|
Int |
The id of the display where activity should be launched, android.view.Display#INVALID_DISPLAY if not set. |
See Also
getLockTaskMode
open fun getLockTaskMode(): Boolean
Gets whether the activity is to be launched into LockTask mode.
Return | |
---|---|
Boolean |
true if the activity is to be launched into LockTask mode. |
getPendingIntentBackgroundActivityStartMode
open fun getPendingIntentBackgroundActivityStartMode(): Int
Get the mode for allowing or denying the senders privileges to start background activities to the PendingIntent.
Return | |
---|---|
Int |
Value is android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_ALLOWED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_DENIED , or android.app.ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_COMPAT |
getPendingIntentCreatorBackgroundActivityStartMode
open fun getPendingIntentCreatorBackgroundActivityStartMode(): Int
Returns the mode to start background activities granted by the creator of the PendingIntent
.
Return | |
---|---|
Int |
the mode currently set Value is android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_ALLOWED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_DENIED , or android.app.ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_COMPAT |
getSplashScreenStyle
open fun getSplashScreenStyle(): Int
Gets the style can be used for cold-launching an activity.
Return | |
---|---|
Int |
Value is android.window.SplashScreen.SPLASH_SCREEN_STYLE_UNDEFINED, android.window.SplashScreen#SPLASH_SCREEN_STYLE_SOLID_COLOR , or android.window.SplashScreen#SPLASH_SCREEN_STYLE_ICON |
See Also
isPendingIntentBackgroundActivityLaunchAllowed
open funisPendingIntentBackgroundActivityLaunchAllowed(): Boolean
Deprecated: use getPendingIntentBackgroundActivityStartMode()
since for apps targeting android.os.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.
isShareIdentityEnabled
open fun isShareIdentityEnabled(): Boolean
Returns whether the launching app has opted-in to sharing its identity with the launched activity.
Return | |
---|---|
Boolean |
true if the launching app has opted-in to sharing its identity |
makeBasic
open static fun makeBasic(): ActivityOptions!
Create a basic ActivityOptions that has no special animation associated with it. Other options can still be set.
makeClipRevealAnimation
open static fun makeClipRevealAnimation(
source: View!,
startX: Int,
startY: Int,
width: Int,
height: Int
): ActivityOptions!
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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
makeCustomAnimation
open static fun makeCustomAnimation(
context: Context!,
enterResId: Int,
exitResId: Int
): ActivityOptions!
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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
makeCustomAnimation
open static fun makeCustomAnimation(
context: Context,
enterResId: Int,
exitResId: Int,
backgroundColor: Int
): ActivityOptions
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. |
Return | |
---|---|
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
open static fun makeLaunchIntoPip(pictureInPictureParams: PictureInPictureParams): ActivityOptions
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 . |
Return | |
---|---|
ActivityOptions |
This value cannot be null . |
makeScaleUpAnimation
open static fun makeScaleUpAnimation(
source: View!,
startX: Int,
startY: Int,
width: Int,
height: Int
): ActivityOptions!
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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
makeSceneTransitionAnimation
open static fun makeSceneTransitionAnimation(
activity: Activity!,
: View!,
: String!
): ActivityOptions!
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 android.view.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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
makeSceneTransitionAnimation
@SafeVarargs open static fun makeSceneTransitionAnimation(
activity: Activity!,
vararg : Pair<View!, String!>!
): ActivityOptions!
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 android.view.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<View!, String!>!: 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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
makeTaskLaunchBehind
open static fun makeTaskLaunchBehind(): ActivityOptions!
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
.
makeThumbnailScaleUpAnimation
open static fun makeThumbnailScaleUpAnimation(
source: View!,
thumbnail: Bitmap!,
startX: Int,
startY: Int
): ActivityOptions!
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. |
Return | |
---|---|
ActivityOptions! |
Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity. |
requestUsageTimeReport
open fun requestUsageTimeReport(receiver: PendingIntent!): Unit
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
open fun setAppVerificationBundle(bundle: Bundle!): ActivityOptions!
Set the Bundle
that is provided to the app installer for additional verification if the call to android.content.Context#startActivity results in an app being installed. This Bundle is not provided to any other app besides the installer.
setLaunchBounds
open fun setLaunchBounds(screenSpacePixelRect: Rect?): ActivityOptions!
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 android.content.pm.PackageManager#FEATURE_FREEFORM_WINDOW_MANAGEMENT
or android.content.pm.PackageManager#FEATURE_PICTURE_IN_PICTURE
enabled.
Parameters | |
---|---|
screenSpacePixelRect |
Rect?: launch bounds or null for fullscreen |
Return | |
---|---|
ActivityOptions! |
this ActivityOptions instance |
setLaunchDisplayId
open fun setLaunchDisplayId(launchDisplayId: Int): ActivityOptions!
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 android.content.pm.PackageManager#FEATURE_ACTIVITIES_ON_SECONDARY_DISPLAYS
.
Parameters | |
---|---|
launchDisplayId |
Int: The id of the display where the activity should be launched. |
Return | |
---|---|
ActivityOptions! |
this ActivityOptions instance. |
setLockTaskEnabled
open fun setLockTaskEnabled(lockTaskMode: Boolean): ActivityOptions!
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 android.app.admin.DevicePolicyManager
can run in LockTask mode. Therefore, if android.app.admin.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 — 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. |
Return | |
---|---|
ActivityOptions! |
this ActivityOptions instance. |
setPendingIntentBackgroundActivityLaunchAllowed
open funsetPendingIntentBackgroundActivityLaunchAllowed(allowed: Boolean): Unit
Deprecated: 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.
setPendingIntentBackgroundActivityStartMode
open fun setPendingIntentBackgroundActivityStartMode(state: Int): ActivityOptions
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,
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.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_ALLOWED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_DENIED , or android.app.ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_COMPAT |
Return | |
---|---|
ActivityOptions |
This value cannot be null . |
setPendingIntentCreatorBackgroundActivityStartMode
open fun setPendingIntentCreatorBackgroundActivityStartMode(mode: Int): ActivityOptions
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.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_SYSTEM_DEFINED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_ALLOWED , android.app.ActivityOptions#MODE_BACKGROUND_ACTIVITY_START_DENIED , or android.app.ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_COMPAT |
Return | |
---|---|
ActivityOptions |
This value cannot be null . |
setShareIdentityEnabled
open fun setShareIdentityEnabled(: Boolean): ActivityOptions
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 android.app.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 |
Return | |
---|---|
ActivityOptions |
this ActivityOptions instance. This value cannot be null . |
setSplashScreenStyle
open fun setSplashScreenStyle(style: Int): ActivityOptions
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, android.window.SplashScreen#SPLASH_SCREEN_STYLE_SOLID_COLOR , or android.window.SplashScreen#SPLASH_SCREEN_STYLE_ICON |
Return | |
---|---|
ActivityOptions |
This value cannot be null . |
toBundle
open fun toBundle(): Bundle!
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.
update
open fun update(otherOptions: ActivityOptions!): Unit
Update the current values in this ActivityOptions from those supplied in otherOptions. Any values defined in otherOptions replace those in the base options.