Element Syntax and Hierarchy

Declare Activity subclasses within the <application> parent element using the following structure:

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:theme="@style/CustomTheme"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="adjustResize">
    
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="org.sample.myapp.ParentActivity" />
</activity>

Permitted child elements include <intent-filter>, <meta-data>, and <layout>. Every Activity utilized by the application requires explicit declaration; undeclared components remain inaccessible to the system.

Identification and Availability

android:name

Specifies the fully qualified class name implementing the Activity. Shorthand notation prefixing with a dot (.DetailActivity) appends the manifest package name. This attribute requires definition before application publication and cannot be altered post-release unless exported is set to false.

android:enabled

Controls system instantiation capabilities. Both application-level and component-level enabled attributes must evaluate to true (default values) for instantiation. Setting either to false prevents Activity creation.

android:exported

Determines cross-application accessibility. When false, only components within the same UID or application may launch the Activity. Intent filters imply external accessibility; therefore, combining filters with exported="false" triggers ActivityNotFoundException for external launch attempts. Absent filters default this attribute to false.

Task Management and Navigation

android:launchMode

Defines Activity instantiation behavior across four distinct modes:

• standard: Default behavior creating new instances per Intent request
• singleTop: Reuses existing top-stack instances via onNewIntent() when available
• singleTask: Establishes new task roots; single instance per task
• singleInstance: Exclusive task ownership prohibiting additional Activities in the same task

Standard and singleTop modes permit multiple instances across any stack position. SingleTask and singleInstance occupy root positions exclusively, restricting themselves to one instance system-wide.

android:taskAffinity

Associates Activities with specific task groups. By default, all application Activities share the package name affinity. Empty strings indicate no affinity assignment. This property influences task selection during FLAG_ACTIVITY_NEW_TASK launches and reparenting operations.

android:allowTaskReparenting

Enables automatic migration to affinity-matched tasks when those tasks regain foreground status. Effective exclusively for standard and singleTop launch modes, as singleTask/singleInstance Activities inherent define task roots.

android:clearTaskOnLaunch

When set to true on root Activities, clearing the task stack upon every relaunch from the home screen, preserving only the root component. Takes precedence over alwaysRetainTaskState.

android:alwaysRetainTaskState

Prevents system-initiated task resets during prolonged background periods (typically 30 minutes). Applicable solely to root Activities, maintaining complete historical stack state across navigation interruptions.

android:parentActivityName

Defines logical parent relationships for action bar navigation and synthetic back stack construction via TaskStackBuilder. Supports API 4-16 through meta-data declarations:

<activity
    android:name="org.sample.myapp.ChildActivity"
    android:parentActivityName="org.sample.myapp.MainActivity">
    <meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="org.sample.myapp.MainActivity" />
</activity>

State Persistence and Lifecycle

android:persistableMode

Controls cross-reboot state retention with three options:

• persistRootOnly: Preserves only root Activity launch Intent (default)
• persistAcrossReboots: Maintains Activity state and stack information through PersistableBundle in onCreate()
• persistNever: Excludes from persistence mechanisms

Root Activity configuration dictates application-wide persistence behavior for persistRootOnly and persistNever values.

android:stateNotNeeded

When true, permits system termination without onSaveInstanceState() invocation, passing null bundles to onCreate(). Suitable for Activities regenerating state independently, such as launch screens.

android:noHistory

Removes the Activity from stack history up on navigation away, preventing return navigation. Eliminates onActivityResult() callbacks when starting other Activities for results.

Window Configuration and Input

android:windowSoftInputMode

Governs soft keyboard visibility and window adjustments through state and adjustment combinations:

State values:

• stateUnspecified, stateUnchanged, stateHidden, stateAlwaysHidden
• stateVisible, stateAlwaysVisible

Adjustment values:

• adjustResize: Shrinks window dimensions accommodating keyboard space
• adjustPan: Translates content without resizing to maintain focus visibility
• adjustUnspecified: System-selected default behavior

