xref: /frameworks/base/docs/html/guide/topics/manifest/activity-element.jd

page.title=<activity>
parent.title=The AndroidManifest.xml File
parent.link=manifest-intro.html
@jd:body

<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx">&lt;activity android:<a href="#embedded">allowEmbedded</a>=["true" | "false"]
          android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"]
          android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"]
          android:<a href="#autoremrecents">autoRemoveFromRecents</a>=["true" | "false"]
          android:<a href="#banner">banner</a>="<i>drawable resource</i>"
          android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"]
          android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale",
                                 "touchscreen", "keyboard", "keyboardHidden",
                                 "navigation", "screenLayout", "fontScale",
                                 "uiMode", "orientation", "screenSize",
                                 "smallestScreenSize"]
          android:<a href="#dlmode">documentLaunchMode</a>=["intoExisting" | "always" |
                                  "none" | "never"]
          android:<a href="#enabled">enabled</a>=["true" | "false"]
          android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"]
          android:<a href="#exported">exported</a>=["true" | "false"]
          android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"]
          android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"]
          android:<a href="#icon">icon</a>="<i>drawable resource</i>"
          android:<a href="#label">label</a>="<i>string resource</i>"
          android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" |
                              "singleTask" | "singleInstance"]
          android:<a href="#maxRecents">maxRecents</a>="<i>integer</i>"
          android:<a href="#multi">multiprocess</a>=["true" | "false"]
          android:<a href="#nm">name</a>="<i>string</i>"
          android:<a href="#nohist">noHistory</a>=["true" | "false"]  <!-- ##api level 3## -->
          android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 -->
          android:<a href="#prmsn">permission</a>="<i>string</i>"
          android:<a href="#proc">process</a>="<i>string</i>"
          android:<a href="#relinquish">relinquishTaskIdentity</a>=["true" | "false"]
          android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" |
                                     "landscape" | "portrait" |
                                     "reverseLandscape" | "reversePortrait" |
                                     "sensorLandscape" | "sensorPortrait" |
                                     "userLandscape" | "userPortrait" |
                                     "sensor" | "fullSensor" | "nosensor" |
                                     "user" | "fullUser" | "locked"]
          android:<a href="#state">stateNotNeeded</a>=["true" | "false"]
          android:<a href="#aff">taskAffinity</a>="<i>string</i>"
          android:<a href="#theme">theme</a>="<i>resource or theme</i>"
          android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"]
          android:<a href="#wsoft">windowSoftInputMode</a>=["stateUnspecified",
                                       "stateUnchanged", "stateHidden",
                                       "stateAlwaysHidden", "stateVisible",
                                       "stateAlwaysVisible", "adjustUnspecified",
                                       "adjustResize", "adjustPan"] &gt;   <!-- ##api level 3## -->
    . . .
&lt;/activity&gt;</pre></dd>

<dt>contained in:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code></dd>

<dt>can contain:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code></dd>

<dt>description:</dt>
<dd itemprop="description">Declares an activity (an {@link android.app.Activity} subclass) that
implements part of the application's visual user interface.  All activities
must be represented by {@code <activity>}
elements in the manifest file.  Any that are not declared there will not be seen
by the system and will never be run.

<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="embedded"></a>{@code android:allowEmbedded}</dt>
<dd>
    Indicate 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 must declare this so
    Wear can display the activity in it's context stream, which resides
    in another process.

    <p>The default value of this attribute is <code>false</code>.
</dd>
<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt>
<dd>Whether or not the activity can move from the task that started it to
the task it has an affinity for when that task is next brought to the
front &mdash; "{@code true}" if it can move, and "{@code false}" if it
must remain with the task where it started.

<p>
If this attribute is not set, the value set by the corresponding
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code>
attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element
applies to the activity.  The default value is "{@code false}".
</p>

<p>
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, it's used to cause the activities of an application to move
to the main task associated with that application.
</p>

<p>
For example, if an e-mail 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 e-mail
task.  If it's reparented to the browser task, it will be shown when the
browser next comes to the front, and will be absent when the e-mail task
again comes forward.
</p>

<p>
The affinity of an activity is defined by the
<code><a href="#aff">taskAffinity</a></code> 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 "{@code singleTask}" or
"{@code singleInstance}" launch modes can only be at the root of a task,
re-parenting is limited to the "{@code standard}" and "{@code singleTop}"
modes.  (See also the <code><a href="#lmode">launchMode</a></code>
attribute.)
</p></dd>

<dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt>
<dd>Whether or not the state of the task that the activity is in will always
be maintained by the system &mdash; "{@code true}" if it will be, and
"{@code false}" if the system is allowed to reset the task to its initial
state in certain situations.  The default value is "{@code false}".  This
attribute is meaningful only for the root activity of a task; it's ignored
for all other activities.

