<activity>

Indicates that the activity can be launched as the embedded child of another activity, particularly in the case where the child lives in a container, such as a Display owned by another activity. For example, activities that are used for Wear custom notifications declare this so Wear can display the activity in its context stream, which resides in another process.

The default value of this attribute is false.

If this attribute isn't set, the value set by the corresponding allowTaskReparenting attribute of the <application> element applies to the activity. The default value is "false".

Normally, when an activity is started it's associated with the task of the activity that started it and it stays there for its entire lifetime. You can use this attribute to force it to be re-parented to the task it has an affinity for when its current task is no longer displayed. Typically, this is used to cause the activities of an application to move to the main task associated with that application.

For example, if an email message contains a link to a web page, clicking the link brings up an activity that can display the page. That activity is defined by the browser application but is launched as part of the email task. If it's reparented to the browser task, it shows when the browser next comes to the front and is absent when the email task again comes forward.

The affinity of an activity is defined by the taskAffinity attribute. The affinity of a task is determined by reading the affinity of its root activity. Therefore, by definition, a root activity is always in a task with the same affinity. Since activities with "singleTask" or "singleInstance" launch modes can only be at the root of a task, re-parenting is limited to the "standard" and "singleTop" modes. (See also the launchMode attribute.)

Normally, the system clears a task, removing all activities from the stack above the root activity, in certain situations when the user re-selects that task from the home screen. Typically, this is done if the user hasn't visited the task for a certain amount of time, such as 30 minutes.

However, when this attribute is "true", users always return to the task in its last state, regardless of how they get there. This is useful in an application like a web browser where there is a lot of state, such as multiple open tabs, that users don't want to lose.

The system uses the banner to represent an app in the Android TV home screen. Since the banner displays only in the home screen, it is only specified by applications with an activity that handles the CATEGORY_LEANBACK_LAUNCHER intent.

This attribute is set as a reference to a drawable resource containing the image, such as "@drawable/banner". There is no default banner.

For more information, see Provide a home screen banner in Get Started with TV Apps.

Indicates whether the activity can be displayed on a remote device which may or may not be running Android. It must be a boolean value, either "true" or "false".

The default value of this attribute is "true".

When the value is "true", every time users start the task, they are brought to its root activity regardless of what they were last doing in the task and regardless of whether they used the Back or Home button to leave it. When the value is "false", the task can be cleared of activities in some situations, but not always. For more information, see the alwaysRetainTaskState attribute.

Suppose the user launches activity P from the home screen, and from there goes to activity Q. The user next taps Home, and then returns to activity P. Normally, the user sees activity Q, since that is what they were last doing in P's task. However, if P set this flag to "true", all of the activities on top of it—in this case, Q—are removed when the user launches activity P from the home screen. So, the user sees only P when returning to the task.

If this attribute and allowTaskReparenting are both "true", any activities that can be re-parented are moved to the task they share an affinity with. The remaining activities are then dropped.

This attribute is ignored if FLAG_ACTIVITY_RESET_TASK_IF_NEEDED isn't set.

Specifies the activity's color mode. If specified, can be either hdr or wideColorGamut.

If hdr, requests that the activity be displayed in a high dynamic range if the device supports it.

If wideColorGamut, requests that the activity be displayed in wide color gamut mode on compatible devices. In wide color gamut mode, a window can render outside of the SRGB gamut to display more vibrant colors. If the device doesn't support wide color gamut rendering, this attribute has no effect. For more information about rendering in wide color mode, see Enhance graphics with wide color content.

Note: Use this attribute only in special cases to improve application performance and responsiveness. For more information, see Handle configuration changes.

The following strings are valid values for this attribute. Multiple values are separated by |, such as "locale|navigation|orientation".

All these configuration changes can impact the resource values seen by the application. Therefore, when onConfigurationChanged() is called, it is usually necessary to again retrieve all resources, including view layouts and drawables, to correctly handle the change.

Note: To handle multi-window related configuration changes, use both "screenLayout" and "smallestScreenSize". Multi-window is supported in Android 7.0 (API level 24) or higher.

Whether the activity is Direct-Boot aware—that is, whether it can run before the user unlocks the device.

Note: During Direct Boot, an activity in your application can only access the data that is stored in device protected storage.