Combine values using pipe separators: "stateVisible|adjustResize".

android:screenOrientation

Constrains display orientation with options including:

• portrait, landscape, sensor, fullSensor
• reversePortrait, reverseLandscape (API 9+)
• userPortrait, userLandscape (API 18+)
• locked (API 18+)

Ignored during multi-window operation. Specific orientation declarations enable Play Store filtering for compatible devices.

android:immersive

Locks immersive mode flags in ActivityInfo.flags, overriding runtime setImmersive() modifications when set to true.

Security and Permissions

android:permission

Restricts access requiring specific permission grants for startActivity() or startActivityForResult() invocations. Inherits application-level permission definitions when unspecified.

android:directBootAware

Permits execution during direct boot phases before user credential verification. Limited to device-protected storage access during this state. Defaults to false.

Display and Multi-Window Support

android:resizeableActivity

Enables free-form and split-screen multi-window support (API 24+). Defaults to true for applications targeting API 24+. When false, Activities force full-screen display regardless of windowing mode attempts.

android:maxAspectRatio

Specifies maximum supported aspect ratios (long edge/short edge), triggering letterboxing on wider displays. Minimum values: 1.33 for handheld devices, 1.0 for wearables. Ignored when resizeableActivity is enabled.

android:supportsPictureInPicture

Indicates picture-in-picture capability for video playback Activities. Requires resizeableActivity support for effectiveness (API 24+).

android:colorMode

Requests wide color gamut rendering on compatible hardware (API 26+), enabling display outputs beyond sRGB color spaces for enhanced visual fidelity.

Process and Performance

android:process

Assigns execution processes. Colon-prefix (:remote) creates application-private processes; lowercase initials indicate shared global processes requiring appropriate permissions. Defaults to application package process.

android:multiprocess

Allows instantiation with in calling component processes rather than standard application processes. Defaults to false.

android:hardwareAccelerated

Enables OpenGL hardware rendering for 2D graphics operations, improving animation and scrolling performance at increased memory cost (API 11+). Requires testing for compatibility with custom drawing operations.

Specialized Behaviors

android:documentLaunchMode

Manages document-centric task creation in the overview screen:

• intoExisting: Reuses matching Intent/URI tasks via onNewIntent()
• always: Creates new tasks per document launch
• none: Standard task management (default)
• never: Prevents new document tasks regardless of Intent flags

Requires launchMode="standard" for non-default values.

android:configChanges

Prevents Activity restart during configuration shifts, routing changes to onConfigurationChanged() instead. Accepts bitmask values including orientation, screenSize, keyboardHidden, locale, uiMode, density (API 24+), and layoutDirection (API 17+).

android:relinquishTaskIdentity

When true on root Activities, replaces task base Intent with subsequent Activity Intents in the overview screen, enabling dynamic task labeling and iconography via ActivityManager.TaskDescription.

android:lockTaskMode

Controls kiosk-mode presentation (API 23+):

• normal: Standard operation
• if_whitelisted: Conditional locked task based on DPC authorization
• always: Permanent locked task (system apps only)
• never: Prevents pinning (system apps only)

android:excludeFromRecents

Hides task representation from the overview screen when set to true on root Activities.

android:autoRemoveFromRecents

Automatically eliminates tasks from the overview screen upon completion of all contained Activities.

android:maxRecents

Limits task instances retained in the overview screen (1-50, default 16).

android:showForAllUsers

Displays Activity across user profiles regardless of launching user identity (API 23+).

Visual Assets

android:theme

References style resources defining Activity appearance, inherited from application theme when unspecified.

android:icon

Specifies drawable resources for Activity representation in launchers and task lists. Defaults to application icon.

android:banner

Provides wide-format drawable resources for Android TV main screen representation. Required for Leanback launcher categories.

android:label

Defines user-readable Activity titles, supporting localization via string resource references.

android:uiOptions

Supplementary interface configurations:

• splitActionBarWhenNarrow: Divides action bar between top navigation and bottom action items on narrow displays (API 14+)