<p>
Normally, the system clears a task (removes 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.
</p>

<p>
However, when this attribute is "{@code true}", users will always return
to the task in its last state, regardless of how they get there.  This is
useful, for example, in an application like the web browser where there is
a lot of state (such as multiple open tabs) that users would not like to lose.
</p></dd>

<dt><a name="autoremrecents"></a>{@code android:autoRemoveFromRecents}</dt>
<dd>Whether or not tasks launched by activities with this attribute remains in the
<a href="{@docRoot}guide/components/recents.html">overview screen</a> until the last activity in the
task is completed. If {@code true}, the task is
automatically removed from the overview screen. This overrides the caller's use of
{@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS}. It must be a boolean value, either
"{@code true}" or "{@code false}".</dd>


<dt><a name="banner"></a>{@code android:banner}</dt>
<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a>
providing an extended graphical banner for its associated item. Use with the
{@code <activity>} tag to supply a default banner for a specific activity, or with the
<a href="{@docRoot}guide/topics/manifest/application-element.html"><code>&lt;application&gt;</code></a>
tag to supply a banner for all application activities.

<p>The system uses the banner to represent an app in
the Android TV home screen. Since the banner is displayed only in the home screen, it
should only be specified by applications with an activity that handles the
{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p>

<p>This attribute must be set as a reference to a drawable resource containing
the image (for example {@code "@drawable/banner"}). There is no default banner.
</p>

<p>
See <a href="{@docRoot}design/tv/patterns.html#banner">
Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner">
Provide a home screen banner</a> in Get Started with TV Apps for more information.
</p></dd>


<dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt>
<dd>Whether or not all activities will be removed from the task, except for
the root activity, whenever it is re-launched from the home screen &mdash;
"{@code true}" if the task is always stripped down to its root activity, and
"{@code false}" if not.  The default value is "{@code false}".  This attribute
is meaningful only for activities that start a new task (the root activity);
it's ignored for all other activities in the task.

<p>
When the value is "{@code true}", every time users start the task again, they
are brought to its root activity regardless of what they were last doing in
the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to
leave it. When the value is "{@code false}", the task may be cleared of activities in
some situations (see the
<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always.
</p>

<p>
Suppose, for example, that someone launches activity P from the home screen,
and from there goes to activity Q.  The user next presses <em>Home</em>, and then returns
to activity P.  Normally, the user would see activity Q, since that is what they
were last doing in P's task.  However, if P set this flag to "{@code true}", all
of the activities on top of it (Q in this case) were removed when the user pressed
<em>Home</em> and the task went to the background.  So the user sees only P when returning
to the task.
</p>

<p>
If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code>
are both "{@code true}", any activities that can be re-parented are moved to
the task they share an affinity with; the remaining activities are then dropped,
as described above.
</p></dd>

<dt><a name="config"></a>{@code android:configChanges}</dt>
<dd>Lists configuration changes that the activity will handle itself.  When a configuration
change occurs at runtime, the activity is shut down and restarted by default, but declaring a
configuration with this attribute will prevent the activity from being restarted. Instead, the
activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged(android.content.res.Configuration)
onConfigurationChanged()}</code> method is called.

<p class="note"><strong>Note:</strong> Using this attribute should be
avoided and used only as a last resort. Please read <a
href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more
information about how to properly handle a restart due to a configuration change.</p>

<p>
Any or all of the following strings are valid values for this attribute. Multiple values are
separated by '{@code |}' &mdash; for example, "{@code locale|navigation|orientation}".
</p>

<table>
<tr>
   <th>Value</th>
   <th>Description</th>
</tr><tr>
   <td>"{@code mcc}"</td>
   <td>The IMSI mobile country code (MCC) has changed &mdash;
       a SIM has been detected and updated the MCC.</td>
</tr><tr>
   <td>"{@code mnc}"</td>
   <td>The IMSI mobile network code (MNC) has changed &mdash;
       a SIM has been detected and updated the MNC.</td>
</tr><tr>
   <td>"{@code locale}"</td>
   <td>The locale has changed &mdash; the user has selected a new
       language that text should be displayed in.</td>
</tr><tr>
   <td>"{@code touchscreen}"</td>
   <td>The touchscreen has changed.  (This should never normally happen.)</td>
</tr><tr>
   <td>"{@code keyboard}"</td>
   <td>The keyboard type has changed &mdash; for example, the user has
       plugged in an external keyboard.</td>
</tr><tr>
   <td>"{@code keyboardHidden}"</td>
   <td>The keyboard accessibility has changed &mdash; for example, the
       user has revealed the hardware keyboard.</td>
</tr><tr>
   <td>"{@code navigation}"</td>
   <td>The navigation type (trackball/dpad) has changed.  (This should never normally happen.)</td>
</tr><tr>
   <td>"{@code screenLayout}"</td>
   <td>The screen layout has changed &mdash; this might be caused by a
             different display being activated.</td>
 </tr><tr>
  <td>"{@code fontScale}"</td>
   <td>The font scaling factor has changed &mdash; the user has selected
       a new global font size.</td>
  </tr><tr>
  <td>"{@code uiMode}"</td>
   <td>The user interface mode has changed &mdash; this can be caused when the user places the
device into a desk/car dock or when the night mode changes. See {@link
android.app.UiModeManager}.
    <em>Added in API level 8</em>.</td>
  </tr><tr>
   <td>"{@code orientation}"</td>
   <td>The screen orientation has changed &mdash; the user has rotated the device.
       <p class="note"><strong>Note:</strong> If your application targets API level 13 or higher (as
declared by the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
minSdkVersion}</a> and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
targetSdkVersion}</a> attributes), then you should also declare the {@code "screenSize"}
configuration, because it also changes when a device switches between portrait and landscape
orientations.</p></td>
 </tr><tr>
   <td>"{@code screenSize}"</td>
   <td>The current available screen size has changed. This represents a change in the currently