The default value is "false".

This attribute has four values, which produce the following effects when the user opens a document with the application:

Note: For values other than "none" and "never", the activity is defined with launchMode="standard". If this attribute isn't specified, documentLaunchMode="none" is used.

The <application> element has its own enabled attribute that applies to all application components, including activities. The <application> and <activity> attributes must both be "true", as they both are by default, for the system to be able to instantiate the activity. If either is "false", it can't be instantiated.

Setting android:enableOnBackInvokedCallback=false turns off predictive back animations either at the activity level or at the app level, depending on where you set the tag, and instructs the system to ignore calls to the OnBackInvokedCallback platform API.

Whether the task initiated by this activity is excluded from the Recents screen. That is, when this activity is the root activity of a new task, this attribute determines whether the task appears in the list of recent apps. It's "true" if the task is excluded from the list; "false" if it is included. The default value is "false".

Whether the activity can be launched by components of other applications:

• If "true", the activity is accessible to any app, and is launchable by its exact class name.
• If "false", the activity can be launched only by components of the same application, applications with the same user ID, or privileged system components. This is the default value when there are no intent filters.

If an activity in your app includes intent filters, set this element to "true" to let other apps start it. For example, if the activity is the main activity of the app and includes the category android.intent.category.LAUNCHER.

If this element is set to "false" and an app tries to start the activity, the system throws an ActivityNotFoundException.

This attribute isn't the only way to limit an activity's exposure to other applications. Permissions are also used to limit the external entities that can invoke the activity. See the permission attribute.

If this attribute and allowTaskReparenting are both "true", this attribute trumps the other. The affinity of the activity is ignored. The activity isn't re-parented, but destroyed.

This attribute is ignored if FLAG_ACTIVITY_RESET_TASK_IF_NEEDED isn't set.

On Android 3.0 and higher, a hardware-accelerated OpenGL renderer is available to applications to improve performance for many common 2D graphics operations. When the hardware-accelerated renderer is enabled, most operations in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated.

This results in smoother animations, smoother scrolling, and improved responsiveness overall, even for applications that don't explicitly make use the framework's OpenGL libraries. Because of the increased resources required to enable hardware acceleration, your app consumes more RAM.

Not all of the OpenGL 2D operations are accelerated. If you enable the hardware-accelerated renderer, test whether your application can use the renderer without errors.

An icon representing the activity. The icon is displayed to users when a representation of the activity is required on-screen. For example, icons for activities that initiate tasks are displayed in the launcher window. The icon is often accompanied by a label; for information about the label, see the android:label attribute.

This attribute is set as a reference to a drawable resource containing the image definition. If it isn't set, the icon specified for the application as a whole is used instead. For more information, see the <application> element's icon attribute.

The activity's icon, whether set here or by the <application> element, is also the default icon for all the activity's intent filters. For more information, see the <intent-filter> element's icon attribute.

A user-readable label for the activity. The label displays on-screen when the activity is represented to the user. It's often displayed along with the activity icon. If this attribute isn't set, the label set for the application as a whole is used instead. see the <application> element's label attribute.

The activity's label, whether set here or by the <application> element, is also the default label for all the activity's intent filters. For more information, see the <intent-filter> element's label attribute.

The label is set as a reference to a string resource so that it can be localized like other strings in the user interface. However, as a convenience while you're developing the application, it can also be set as a raw string.

An instruction for how the activity launches. There are five modes, which work in conjunction with activity flags (FLAG_ACTIVITY_* constants) in Intent objects to determine what happens when the activity is called upon to handle an intent:

"standard"
"singleTop"
"singleTask"
"singleInstance"
"singleInstancePerTask"

The default mode is "standard".

As shown in the following table, the modes fall into two main groups, with "standard" and "singleTop" activities on one side, and "singleTask", "singleInstance", and "singleInstancePerTask" activities on the other. An activity with the "standard" or "singleTop" launch mode can be instantiated multiple times.

The instances can belong to any task and can be located anywhere in the activity task. Typically, they're launched into the task that called startActivity(), unless the Intent object contains a FLAG_ACTIVITY_NEW_TASK instruction, in which case a different task is chosen. For more information, see the taskAffinity attribute.

