Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality

ActivityOptionsCompat

open class ActivityOptionsCompat
kotlin.Any
   ↳ androidx.core.app.ActivityOptionsCompat

Helper for accessing features in android.app.ActivityOptions in a backwards compatible fashion.

Summary

Constants
static String

A long in the extras delivered by requestUsageTimeReport that contains the total time (in ms) the user spent in the app flow.
static 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).

Protected constructors

Public methods
open Rect?

Returns the bounds that should be used to launch the activity.
open static ActivityOptionsCompat

Create a basic ActivityOptions that has no special animation associated with it.
open static ActivityOptionsCompat
makeClipRevealAnimation(@NonNull source: View, startX: Int, startY: Int, width: Int, height: Int)

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 ActivityOptionsCompat
makeCustomAnimation(@NonNull context: Context, enterResId: Int, exitResId: Int)

Create an ActivityOptions specifying a custom animation to run when the activity is displayed.
open static ActivityOptionsCompat
makeScaleUpAnimation(@NonNull source: View, startX: Int, startY: Int, startWidth: Int, startHeight: Int)

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 ActivityOptionsCompat
makeSceneTransitionAnimation(@NonNull activity: Activity, @NonNull sharedElement: View, @NonNull sharedElementName: String)

Create an ActivityOptions to transition between Activities using cross-Activity scene animations.
open static ActivityOptionsCompat
makeSceneTransitionAnimation(@NonNull activity: Activity, vararg sharedElements: Pair<View!, String!>!)

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

If set along with Intent.
open static ActivityOptionsCompat
makeThumbnailScaleUpAnimation(@NonNull source: View, @NonNull 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

Ask the the system track that time the user spends in the app being launched, and report it back once done.
open ActivityOptionsCompat
setLaunchBounds(@Nullable screenSpacePixelRect: Rect?)

Sets the bounds (window size) that the activity should be launched in.
open Bundle?

Returns the created options as a Bundle, which can be passed to androidx.core.content.ContextCompat#startActivity(Context, android.content.Intent, Bundle).
open Unit
update(@NonNull otherOptions: ActivityOptionsCompat)

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"

Protected constructors

<init>

protected ActivityOptionsCompat()

Public methods

getLaunchBounds

@Nullable open fun getLaunchBounds(): Rect?

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

Return
Rect?: Bounds used to launch the activity.

makeBasic

@NonNull open static fun makeBasic(): ActivityOptionsCompat

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

makeClipRevealAnimation

@NonNull open static fun makeClipRevealAnimation(@NonNull source: View, startX: Int, startY: Int, width: Int, height: Int): ActivityOptionsCompat

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 View: The x starting location of the new activity, relative to source.
startY View: The y starting location of the activity, relative to source.
width View: The initial width of the new activity.
height View: The initial height of the new activity.
Return
ActivityOptionsCompat: Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeCustomAnimation

@NonNull open static fun makeCustomAnimation(@NonNull context: Context, enterResId: Int, exitResId: Int): ActivityOptionsCompat

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 Context: A resource ID of the animation resource to use for the incoming activity. Use 0 for no animation.
exitResId Context: A resource ID of the animation resource to use for the outgoing activity. Use 0 for no animation.
Return
ActivityOptionsCompat: Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeScaleUpAnimation

@NonNull open static fun makeScaleUpAnimation(@NonNull source: View, startX: Int, startY: Int, startWidth: Int, startHeight: Int): ActivityOptionsCompat

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 android.content.Intent#setSourceBounds(android.graphics.Rect), 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 View: The x starting location of the new activity, relative to source.
startY View: The y starting location of the activity, relative to source.
startWidth View: The initial width of the new activity.
startHeight View: The initial height of the new activity.
Return
ActivityOptionsCompat: Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeSceneTransitionAnimation

@NonNull open static fun makeSceneTransitionAnimation(@NonNull activity: Activity, @NonNull sharedElement: View, @NonNull sharedElementName: String): ActivityOptionsCompat

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_CONTENT_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 Activity: The View to transition to the started Activity. sharedElement must have a non-null sharedElementName.
sharedElementName Activity: The shared element name as used in the target Activity. This may be null if it has the same name as sharedElement.
Return
ActivityOptionsCompat: Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeSceneTransitionAnimation

@NonNull open static fun makeSceneTransitionAnimation(@NonNull activity: Activity, vararg sharedElements: Pair<View!, String!>!): ActivityOptionsCompat

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_CONTENT_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 Activity: 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
ActivityOptionsCompat: Returns a new ActivityOptions object that you can use to supply these options as the options Bundle when starting an activity.

makeTaskLaunchBehind

@NonNull open static fun makeTaskLaunchBehind(): ActivityOptionsCompat

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

@NonNull open static fun makeThumbnailScaleUpAnimation(@NonNull source: View, @NonNull thumbnail: Bitmap, startX: Int, startY: Int): ActivityOptionsCompat

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 android.content.Intent#setSourceBounds(android.graphics.Rect), 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 View: The bitmap that will be shown as the initial thumbnail of the animation.
startX View: The x starting location of the bitmap, relative to source.
startY View: The y starting location of the bitmap, relative to source.
Return
ActivityOptionsCompat: 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(@NonNull receiver: PendingIntent): Unit

Ask the 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 will receive the report.

setLaunchBounds

@NonNull open fun setLaunchBounds(@Nullable screenSpacePixelRect: Rect?): ActivityOptionsCompat

Sets the bounds (window size) that the activity should be launched in. Rect position should be provided in pixels and in screen coordinates. Set to null explicitly for 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 to use for the activity or null for fullscreen.

toBundle

@Nullable open fun toBundle(): Bundle?

Returns the created options as a Bundle, which can be passed to androidx.core.content.ContextCompat#startActivity(Context, android.content.Intent, Bundle). 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(@NonNull otherOptions: ActivityOptionsCompat): Unit

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