available size, relative to the current aspect ratio, so will change when the user switches between
landscape and portrait. However, if your application targets API level 12 or lower, then your
activity always handles this configuration change itself (this configuration change does not restart
your activity, even when running on an Android 3.2 or higher device).
  <p><em>Added in API level 13.</em></p></td>
 </tr><tr>
   <td>"{@code smallestScreenSize}"</td>
   <td>The physical screen size has changed. This represents a change in size regardless of
orientation, so will only change when the actual physical screen size has changed such as switching
to an external display. A change to this configuration corresponds to a change in the <a
href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">
smallestWidth configuration</a>. However, if your application targets API level 12 or lower, then
your activity always handles this configuration change itself (this configuration change does not
restart your activity, even when running on an Android 3.2 or higher device).
  <p><em>Added in API level 13.</em></p></td>
 </tr><tr>
  <td>"{@code layoutDirection}"</td>
   <td>The layout direction has changed. For example, changing from left-to-right (LTR)
    to right-to-left (RTL).
   <em>Added in API level 17.</em></td>
  </tr>
</table>

<p>
All of these configuration changes can impact the resource values seen by the
application.  Therefore, when <code>{@link android.app.Activity#onConfigurationChanged(android.content.res.Configuration)
onConfigurationChanged()}</code> is called, it will generally be necessary to again
retrieve all resources (including view layouts, drawables, and so on) to correctly
handle the change.
</p></dd>

<dt><a name="dlmode"></a>{@code android:documentLaunchMode}</dt>
<dd>Specifies how a new instance of an activity should be added to a task each time it is
launched. This attribute permits the user to have multiple documents from the same application
appear in the <a href="{@docRoot}guide/components/recents.html">overview screen</a>.

<p>This attribute has four values which produce the following effects when the user opens a document
with the application:</p>

<table>
<tr>
  <th>Value</th>
  <th>Description</th>
</tr><tr>
  <td>"{@code intoExisting}"</td>
  <td>The activity reuses the existing task for the document. Using this value is the same as setting
  the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag, <em>without</em> setting the
  {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag, as described in
  <a href="{@docRoot}guide/components/recents.html#flag-new-doc">Using the Intent flag to add a task
  </a>.</td>
</tr><tr>
    <td>"{@code always}"</td>
    <td>The activity creates a new task for the document, even if the document is already opened.
    This is the same as setting both the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}
    and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags.</td>
</tr><tr>
    <td>"{@code none}"</td>
    <td>The activity does not create a new task for the activity. This is the default value, which
    creates a new task only when {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} is set.
    The overview screen treats the activity as it would by default: it displays a single task for
    the app, which resumes from whatever activity the user last invoked.</td>