In contrast, "singleTask", "singleInstance", and "singleInstancePerTask" activities have different behaviors. "singleInstancePerTask" is always at the root of the activity task. Also, the device can hold only one instance of the "singleInstance" activity at a time, while the "singleInstancePerTask activity can be instantiated multiple times in different tasks when FLAG_ACTIVITY_MULTIPLE_TASK or FLAG_ACTIVITY_NEW_DOCUMENT is set.

An activity with the "singleTask" launch mode combines the behaviors of "singleInstance" and "singleInstancePerTask": the activity can be instantiated multiple times and can be located anywhere in a task of the same taskAffinity. But the device can only hold one task for locating the "singleTask" activity at the root of the activity task.

The "standard" and "singleTop" modes differ from each other in one respect: every time there's a new intent for a "standard" activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. Similarly, a new instance of a "singleTop" activity can also be created to handle a new intent.

However, if the target task already has an existing instance of the activity at the top of its stack, that instance receives the new intent, in an onNewIntent() call. A new instance isn't created. Otherwise—if an existing instance of the "singleTop" activity is in the target task but not at the top of the stack, or if it's at the top of a stack, but not in the target task—a new instance is created and pushed on the stack.

Similarly, if the user navigates up to an activity on the current stack, the behavior is determined by the parent activity's launch mode. If the parent activity has launch mode singleTop (or the up intent contains FLAG_ACTIVITY_CLEAR_TOP), the parent is brought to the top of the stack, and its state is preserved.

The navigation intent is received by the parent activity's onNewIntent() method. If the parent activity has launch mode standard, and the up intent doesn't contain FLAG_ACTIVITY_CLEAR_TOP, the current activity and its parent both pop off the stack, and a new instance of the parent activity is created to receive the navigation intent.

The "singleInstance" mode also differs from "singleTask" and "singleInstancePerTask" in only one respect: an activity with the "singleTask" or "singleInstancePerTask" launch mode lets other activities, necessarily "standard" and "singleTop" activities, be part of its task.

A "singleInstance" activity, on the other hand, permits no other activities to be part of its task. It must be the only activity in the task. If it starts another activity, that activity is assigned to a different task, as if FLAG_ACTIVITY_NEW_TASK were in the intent.

As shown in the preceding table, "standard" is the default mode and is appropriate for most types of activities. "singleTop" is also a common and useful launch mode for many types of activities. The other modes, "singleTask" , "singleInstance", and "singleInstancePerTask", are not appropriate for most applications. They result in an interaction model that is likely to be unfamiliar to users and is very different from most other applications.

Regardless of the launch mode that you choose, make sure to test the usability of the activity during launch and when navigating back to it from other activities and tasks using the Back button.

For more information about launch modes and their interaction with Intent flags, see Tasks and the back stack.

Android can run tasks in an immersive, kiosk-like fashion called lock task mode. When the system runs in lock task mode, device users typically can't see notifications, access non-allowlisted apps, or return to the home screen, unless the Home app is allowlisted.

Only apps that are allowlisted by a device policy controller (DPC) can run when the system is in lock task mode. System and privileged apps, however, can run in lock task mode without being allowlisted.

The value can be any one of the following R.attr.lockTaskMode string values:

This attribute was introduced in API level 23.

The maximum aspect ratio the activity supports. If the app runs on a device with a wider aspect ratio, the system automatically letterboxes the app, leaving portions of the screen unused so the app can run at its specified maximum aspect ratio.

Maximum aspect ratio is expressed as the decimal form of the quotient of the device's longer dimension divided by its shorter dimension. For example, if the maximum aspect ratio is 7:3, set the value of this attribute to 2.33.

On non-wearable devices, the value of this attribute needs to be 1.33 or greater. On wearable devices, it must be 1.0 or greater. Otherwise, the system ignores the set value.

Note: This attribute is ignored if the activity has resizeableActivity set to true, since that means your activity supports any size.

For more information about this attribute, see Declare a maximum aspect ratio.

Normally, a new instance of an activity is launched into the process of the application that defined it, so all instances of the activity run in the same process. However, if this flag is set to "true", instances of the activity can run in multiple processes, letting the system create instances wherever they are used, provided permissions let it—something that is almost never necessary or desirable.