</tr><tr>
    <td>"{@code never}"</td>
    <td>This activity is not launched into a new document even if the Intent contains
    {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}. Setting this overrides the behavior
    of the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} and
    {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags, if either of these are set in
    the activity, and the overview screen displays a single task for the app, which resumes from
    whatever activity the user last invoked.</td>
</tr>
</table>

<p class="note"><strong>Note:</strong> For values other than "{@code none}" and "{@code never}" the
activity must be defined with {@code launchMode="standard"}. If this attribute is not specified,
{@code documentLaunchMode="none"} is used.</p>
</dd>

<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the activity can be instantiated by the system &mdash;
{@code "true"} if it can be, and "{@code false}" if not.  The default value
is "{@code true}".

<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
</code> element has its own<code>
<a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code>
attribute that applies to all application components, including activities.  The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
and {@code <activity>} attributes must both be "{@code true}" (as they both
are by default) for the system to be able to instantiate the activity.  If either
is "{@code false}", it cannot be instantiated.
</p></dd>

<dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt>
<dd>Whether or not the task initiated by this activity should be excluded from the list of recently
used applications, the <a href="{@docRoot}guide/components/recents.html">
overview screen</a>. That is, when this activity is the root activity of a new
task, this attribute determines whether the task should not appear in the list of recent apps. Set
"{@code true}" if the task should be <em>excluded</em> from the list; set "{@code false}" if it
should be <em>included</em>. The default value is "{@code false}".
</p></dd>

<dt><a name="exported"></a>{@code android:exported}</dt>
<dd>Whether or not the activity can be launched by components of other
applications &mdash; "{@code true}" if it can be, and "{@code false}" if not.
If "{@code false}", the activity can be launched only by components of the
same application or applications with the same user ID.

<p>
The default value depends on whether the activity contains intent filters.  The
absence of any filters means that the activity can be invoked only by specifying
its exact class name.  This implies that the activity is intended only for
application-internal use (since others would not know the class name).  So in
this case, the default value is "{@code false}".
On the other hand, the presence of at least one filter implies that the activity
is intended for external use, so the default value is "{@code true}".
</p>

<p>
This attribute is not the only way to limit an activity's exposure to other
applications.  You can also use a permission to limit the external entities that
can invoke the activity  (see the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code>
attribute).
</p></dd>

<dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt>
<dd>Whether or not an existing instance of the activity should be shut down
(finished) whenever the user again launches its task (chooses the task on the
home screen) &mdash; "{@code true}" if it should be shut down, and "{@code false}"
if not. The default value is "{@code false}".

<p>
If this attribute and
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
are both "{@code true}", this attribute trumps the other.  The affinity of the
activity is ignored.  The activity is not re-parented, but destroyed.
</p>

<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt>
<dd>Whether or not hardware-accelerated rendering should be enabled for this
Activity &mdash; "{@code true}" if it should be enabled, and "{@code false}" if
not. The default value is "{@code false}".


<p>Starting from Android 3.0, 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 do not explicitly make use
the framework's OpenGL libraries. Because of the increased resources required to
enable hardware acceleration, your app will consume more RAM.</p>

<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable
the hardware-accelerated renderer, test your application to ensure that it can
make use of the renderer without errors.</p>
</dd>

<dt><a name="icon"></a>{@code android:icon}</dt>
<dd>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 (see the <a href="#label">{@code
android:label}</a> attribute).
</p>

<p>
This attribute must be set as a reference to a drawable resource containing
the image definition.  If it is not set, the icon specified for the application
as a whole is used instead (see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).
</p>

<p>
The activity's icon &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element &mdash; is also the default icon for all the activity's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute).
</p></dd>

<dt><a name="label"></a>{@code android:label}</dt>
<dd>A user-readable label for the activity.  The label is displayed on-screen
when the activity must be represented to the user. It's often displayed along
with the activity icon.

<p>
If this attribute is not set, the label set for the application as a whole is
used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
</p>

<p>
The activity's label &mdash; whether set here or by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element &mdash; is also the
default label for all the activity's intent filters (see the
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">&lt;intent-filter&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute).
</p>

<p>
The label should be 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.
</p></dd>

<dt><a name="lmode"></a>{@code android:launchMode}</dt>
<dd>An instruction on how the activity should be launched.  There are four modes
that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants)
in {@link android.content.Intent} objects to determine what should happen when
the activity is called upon to handle an intent. They are:</p>

<p style="margin-left: 2em">"{@code standard}"
<br>"{@code singleTop}"
<br>"{@code singleTask}"
<br>"{@code singleInstance}"</p>

<p>
The default mode is "{@code standard}".
</p>

<p>
As shown in the table below, the modes fall into two main groups, with
"{@code standard}" and "{@code singleTop}" activities on one side, and
"{@code singleTask}" and "{@code singleInstance}" activities on the other.
An activity with the "{@code standard}" or "{@code singleTop}" launch mode
can be instantiated multiple times.  The instances can belong to any task
and can be located anywhere in the activity stack.  Typically, they're
launched into the task that called
<code>{@link android.content.Context#startActivity startActivity()}</code>
(unless the Intent object contains a
<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
instruction, in which case a different task is chosen &mdash; see the
<a href="#aff">taskAffinity</a> attribute).
</p>

<p>
In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities
can only begin a task.  They are always at the root of the activity stack.
Moreover, the device can hold only one instance of the activity at a time
&mdash; only one such task.
</p>

<p>
The "{@code standard}" and "{@code singleTop}" modes differ from each other
in just one respect:  Every time there's a new intent for a "{@code 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 "{@code singleTop}" activity may 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
will receive the new intent (in an
{@link android.app.Activity#onNewIntent onNewIntent()} call);
a new instance is not created.
In other circumstances &mdash; for example, if an existing instance of the
"{@code 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
&mdash; a new instance would be created and pushed on the stack.
</p>

<p>Similarly, if you
<a href="{@docRoot}training/implementing-navigation/ancestral.html">navigate
up</a> 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 {@code
singleTop} (or the <code>up</code> intent contains {@link
android.content.Intent#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 {@link android.app.Activity#onNewIntent onNewIntent()}
method.  If the parent activity has launch mode {@code standard} (and the
<code>up</code> intent does not contain {@link
android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the current activity and its
parent are both popped off the stack, and a new instance of the parent activity
is created to receive the navigation intent.
</p>


<p>
The "{@code singleTask}" and "{@code singleInstance}" modes also differ from
each other in only one respect:  A "{@code singleTask}" activity allows other
activities to be part of its task. It's always at the root of its task, but
other activities (necessarily "{@code standard}" and "{@code singleTop}"
activities) can be launched into that task.  A "{@code singleInstance}"
activity, on the other hand, permits no other activities to be part of its task.
It's the only activity in the task.  If it starts another activity, that
activity is assigned to a different task &mdash; as if {@code
FLAG_ACTIVITY_NEW_TASK} was in the intent.
</p>

<table>
<tr>
<th>Use Cases</th>
<th>Launch Mode</th>
<th>Multiple Instances?</th>
<th>Comments</th>
</tr>
<tr>
<td rowspan="2" style="width:20%;">Normal launches for most activities</td>
<td>"<code>standard</code>"</td>
<td>Yes</td>
<td>Default. The system always creates a new instance of the activity in the
target task and routes the intent to it.</td>
</tr>
<tr>
<td>"<code>singleTop</code>"</td>
<td>Conditionally</td>
<td>If an instance of the activity already exists at the top of the target task,
the system routes the intent to that instance through a call to its {@link
android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
new instance of the activity.</td>
</tr>
<tr>
<td rowspan="2">Specialized launches<br>
<em>(not recommended for general use)</em></td>
<td>"<code>singleTask</code>"</td>
<td>No</td>
<td>The system creates the activity at the root of a new task and routes the
intent to it. However, if an instance of the activity already exists, the system
routes the intent to existing instance through a call to its {@link
android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
new one.</td>
</tr>
<tr>
<td>"<code>singleInstance</code>"</td>
<td>No</td>
<td>Same as "<code>singleTask"</code>, except that the system doesn't launch any
other activities into the task holding the instance. The activity is always the
single and only member of its task.</td>
</tr>
</table>

<p>As shown in the table above, <code>standard</code> is the default mode and is
appropriate for most types of activities. <code>SingleTop</code> is also a
common and useful launch mode for many types of activities. The other modes
&mdash; <code>singleTask</code> and <code>singleInstance</code> &mdash; are
<span style="color:red">not appropriate for most applications</span>,
since they result in an interaction model that is likely to be unfamiliar to
users and is very different from most other applications.

<p>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 <em>Back</em> button. </p>

<p>For more information on launch modes and their interaction with Intent
flags, see the
<a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a>
document.
</p>
</dd>

<dt><a name="maxrecents"></a>{@code android:maxRecents}</dt>
<dd>The maximum number of tasks rooted at this activity in the <a href="{@docRoot}guide/components/recents.html">
overview screen</a>. When this number of entries is reached, the system removes the least-recently
used instance from the overview screen. Valid values are 1 through 50 (25 on low memory devices);
zero is invalid. This must be an integer value, such as 50. The default value is 16.
</dd>

<dt><a name="multi"></a>{@code android:multiprocess}</dt>
<dd>Whether an instance of the activity can be launched into the process of the component
that started it &mdash; "{@code true}" if it can be, and "{@code false}" if not.
The default value is "{@code false}".

<p>
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 "{@code true}", instances of the
activity can run in multiple processes, allowing the system to create instances
wherever they are used (provided permissions allow it), something that is almost
never necessary or desirable.
</p></dd>

<dt><a name="nm"></a>{@code android:name}</dt>
<dd>The name of the class that implements the activity, a subclass of
{@link android.app.Activity}.  The attribute value should be a fully qualified
class name (such as, "{@code com.example.project.ExtracurricularActivity}").
However, as a shorthand, if the first character of the name is a period
(for example, "{@code .ExtracurricularActivity}"), it is appended to the
package name specified in the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element.
<p>Once you publish your application, you <a
href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not
change this name</a> (unless you've set <code><a
href="#exported">android:exported</a>="false"</code>).</p>

<p>
There is no default.  The name must be specified.
</p></dd>

<!-- ##api level 3## -->
<dt><a name="nohist"></a>{@code android:noHistory}</dt>
<dd>Whether or not the activity should be removed from the activity stack and
finished (its <code>{@link android.app.Activity#finish finish()}</code>
method called) when the user navigates away from it and it's no longer
visible on screen &mdash; "{@code true}" if it should be finished, and
"{@code false}" if not.  The default value is "{@code false}".

<p>
A value of "{@code true}" means that the activity will not leave a
historical trace.  It will not remain in the activity stack for the task,
so the user will not be able to return to it. In this case,
{@link android.app.Activity#onActivityResult onActivityResult()} is never called if you
start another activity for a result from this activity.
</p>

<p>
This attribute was introduced in API Level 3.
</p>
</dd>

<!-- api level 16 -->
<dt><a name="parent"></a>{@code android:parentActivityName}</dt>
<dd>The class name of the logical parent of the activity. The name here must match the class
  name given to the corresponding {@code <activity>} element's
  <a href="#nm"><code>android:name</code></a> attribute.

<p>The system reads this attribute to determine which activity should be started when
  the user presses the Up button in the action bar. The system can also use this information to
  synthesize a back stack of activities with {@link android.app.TaskStackBuilder}.</p>

<p>To support API levels 4 - 16, you can also declare the parent activity with a {@code
<meta-data>} element that specifies a value for {@code "android.support.PARENT_ACTIVITY"}.
For example:</p>
<pre>
&lt;activity
    android:name="com.example.app.ChildActivity"
    android:label="@string/title_child_activity"
    android:parentActivityName="com.example.app.MainActivity" >
    &lt;!-- Parent activity meta-data to support API level 4+ -->
    &lt;meta-data
        android:name="android.support.PARENT_ACTIVITY"
        android:value="com.example.app.MainActivity" />
&lt;/activity>
</pre>

<p>For more information about declaring the parent activity to support Up navigation,
read <a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
Navigation</a>.</p>

<p>
This attribute was introduced in API Level 16.
</p>
</dd>



<dt><a name="prmsn"></a>{@code android:permission}</dt>
<dd>The name of a permission that clients must have to launch the activity
or otherwise get it to respond to an intent.  If a caller of
<code>{@link android.content.Context#startActivity startActivity()}</code> or
<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code>
has not been granted the specified permission, its intent will not be
delivered to the activity.

<p>
If this attribute is not set, the permission set by the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code>
attribute applies to the activity.  If neither attribute is set, the activity is
not protected by a permission.
</p>

<p>
For more information on permissions, see the
<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
section in the introduction and another document,
<a href="{@docRoot}guide/topics/security/security.html">Security and
Permissions</a>.
</p></dd>

<dt><a name="proc"></a>{@code android:process}</dt>
<dd>The name of the process in which the activity should run. Normally, all components of an
application run in a default process name created for the application and you do
not need to use this attribute. But if necessary, you can override the default process
name with this attribute, allowing you to spread your app components across
multiple processes.

<p>
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 will run
in a global process of that name, provided that it has permission to do so.
This allows components in different applications to share a process, reducing
resource usage.
</p>

<p>The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"
>&lt;application&gt;</a></code> element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code>
attribute can set a different default process name for all components.
</dd>

<dt><a name="relinquish"></a>{@code android:relinquishTaskIdentity}</dt>
<dd>Whether or not 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 "{@code true}" replaces the base
Intent with that of the next activity in the task. If the next activity also has this attribute set
to "{@code true}" then it will yield 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 "{@code false}". The default value is "{@code false}".

<p>This attribute set to "{@code true}" also permits the activity's use of the
{@link android.app.ActivityManager.TaskDescription} to change labels, colors
and icons in the <a href="{@docRoot}guide/components/recents.html">overview screen</a>.</p>
</dd>


<dt><a name="screen"></a>{@code android:screenOrientation}</dt>
<dd>The orientation of the activity's display on the device.

<p>The value can be any one of the following strings:</p>

<table>
<tr>
   <td>"{@code unspecified}"</td>
   <td>The default value.  The system chooses the orientation.  The policy it
       uses, and therefore the choices made in specific contexts, may differ
       from device to device.</td>
</tr><tr>
   <td>"{@code behind}"</td>
   <td>The same orientation as the activity that's immediately beneath it in
       the activity stack.</td>
</tr><tr>
   <td>"{@code landscape}"</td>
   <td>Landscape orientation (the display is wider than it is tall).</td>
</tr><tr>
   <td>"{@code portrait}"</td>
   <td>Portrait orientation (the display is taller than it is wide).</td>
</tr><tr>
   <td>"{@code reverseLandscape}"</td>
   <td>Landscape orientation in the opposite direction from normal landscape.
<em>Added in API level 9.</em></td>
</tr><tr>
   <td>"{@code reversePortrait}"</td>
   <td>Portrait orientation in the opposite direction from normal portrait.
<em>Added in API level 9.</em></td>
</tr><tr>
   <td>"{@code sensorLandscape}"</td>
   <td>Landscape orientation, but can be either normal or reverse landscape based on the device
sensor.
<em>Added in API level 9.</em></td>
</tr><tr>
   <td>"{@code sensorPortrait}"</td>
   <td>Portrait orientation, but can be either normal or reverse portrait based on the device
sensor.
<em>Added in API level 9.</em></td>
</tr><tr>
   <td>"{@code userLandscape}"</td>
   <td>Landscape orientation, but can be either normal or reverse landscape based on the device
sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves
the same as {@code landscape}, otherwise it behaves the same as {@code sensorLandscape}.
<em>Added in API level 18.</em></td>
</tr><tr>
   <td>"{@code userPortrait}"</td>
   <td>Portrait orientation, but can be either normal or reverse portrait based on the device
sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves
the same as {@code portrait}, otherwise it behaves the same as {@code sensorPortrait}.
<em>Added in API level 18.</em></td>
</tr><tr>
   <td>"{@code sensor}"</td>
   <td>The orientation is determined by the device orientation sensor.  The orientation of the
display depends on how the user is holding the device; it changes when the user rotates the
device. Some devices, though, will not rotate to all four possible orientations, by default. To
allow all four orientations, use {@code "fullSensor"}.</td>
</tr><tr>
   <td>"{@code fullSensor}"</td>
   <td>The orientation is determined by the device orientation sensor for any of the 4 orientations.
This is similar to {@code "sensor"} except this allows any of the 4 possible screen orientations,
regardless of what the device will normally do (for example, some devices won't normally use reverse
portrait or reverse landscape, but this enables those). <em>Added in API level 9.</em></td>
</tr><tr>
   <td>"{@code nosensor}"</td>
   <td>The orientation is determined without reference to a physical orientation sensor.  The sensor
is ignored, so the display will not rotate based on how the user moves the device.  Except for this
distinction, the system chooses the orientation using the same policy as for the "{@code
unspecified}" setting.</td>
</tr><tr>
   <td>"{@code user}"</td>
   <td>The user's current preferred orientation.</td>
</tr><tr>
   <td>"{@code fullUser}"</td>
   <td>If the user has locked sensor-based rotation, this behaves the same as {@code user},
   otherwise it behaves the same as {@code fullSensor} and allows any of the 4 possible
   screen orientations.
    <em>Added in API level 18.</em></td>
</tr><tr>
   <td>"{@code locked}"</td>
   <td>Locks the orientation to its current rotation, whatever that is.
<em>Added in API level 18.</em></td>
</tr>
</table>

<p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values,
it is considered a hard requirement for the orientation in which the activity runs. As such,
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 {@code "landscape"}, {@code "reverseLandscape"}, or
{@code "sensorLandscape"}, then your application will be available only to devices that support
landscape orientation. However, you should also explicitly declare that
your application requires either portrait or landscape orientation with the <a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
element. For example, <code>&lt;uses-feature
android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior
provided by Google Play (and other services that support it) and the platform itself does not
control whether your app can be installed when a device supports only certain orientations.</p>

</dd>

<dt><a name="state"></a>{@code android:stateNotNeeded}</dt>
<dd>Whether or not the activity can be killed and successfully restarted
without having saved its state &mdash; "{@code true}" if it can be restarted
without reference to its previous state, and "{@code false}" if its previous
state is required.  The default value is "{@code false}".

<p>
Normally, before an activity is temporarily shut down to save resources, its
<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code>
method is called.  This method stores the current state of the activity in a
{@link android.os.Bundle} object, which is then passed to
<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity
is restarted.  If this attribute is set to "{@code true}",
{@code onSaveInstanceState()} may not be called and {@code onCreate()} will
be passed {@code null} instead of the Bundle &mdash; just as it was when the
activity started for the first time.
</p>

<p>
A "{@code true}" setting ensures that the activity can be restarted in the
absence of retained state.  For example, the activity that displays the
home screen uses this setting to make sure that it does not get removed if it
crashes for some reason.
</p></dd>

<dt><a name="aff"></a>{@code android:taskAffinity}</dt>
<dd>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.

<p>
The affinity determines two things &mdash; the task that the activity is re-parented
to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
attribute) and the task that will house the activity when it is launched
with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
flag.
</p>

<p>
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 does not have an affinity for any task, set
it to an empty string.

<p>
If this attribute is not set, the activity inherits the affinity set
for the application (see the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code>
attribute).  The name of the default affinity for an application is
the package name set by the
<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code>
element.
</p>

<dt><a name="theme"></a>{@code android:theme}</dt>
<dd>A reference to a style resource defining an overall theme for the activity.
This automatically sets the activity's context to use this theme (see
<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also
cause "starting" animations prior to the activity being launched (to better
match what the activity actually looks like).

<p>
If this attribute is not set, the activity inherits the theme set for the
application as a whole &mdash; from the
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
element's
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code>
attribute.  If that attribute is also not set, the default system theme is used. For more
information, see the <a
href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide.
</p>
<dd>

<!-- ##api level 14## -->
<dt><a name="uioptions"></a>{@code android:uiOptions}</dt>
<dd>Extra options for an activity's UI.
  <p>Must be one of the following values.</p>

  <table>
    <tr><th>Value</th><th>Description</th></tr>
    <tr><td>{@code "none"}</td><td>No extra UI options. This is the default.</td></tr>
    <tr><td>{@code "splitActionBarWhenNarrow"}</td><td>Add a bar at
the bottom of the screen to display action items in the <em>app bar</em> (also known as the
<em>action bar</em>), when
constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small
number of action items appearing in the app bar at the top of the screen, the app bar is
split into the top navigation section and the bottom bar for action items. This ensures a reasonable
amount of space is made available not only for the action items, but also for navigation and title
elements at the top. Menu items are not split across the two bars; they always appear
together.</td></tr>
  </table>
  <p>For more information about the app bar, see the <a
href="{@docRoot}training/appbar/index.html">Adding the App Bar</a> training class.</p>
  <p>This attribute was added in API level 14.</p>
</dd>


<!-- ##api level 3## -->
<dt><a name="wsoft"></a>{@code android:windowSoftInputMode}</dt>
<dd>How the main window of the activity interacts with the window containing
the on-screen soft keyboard.  The setting for this attribute affects two
things:

<ul>
<li>The state of the soft keyboard &mdash; whether it is hidden or visible
&mdash; when the activity becomes the focus of user attention.</li>

<li>The adjustment made to the activity's main window &mdash; whether it is
resized smaller to make room for the soft keyboard or whether its contents
pan to make the current focus visible when part of the window is covered by
the soft keyboard.</li>
</ul>

<p>
The setting must be one of the values listed in the following table, or a
combination of one "{@code state...}" value plus one "{@code adjust...}"
value.  Setting multiple values in either group &mdash; multiple
"{@code state...}" values, for example &mdash; has undefined results.
Individual values are separated by a vertical bar ({@code |}).  For example:
</p>

<pre>&lt;activity android:windowSoftInputMode="stateVisible|adjustResize" . . . &gt;</pre>

<p>
Values set here (other than "{@code stateUnspecified}" and
"{@code adjustUnspecified}") override values set in the theme.
</p>

<table>
<tr>
   <th>Value</th>
   <th>Description</th>
</tr><tr>
   <td>"{@code stateUnspecified}"</td>
   <td>The state of the soft keyboard (whether it is hidden or visible)
       is not specified.  The system will choose an appropriate state or
       rely on the setting in the theme.

       <p>
       This is the default setting for the behavior of the soft keyboard.
       </p></td>
</tr></tr>
   <td>"{@code stateUnchanged}"</td>
   <td>The soft keyboard is kept in whatever state it was last in,
       whether visible or hidden, when the activity comes to the fore.</td>
</tr></tr>
   <td>"{@code stateHidden}"</td>
   <td>The soft keyboard is hidden when the user chooses the activity
       &mdash; that is, when the user affirmatively navigates forward to the
       activity, rather than backs into it because of leaving another activity.</td>
</tr></tr>
   <td>"{@code stateAlwaysHidden}"</td>
   <td>The soft keyboard is always hidden when the activity's main window
       has input focus.</td>
</tr></tr>
   <td>"{@code stateVisible}"</td>
   <td>The soft keyboard is visible when that's normally appropriate
       (when the user is navigating forward to the activity's main window).</td>
</tr></tr>
   <td>"{@code stateAlwaysVisible}"</td>
   <td>The soft keyboard is made visible when the user chooses the
       activity &mdash; that is, when the user affirmatively navigates forward
       to the activity, rather than backs into it because of leaving another
       activity.</td>
</tr></tr>
   <td>"{@code adjustUnspecified}"</td>
   <td>It is unspecified whether the activity's main window resizes
       to make room for the soft keyboard, or whether the contents
       of the window pan to make the current focus visible on-screen.
       The system will automatically select one of these modes depending
       on whether the content of the window has any layout views that
       can scroll their contents.  If there is such a view, the window
       will be resized, on the assumption that scrolling can make all
       of the window's contents visible within a smaller area.

       <p>
       This is the default setting for the behavior of the main window.
       </p></td>
</tr></tr>
   <td>"{@code adjustResize}"</td>
   <td>The activity's main window is always resized to make room for
       the soft keyboard on screen.</td>
</tr></tr>
   <td>"{@code adjustPan}"</td>
   <td>The activity's main window is not resized to make room for the soft
       keyboard.  Rather, the contents of the window are automatically
       panned so that the current focus is never obscured by the keyboard
       and users can always see what they are typing.  This is generally less
       desirable than resizing, because the user may need to close the soft
       keyboard to get at and interact with obscured parts of the window.</td>
</tr>
</table>

<p>
This attribute was introduced in API Level 3.
</p></dd>
</dl></dd>

<!-- ##api level indication## -->
<dt>introduced in:</dt>
<dd>API Level 1 for all attributes except for
<code><a href="#nohist">noHistory</a></code> and
<code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API
Level 3.</dd>

<dt>see also:</dt>
<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></code></dd>
</dl>