Once you publish your application, don't change this name, unless you set android:exported="false". There is no default. The name must be specified.

A value of "true" means that the activity doesn't leave a historical trace. It doesn't remain in the activity stack for the task, so the user isn't able to return to it. In this case, onActivityResult() is never called if you start another activity for a result from this activity.

This attribute was introduced in API level 3.

The system reads this attribute to determine which activity to start when the user taps the Up button in the action bar. The system can also use this information to synthesize a back stack of activities with TaskStackBuilder.

To support API levels 4 - 16, you can also declare the parent activity with a <meta-data> element that specifies a value for "android.support.PARENT_ACTIVITY":

<activity
    android:name="com.example.app.ChildActivity"
    android:label="@string/title_child_activity"
    android:parentActivityName="com.example.app.MainActivity" >
    <!-- Parent activity meta-data to support API level 4+ -->
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="com.example.app.MainActivity" />
</activity>

For more information about declaring the parent activity to support Up navigation, read Providing Up Navigation.

This attribute was introduced in API level 16.

Defines how an instance of an activity is preserved within a containing task across device restarts.

If the root activity of a task sets this attribute's value to persistRootOnly, then only the root activity is preserved. Otherwise, the activities that are higher up the task's back stack are examined; any of these activities that set this attribute's value to persistAcrossReboots are preserved.

If you use this attribute, you must set its value to one of the following:

This attribute was introduced in API level 21.

If this attribute isn't set, the permission set by the <application> element's permission attribute applies to the activity. If neither attribute is set, the activity isn't protected by a permission.

For more information on permissions, see the Permissions section of the App manifest overview and Security tips.

The name of the process in which the activity runs. Normally, all components of an application run in a default process name created for the application, and you don't need to use this attribute. But if necessary, you can override the default process name with this attribute, letting you spread your app components across multiple processes.

If the name assigned to this attribute begins with a colon (:), a new process, private to the application, is created when it's needed and the activity runs in that process.

If the process name begins with a lowercase character, the activity runs in a global process of that name, provided that it has permission to do so. This lets components in different applications share a process, reducing resource usage.

The <application> element's process attribute can set a different default process name for all components.

Whether the activity relinquishes its task identifiers to an activity above it in the task stack. A task whose root activity has this attribute set to "true" replaces the base Intent with that of the next activity in the task.

If the next activity also has this attribute set to "true" then it yields the base Intent to any activity that it launches in the same task. This continues for each activity until an activity is encountered which has this attribute set to "false". The default value is "false".

This attribute set to "true" also permits the activity's use of the ActivityManager.TaskDescription to change labels, colors, and icons in the Recents screen.

Specifies permissions necessary to launch this activity when passing content URIs. The default value is none, meaning no specific permissions are required. Setting this attribute restricts activity invocation based on the invoker's permissions. If the invoker doesn't have the required permissions, the activity start will be denied via a SecurityException .

Note that the enforcement works for content URIs inside Intent.getData(), Intent.EXTRA_STREAM, and Intent.getClipData().

May be a string value, using '\\;' to escape characters such as '\\n' or '\\uxxxx' for a unicode character;

Must be one of the following constant values.

Specifies whether the app supports multi-window mode. You can set this attribute in either the <activity> or <application> element.

If you set this attribute to "true", the user can launch the activity in split-screen and free-form modes. If you set the attribute to "false", the app can't be tested or optimized for a multi-window environment. The system can still put the activity in multi-window mode with compatibility mode applied.

Setting this attribute to "false" doesn't guarantee that there are no other apps in multi-window mode visible on screen, such as in a picture-in-picture, or on other displays. Therefore, setting this flag doesn't mean that your app has exclusive resource access.

If your app targets API level 24 or higher and you do not specify a value for this attribute, the attribute's value defaults to "true".

If your app targets API level 31 or higher, this attribute works differently on small and large screens:

• Large screens (sw >= 600dp): all apps support multi-window mode. The attribute indicates whether an app can be resized, not whether the app supports multi-window mode. If resizeableActivity="false", the app is put into compatibility mode when necessary to conform to display dimensions.
• Small screens (sw < 600dp): if resizeableActivity="true" and the minimum width and minimum height of the activity are within the multi-window requirements, the app supports multi-window mode. If resizeableActivity="false", the app doesn't support multi-window mode regardless of the activity minimum width and height.

Note: Device manufacturers can override the API level 31 behavior.

This attribute was added in API level 24.

Note: A task's root activity value is applied to all additional activities launched in the task. That is, if the root activity of a task is resizable, then the system treats all other activities in the task as resizable. If the root activity isn't resizable, the other activities in the task aren't resizable.

The requested orientation of the activity.

When an activity fills the entire screen, the requested orientation acts as a suggestion to change the orientation on that screen to match the requested value. This can result in an orientation that differs from the screen's physical orientation in space, requiring the user to rotate the device to continue using the app. On Android 12 (API level 31) and higher, device manufacturers can configure individual device screens (such as the tablet-sized screen of a foldable) to ignore this suggestion, and instead force an activity to be letterboxed within the user's preferred orientation of the device. This results in the activity's orientation matching the requested one without needing the user to physically rotate their device.

In multi-window mode, the requested orientation does not act as a suggestion for the overall orientation. If the activity is letterboxed, the requested orientation impacts the letterboxing applied to the activity.

The value can be any one of the following strings:

Note: When you declare one of the landscape or portrait values, it is considered a hard requirement for the orientation in which the activity runs. The value you declare enables filtering by services such as Google Play, so your application is available only to devices that support the orientation required by your activities. For example, if you declare either "landscape", "reverseLandscape", or "sensorLandscape", then your application is available only to devices that support landscape orientation.

Also explicitly declare that your application requires either portrait or landscape orientation with the <uses-feature> Element, such as <uses-feature android:name="android.hardware.screen.portrait"/>. This is a filtering behavior provided by Google Play and other services that support it, and the platform itself doesn't control whether your app can install when a device supports only certain orientations.

Whether the activity is shown when the device's current user is different than the user who launched the activity. You can set this attribute to a literal value, like "true" or "false", or you can set the attribute to a resource or theme attribute that contains a boolean value.

This attribute was added in API level 23.

Normally, before an activity is temporarily shut down to save resources, its onSaveInstanceState() method is called. This method stores the current state of the activity in a Bundle object, which is then passed to onCreate() when the activity is restarted. If this attribute is set to "true", onSaveInstanceState() might not be called, and onCreate() is passed null instead of the Bundle, as it is when the activity starts for the first time.

A "true" setting means that the activity can be restarted without retained state. For example, the activity that displays the Home screen uses this setting to make sure that it doesn't get removed if it crashes for some reason.

Specifies whether the activity supports picture-in-picture display.

The task that the activity has an affinity for. Activities with the same affinity conceptually belong to the same task, to the same "application" from the user's perspective. The affinity of a task is determined by the affinity of its root activity.

The affinity determines two things: the task that the activity is re-parented to (see the allowTaskReparenting attribute) and the task that houses the activity when it launches with the FLAG_ACTIVITY_NEW_TASK flag.

By default, all activities in an application have the same affinity. You can set this attribute to group them differently, and even place activities defined in different applications within the same task. To specify that the activity doesn't have an affinity for any task, set it to an empty string.

If this attribute isn't set, the activity inherits the affinity set for the application. See the <application> element's taskAffinity attribute. The name of the default affinity for an application is the namespace set in the build.gradle file.

If this attribute isn't set, the activity inherits the theme set for the application as a whole, from the <application> element's theme attribute. If that attribute is also not set, the default system theme is used. For more information, see Styles and themes.

Extra options for an activity's UI. Must be one of the following values.

For more information about the app bar, see Add the app bar.

This attribute was added in API level 14.

• Whether the soft keyboard is hidden or visible when the activity becomes the focus of user attention.
• Whether the activity's main window is resized smaller to make room for the soft keyboard or its contents pan to make the current focus visible when part of the window is covered by the soft keyboard.

The setting must be one of the values listed in the following table or a combination of one "state..." value plus one "adjust..." value. Setting multiple values in either group, such as multiple "state..." values, has undefined results. Individual values are separated by a vertical bar (|), as shown in the following example:

<activity android:windowSoftInputMode="stateVisible|adjustResize" ... >

Values set here (other than "stateUnspecified" and "adjustUnspecified") override values set in the theme.

This attribute was introduced in API level 3.