1 page.title=<activity>
2 parent.title=The AndroidManifest.xml File
3 parent.link=manifest-intro.html
8 <dd><pre class="stx"><activity android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"]
9 android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"]
10 android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"]
11 android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale",
12 "touchscreen", "keyboard", "keyboardHidden",
13 "navigation", "screenLayout", "fontScale", "uiMode",
14 "orientation", "screenSize", "smallestScreenSize"]
15 android:<a href="#enabled">enabled</a>=["true" | "false"]
16 android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"]
17 android:<a href="#exported">exported</a>=["true" | "false"]
18 android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"]
19 android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"]
20 android:<a href="#icon">icon</a>="<i>drawable resource</i>"
21 android:<a href="#label">label</a>="<i>string resource</i>"
22 android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" |
23 "singleTask" | "singleInstance"]
24 android:<a href="#multi">multiprocess</a>=["true" | "false"]
25 android:<a href="#nm">name</a>="<i>string</i>"
26 android:<a href="#nohist">noHistory</a>=["true" | "false"] <!-- ##api level 3## -->
27 android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 -->
28 android:<a href="#prmsn">permission</a>="<i>string</i>"
29 android:<a href="#proc">process</a>="<i>string</i>"
30 android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" |
31 "landscape" | "portrait" |
32 "reverseLandscape" | "reversePortrait" |
33 "sensorLandscape" | "sensorPortrait" |
34 "sensor" | "fullSensor" | "nosensor"]
35 android:<a href="#state">stateNotNeeded</a>=["true" | "false"]
36 android:<a href="#aff">taskAffinity</a>="<i>string</i>"
37 android:<a href="#theme">theme</a>="<i>resource or theme</i>"
38 android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"]
39 android:<a href="#wsoft">windowSoftInputMode</a>=["stateUnspecified",
40 "stateUnchanged", "stateHidden",
41 "stateAlwaysHidden", "stateVisible",
42 "stateAlwaysVisible", "adjustUnspecified",
43 "adjustResize", "adjustPan"] > <!-- ##api level 3## -->
45 </activity></pre></dd>
47 <dt>contained in:</dt>
48 <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd>
51 <dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code>
52 <br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd>
55 <dd>Declares an activity (an {@link android.app.Activity} subclass) that
56 implements part of the application's visual user interface. All activities
57 must be represented by {@code <activity>}
58 elements in the manifest file. Any that are not declared there will not be seen
59 by the system and will never be run.
63 <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt>
64 <dd>Whether or not the activity can move from the task that started it to
65 the task it has an affinity for when that task is next brought to the
66 front — "{@code true}" if it can move, and "{@code false}" if it
67 must remain with the task where it started.
70 If this attribute is not set, the value set by the corresponding
71 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code>
72 attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element
73 applies to the activity. The default value is "{@code false}".
77 Normally when an activity is started, it's associated with the task of
78 the activity that started it and it stays there for its entire lifetime.
79 You can use this attribute to force it to be re-parented to the task it
80 has an affinity for when its current task is no longer displayed.
81 Typically, it's used to cause the activities of an application to move
82 to the main task associated with that application.
86 For example, if an e-mail message contains a link to a web page, clicking
87 the link brings up an activity that can display the page. That activity
88 is defined by the browser application, but is launched as part of the e-mail
89 task. If it's reparented to the browser task, it will be shown when the
90 browser next comes to the front, and will be absent when the e-mail task
95 The affinity of an activity is defined by the
96 <code><a href="#aff">taskAffinity</a></code> attribute. The affinity
97 of a task is determined by reading the affinity of its root activity.
98 Therefore, by definition, a root activity is always in a task with the
99 same affinity. Since activities with "{@code singleTask}" or
100 "{@code singleInstance}" launch modes can only be at the root of a task,
101 re-parenting is limited to the "{@code standard}" and "{@code singleTop}"
102 modes. (See also the <code><a href="#lmode">launchMode</a></code>
106 <dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt>
107 <dd>Whether or not the state of the task that the activity is in will always
108 be maintained by the system — "{@code true}" if it will be, and
109 "{@code false}" if the system is allowed to reset the task to its initial
110 state in certain situations. The default value is "{@code false}". This
111 attribute is meaningful only for the root activity of a task; it's ignored
112 for all other activities.
115 Normally, the system clears a task (removes all activities from the stack
116 above the root activity) in certain situations when the user re-selects that
117 task from the home screen. Typically, this is done if the user hasn't visited
118 the task for a certain amount of time, such as 30 minutes.
122 However, when this attribute is "{@code true}", users will always return
123 to the task in its last state, regardless of how they get there. This is
124 useful, for example, in an application like the web browser where there is
125 a lot of state (such as multiple open tabs) that users would not like to lose.
128 <dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt>
129 <dd>Whether or not all activities will be removed from the task, except for
130 the root activity, whenever it is re-launched from the home screen —
131 "{@code true}" if the task is always stripped down to its root activity, and
132 "{@code false}" if not. The default value is "{@code false}". This attribute
133 is meaningful only for activities that start a new task (the root activity);
134 it's ignored for all other activities in the task.
137 When the value is "{@code true}", every time users start the task again, they
138 are brought to its root activity regardless of what they were last doing in
139 the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to
140 leave it. When the value is "{@code false}", the task may be cleared of activities in
141 some situations (see the
142 <code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always.
146 Suppose, for example, that someone launches activity P from the home screen,
147 and from there goes to activity Q. The user next presses <em>Home</em>, and then returns
148 to activity P. Normally, the user would see activity Q, since that is what they
149 were last doing in P's task. However, if P set this flag to "{@code true}", all
150 of the activities on top of it (Q in this case) were removed when the user pressed
151 <em>Home</em> and the task went to the background. So the user sees only P when returning
156 If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code>
157 are both "{@code true}", any activities that can be re-parented are moved to
158 the task they share an affinity with; the remaining activities are then dropped,
162 <dt><a name="config"></a>{@code android:configChanges}</dt>
163 <dd>Lists configuration changes that the activity will handle itself. When a configuration
164 change occurs at runtime, the activity is shut down and restarted by default, but declaring a
165 configuration with this attribute will prevent the activity from being restarted. Instead, the
166 activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged
167 onConfigurationChanged()}</code> method is called.
169 <p class="note"><strong>Note:</strong> Using this attribute should be
170 avoided and used only as a last-resort. Please read <a
171 href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more
172 information about how to properly handle a restart due to a configuration change.</p>
175 Any or all of the following strings are valid values for this attribute. Multiple values are
176 separated by '{@code |}' — for example, "{@code locale|navigation|orientation}".
184 <td>"{@code mcc}"</td>
185 <td>The IMSI mobile country code (MCC) has changed —
186 a SIM has been detected and updated the MCC.</td>
188 <td>"{@code mnc}"</td>
189 <td>The IMSI mobile network code (MNC) has changed —
190 a SIM has been detected and updated the MNC.</td>
192 <td>"{@code locale}"</td>
193 <td>The locale has changed — the user has selected a new
194 language that text should be displayed in.</td>
196 <td>"{@code touchscreen}"</td>
197 <td>The touchscreen has changed. (This should never normally happen.)</td>
199 <td>"{@code keyboard}"</td>
200 <td>The keyboard type has changed — for example, the user has
201 plugged in an external keyboard.</td>
203 <td>"{@code keyboardHidden}"</td>
204 <td>The keyboard accessibility has changed — for example, the
205 user has revealed the hardware keyboard.</td>
207 <td>"{@code navigation}"</td>
208 <td>The navigation type (trackball/dpad) has changed. (This should never normally happen.)</td>
210 <td>"{@code screenLayout}"</td>
211 <td>The screen layout has changed — this might be caused by a
212 different display being activated.</td>
214 <td>"{@code fontScale}"</td>
215 <td>The font scaling factor has changed — the user has selected
216 a new global font size.</td>
218 <td>"{@code uiMode}"</td>
219 <td>The user interface mode has changed — this can be caused when the user places the
220 device into a desk/car dock or when the night mode changes. See {@link
221 android.app.UiModeManager}.
222 <em>Added in API level 8</em>.</td>
224 <td>"{@code orientation}"</td>
225 <td>The screen orientation has changed — the user has rotated the device.
226 <p class="note"><strong>Note:</strong> If your application targets API level 13 or higher (as
227 declared by the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
228 minSdkVersion}</a> and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
229 targetSdkVersion}</a> attributes), then you should also declare the {@code "screenSize"}
230 configuration, because it also changes when a device switches between portrait and landscape
231 orientations.</p></td>
233 <td>"{@code screenSize}"</td>
234 <td>The current available screen size has changed. This represents a change in the currently
235 available size, relative to the current aspect ratio, so will change when the user switches between
236 landscape and portrait. However, if your application targets API level 12 or lower, then your
237 activity always handles this configuration change itself (this configuration change does not restart
238 your activity, even when running on an Android 3.2 or higher device).
239 <p><em>Added in API level 13.</em></p></td>
241 <td>"{@code smallestScreenSize}"</td>
242 <td>The physical screen size has changed. This represents a change in size regardless of
243 orientation, so will only change when the actual physical screen size has changed such as switching
244 to an external display. A change to this configuration corresponds to a change in the <a
245 href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">
246 smallestWidth configuration</a>. However, if your application targets API level 12 or lower, then
247 your activity always handles this configuration change itself (this configuration change does not
248 restart your activity, even when running on an Android 3.2 or higher device).
249 <p><em>Added in API level 13.</em></p></td>
251 <td>"{@code layoutDirection}"</td>
252 <td>The layout direction has changed. For example, changing from left-to-right (LTR)
253 to right-to-left (RTL).
254 <em>Added in API level 17.</em></td>
259 All of these configuration changes can impact the resource values seen by the
260 application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged
261 onConfigurationChanged()}</code> is called, it will generally be necessary to again
262 retrieve all resources (including view layouts, drawables, and so on) to correctly
266 <dt><a name="enabled"></a>{@code android:enabled}</dt>
267 <dd>Whether or not the activity can be instantiated by the system —
268 "{@code true}" if it can be, and "{@code false}" if not. The default value
272 The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own
273 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code>
274 attribute that applies to all application components, including activities. The
275 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
276 and {@code <activity>} attributes must both be "{@code true}" (as they both
277 are by default) for the system to be able to instantiate the activity. If either
278 is "{@code false}", it cannot be instantiated.
281 <dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt>
282 <dd>Whether or not the task initiated by this activity should be excluded from the list of recently
283 used applications ("recent apps"). That is, when this activity is the root activity of a new task,
284 this attribute determines whether the task should not appear in the list of recent apps. "{@code
285 true}" if the task should be <em>excluded</em> from the list; "{@code false}" if it should be
286 <em>included</em>. The default value is "{@code false}".
289 <dt><a name="exported"></a>{@code android:exported}</dt>
290 <dd>Whether or not the activity can be launched by components of other
291 applications — "{@code true}" if it can be, and "{@code false}" if not.
292 If "{@code false}", the activity can be launched only by components of the
293 same application or applications with the same user ID.
296 The default value depends on whether the activity contains intent filters. The
297 absence of any filters means that the activity can be invoked only by specifying
298 its exact class name. This implies that the activity is intended only for
299 application-internal use (since others would not know the class name). So in
300 this case, the default value is "{@code false}".
301 On the other hand, the presence of at least one filter implies that the activity
302 is intended for external use, so the default value is "{@code true}".
306 This attribute is not the only way to limit an activity's exposure to other
307 applications. You can also use a permission to limit the external entities that
308 can invoke the activity (see the
309 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code>
313 <dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt>
314 <dd>Whether or not an existing instance of the activity should be shut down
315 (finished) whenever the user again launches its task (chooses the task on the
316 home screen) — "{@code true}" if it should be shut down, and "{@code false}"
317 if not. The default value is "{@code false}".
320 If this attribute and
321 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
322 are both "{@code true}", this attribute trumps the other. The affinity of the
323 activity is ignored. The activity is not re-parented, but destroyed.
326 <dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt>
327 <dd>Whether or not hardware-accelerated rendering should be enabled for this
328 Activity — "{@code true}" if it should be enabled, and "{@code false}" if
329 not. The default value is "{@code false}".
332 <p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is
333 available to applications, to improve performance for many common 2D graphics
334 operations. When the hardware-accelerated renderer is enabled, most operations
335 in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated.
336 This results in smoother animations, smoother scrolling, and improved
337 responsiveness overall, even for applications that do not explicitly make use
338 the framework's OpenGL libraries. Because of the increased resources required to
339 enable hardware acceleration, your app will consume more RAM.</p>
341 <p>Note that not all of the OpenGL 2D operations are accelerated. If you enable
342 the hardware-accelerated renderer, test your application to ensure that it can
343 make use of the renderer without errors.</p>
346 <dt><a name="icon"></a>{@code android:icon}</dt>
347 <dd>An icon representing the activity. The icon is displayed to users when
348 a representation of the activity is required on-screen. For example, icons
349 for activities that initiate tasks are displayed in the launcher window.
350 The icon is often accompanied by a label (see the <a href="#label">{@code
351 android:label}</a> attribute).
355 This attribute must be set as a reference to a drawable resource containing
356 the image definition. If it is not set, the icon specified for the application
357 as a whole is used instead (see the
358 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
359 element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).
363 The activity's icon — whether set here or by the
364 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
365 element — is also the default icon for all the activity's intent filters (see the
366 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's
367 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute).
370 <dt><a name="label"></a>{@code android:label}</dt>
371 <dd>A user-readable label for the activity. The label is displayed on-screen
372 when the activity must be represented to the user. It's often displayed along
373 with the activity icon.
376 If this attribute is not set, the label set for the application as a whole is
377 used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's
378 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute).
382 The activity's label — whether set here or by the
383 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the
384 default label for all the activity's intent filters (see the
385 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's
386 <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute).
390 The label should be set as a reference to a string resource, so that
391 it can be localized like other strings in the user interface.
392 However, as a convenience while you're developing the application,
393 it can also be set as a raw string.
396 <dt><a name="lmode"></a>{@code android:launchMode}</dt>
397 <dd>An instruction on how the activity should be launched. There are four modes
398 that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants)
399 in {@link android.content.Intent} objects to determine what should happen when
400 the activity is called upon to handle an intent. They are:</p>
402 <p style="margin-left: 2em">"{@code standard}"
403 <br>"{@code singleTop}"
404 <br>"{@code singleTask}"
405 <br>"{@code singleInstance}"</p>
408 The default mode is "{@code standard}".
412 As shown in the table below, the modes fall into two main groups, with
413 "{@code standard}" and "{@code singleTop}" activities on one side, and
414 "{@code singleTask}" and "{@code singleInstance}" activities on the other.
415 An activity with the "{@code standard}" or "{@code singleTop}" launch mode
416 can be instantiated multiple times. The instances can belong to any task
417 and can be located anywhere in the activity stack. Typically, they're
418 launched into the task that called
419 <code>{@link android.content.Context#startActivity startActivity()}</code>
420 (unless the Intent object contains a
421 <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
422 instruction, in which case a different task is chosen — see the
423 <a href="#aff">taskAffinity</a> attribute).
427 In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities
428 can only begin a task. They are always at the root of the activity stack.
429 Moreover, the device can hold only one instance of the activity at a time
430 — only one such task.
434 The "{@code standard}" and "{@code singleTop}" modes differ from each other
435 in just one respect: Every time there's a new intent for a "{@code standard}"
436 activity, a new instance of the class is created to respond to that intent.
437 Each instance handles a single intent.
438 Similarly, a new instance of a "{@code singleTop}" activity may also be
439 created to handle a new intent. However, if the target task already has an
440 existing instance of the activity at the top of its stack, that instance
441 will receive the new intent (in an
442 <code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call);
443 a new instance is not created.
444 In other circumstances — for example, if an existing instance of the
445 "{@code singleTop}" activity is in the target task, but not at the top of
446 the stack, or if it's at the top of a stack, but not in the target task
447 — a new instance would be created and pushed on the stack.
451 The "{@code singleTask}" and "{@code singleInstance}" modes also differ from
452 each other in only one respect: A "{@code singleTask}" activity allows other
453 activities to be part of its task. It's always at the root of its task, but
454 other activities (necessarily "{@code standard}" and "{@code singleTop}"
455 activities) can be launched into that task. A "{@code singleInstance}"
456 activity, on the other hand, permits no other activities to be part of its task.
457 It's the only activity in the task. If it starts another activity, that
458 activity is assigned to a different task — as if {@code
459 FLAG_ACTIVITY_NEW_TASK} was in the intent.
466 <th>Multiple Instances?</th>
470 <td rowspan="2" style="width:20%;">Normal launches for most activities</td>
471 <td>"<code>standard</code>"</td>
473 <td>Default. The system always creates a new instance of the activity in the
474 target task and routes the intent to it.</td>
477 <td>"<code>singleTop</code>"</td>
478 <td>Conditionally</td>
479 <td>If an instance of the activity already exists at the top of the target task,
480 the system routes the intent to that instance through a call to its {@link
481 android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
482 new instance of the activity.</td>
485 <td rowspan="2">Specialized launches<br>
486 <em>(not recommended for general use)</em></td>
487 <td>"<code>singleTask</code>"</td>
489 <td>The system creates the activity at the root of a new task and routes the
490 intent to it. However, if an instance of the activity already exists, the system
491 routes the intent to existing instance through a call to its {@link
492 android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a
496 <td>"<code>singleInstance</code>"</td>
498 <td>Same as "<code>singleTask"</code>, except that the system doesn't launch any
499 other activities into the task holding the instance. The activity is always the
500 single and only member of its task.</td>
504 <p>As shown in the table above, <code>standard</code> is the default mode and is
505 appropriate for most types of activities. <code>SingleTop</code> is also a
506 common and useful launch mode for many types of activities. The other modes
507 — <code>singleTask</code> and <code>singleInstance</code> — are
508 <span style="color:red">not appropriate for most applications</span>,
509 since they result in an interaction model that is likely to be unfamiliar to
510 users and is very different from most other applications.
512 <p>Regardless of the launch mode that you choose, make sure to test the usability
513 of the activity during launch and when navigating back to it from
514 other activities and tasks using the <em>Back</em> button. </p>
516 <p>For more information on launch modes and their interaction with Intent
518 <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a>
523 <dt><a name="multi"></a>{@code android:multiprocess}</dt>
524 <dd>Whether an instance of the activity can be launched into the process of the component
525 that started it — "{@code true}" if it can be, and "{@code false}" if not.
526 The default value is "{@code false}".
529 Normally, a new instance of an activity is launched into the process of the
530 application that defined it, so all instances of the activity run in the same
531 process. However, if this flag is set to "{@code true}", instances of the
532 activity can run in multiple processes, allowing the system to create instances
533 wherever they are used (provided permissions allow it), something that is almost
534 never necessary or desirable.
537 <dt><a name="nm"></a>{@code android:name}</dt>
538 <dd>The name of the class that implements the activity, a subclass of
539 {@link android.app.Activity}. The attribute value should be a fully qualified
540 class name (such as, "{@code com.example.project.ExtracurricularActivity}").
541 However, as a shorthand, if the first character of the name is a period
542 (for example, "{@code .ExtracurricularActivity}"), it is appended to the
543 package name specified in the
544 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code>
546 <p>Once you publish your application, you <a
547 href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not
548 change this name</a> (unless you've set <code><a
549 href="#exported">android:exported</a>="false"</code>).</p>
552 There is no default. The name must be specified.
555 <!-- ##api level 3## -->
556 <dt><a name="nohist"></a>{@code android:noHistory}</dt>
557 <dd>Whether or not the activity should be removed from the activity stack and
558 finished (its <code>{@link android.app.Activity#finish finish()}</code>
559 method called) when the user navigates away from it and it's no longer
560 visible on screen — "{@code true}" if it should be finished, and
561 "{@code false}" if not. The default value is "{@code false}".
564 A value of "{@code true}" means that the activity will not leave a
565 historical trace. It will not remain in the activity stack for the task,
566 so the user will not be able to return to it.
570 This attribute was introduced in API Level 3.
574 <!-- api level 16 -->
575 <dt><a name="parent"></a>{@code android:parentActivityName}</dt>
576 <dd>The class name of the logical parent of the activity. The name here must be formatted
577 the same as the corresponding activity is declared in its own
578 <a href="#nm">android:name</a>.
580 <p>The system reads this attribute to determine which activity should be started when
581 the use presses the Up button in the action bar. The system can also use this information to
582 synthesize a back stack of activities with {@link android.app.TaskStackBuilder}.</p>
585 This attribute was introduced in API Level 16.
591 <dt><a name="prmsn"></a>{@code android:permission}</dt>
592 <dd>The name of a permission that clients must have to launch the activity
593 or otherwise get it to respond to an intent. If a caller of
594 <code>{@link android.content.Context#startActivity startActivity()}</code> or
595 <code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code>
596 has not been granted the specified permission, its intent will not be
597 delivered to the activity.
600 If this attribute is not set, the permission set by the
601 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
603 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code>
604 attribute applies to the activity. If neither attribute is set, the activity is
605 not protected by a permission.
609 For more information on permissions, see the
610 <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a>
611 section in the introduction and another document,
612 <a href="{@docRoot}guide/topics/security/security.html">Security and
616 <dt><a name="proc"></a>{@code android:process}</dt>
617 <dd>The name of the process in which the activity should run. Normally,
618 all components of an application run in the default process created for the
619 application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's
620 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code>
621 attribute can set a different default for all components. But each component
622 can override the default, allowing you to spread your application across
626 If the name assigned to this attribute begins with a colon (':'), a new
627 process, private to the application, is created when it's needed and
628 the activity runs in that process.
629 If the process name begins with a lowercase character, the activity will run
630 in a global process of that name, provided that it has permission to do so.
631 This allows components in different applications to share a process, reducing
635 <dt><a name="screen"></a>{@code android:screenOrientation}</dt>
636 <dd>The orientation of the activity's display on the device.
638 <p>The value can be any one of the following strings:</p>
642 <td>"{@code unspecified}"</td>
643 <td>The default value. The system chooses the orientation. The policy it
644 uses, and therefore the choices made in specific contexts, may differ
645 from device to device.</td>
647 <td>"{@code user}"</td>
648 <td>The user's current preferred orientation.</td>
650 <td>"{@code behind}"</td>
651 <td>The same orientation as the activity that's immediately beneath it in
652 the activity stack.</td>
654 <td>"{@code landscape}"</td>
655 <td>Landscape orientation (the display is wider than it is tall).</td>
657 <td>"{@code portrait}"</td>
658 <td>Portrait orientation (the display is taller than it is wide).</td>
660 <td>"{@code reverseLandscape}"</td>
661 <td>Landscape orientation in the opposite direction from normal landscape.
662 <em>Added in API level 9.</em></td>
664 <td>"{@code reversePortrait}"</td>
665 <td>Portrait orientation in the opposite direction from normal portrait.
666 <em>Added in API level 9.</em></td>
668 <td>"{@code sensorLandscape}"</td>
669 <td>Landscape orientation, but can be either normal or reverse landscape based on the device
671 <em>Added in API level 9.</em></td>
673 <td>"{@code sensorPortrait}"</td>
674 <td>Portrait orientation, but can be either normal or reverse portrait based on the device
676 <em>Added in API level 9.</em></td>
678 <td>"{@code sensor}"</td>
679 <td>The orientation is determined by the device orientation sensor. The orientation of the
680 display depends on how the user is holding the device; it changes when the user rotates the
681 device. Some devices, though, will not rotate to all four possible orientations, by default. To
682 allow all four orientations, use {@code "fullSensor"}.</td>
684 <td>"{@code fullSensor}"</td>
685 <td>The orientation is determined by the device orientation sensor for any of the 4 orientations.
686 This is similar to {@code "sensor"} except this allows any of the 4 possible screen orientations,
687 regardless of what the device will normally do (for example, some devices won't normally use reverse
688 portrait or reverse landscape, but this enables those). <em>Added in API level 9.</em></td>
690 <td>"{@code nosensor}"</td>
691 <td>The orientation is determined without reference to a physical orientation sensor. The sensor
692 is ignored, so the display will not rotate based on how the user moves the device. Except for this
693 distinction, the system chooses the orientation using the same policy as for the "{@code
694 unspecified}" setting.</td>
698 <p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values,
699 it is considered a hard requirement for the orientation in which the activity runs. As such,
700 the value you declare enables filtering by services such as Google Play so your application is
701 available only to devices that support the orientation required by your activities. For
702 example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or
703 {@code "sensorLandscape"}, then your application will be available only to devices that support
704 landscape orientation. However, you should also explicitly declare that
705 your application requires either portrait or landscape orientation with the <a
706 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
707 element. For example, <code><uses-feature
708 android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior
709 provided by Google Play (and other services that support it) and the platform itself does not
710 control whether your app can be installed when a device supports only certain orientations.</p>
714 <dt><a name="state"></a>{@code android:stateNotNeeded}</dt>
715 <dd>Whether or not the activity can be killed and successfully restarted
716 without having saved its state — "{@code true}" if it can be restarted
717 without reference to its previous state, and "{@code false}" if its previous
718 state is required. The default value is "{@code false}".
721 Normally, before an activity is temporarily shut down to save resources, its
722 <code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code>
723 method is called. This method stores the current state of the activity in a
724 {@link android.os.Bundle} object, which is then passed to
725 <code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity
726 is restarted. If this attribute is set to "{@code true}",
727 {@code onSaveInstanceState()} may not be called and {@code onCreate()} will
728 be passed {@code null} instead of the Bundle — just as it was when the
729 activity started for the first time.
733 A "{@code true}" setting ensures that the activity can be restarted in the
734 absence of retained state. For example, the activity that displays the
735 home screen uses this setting to make sure that it does not get removed if it
736 crashes for some reason.
739 <dt><a name="aff"></a>{@code android:taskAffinity}</dt>
740 <dd>The task that the activity has an affinity for. Activities with
741 the same affinity conceptually belong to the same task (to the same
742 "application" from the user's perspective). The affinity of a task
743 is determined by the affinity of its root activity.
746 The affinity determines two things — the task that the activity is re-parented
747 to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code>
748 attribute) and the task that will house the activity when it is launched
749 with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code>
754 By default, all activities in an application have the same affinity. You
755 can set this attribute to group them differently, and even place
756 activities defined in different applications within the same task. To
757 specify that the activity does not have an affinity for any task, set
758 it to an empty string.
761 If this attribute is not set, the activity inherits the affinity set
762 for the application (see the
763 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
765 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code>
766 attribute). The name of the default affinity for an application is
767 the package name set by the
768 <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code>
772 <dt><a name="theme"></a>{@code android:theme}</dt>
773 <dd>A reference to a style resource defining an overall theme for the activity.
774 This automatically sets the activity's context to use this theme (see
775 <code>{@link android.content.Context#setTheme setTheme()}</code>, and may also
776 cause "starting" animations prior to the activity being launched (to better
777 match what the activity actually looks like).
780 If this attribute is not set, the activity inherits the theme set for the
781 application as a whole — from the
782 <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
784 <code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code>
785 attribute. If that attribute is also not set, the default system theme is used. For more
786 information, see the <a
787 href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide.
791 <!-- ##api level 14## -->
792 <dt><a name="uioptions"></a>{@code android:uiOptions}</dt>
793 <dd>Extra options for an activity's UI.
794 <p>Must be one of the following values.</p>
797 <tr><th>Value</th><th>Description</th></tr>
798 <tr><td>{@code "none"}</td><td>No extra UI options. This is the default.</td></tr>
799 <tr><td>{@code "splitActionBarWhenNarrow"}</td><td>Add a bar at
800 the bottom of the screen to display action items in the {@link android.app.ActionBar}, when
801 constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small
802 number of action items appearing in the action bar at the top of the screen, the action bar is
803 split into the top navigation section and the bottom bar for action items. This ensures a reasonable
804 amount of space is made available not only for the action items, but also for navigation and title
805 elements at the top. Menu items are not split across the two bars; they always appear
808 <p>For more information about the action bar, see the <a
809 href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p>
810 <p>This attribute was added in API level 14.</p>
814 <!-- ##api level 3## -->
815 <dt><a name="wsoft"></a>{@code android:windowSoftInputMode}</dt>
816 <dd>How the main window of the activity interacts with the window containing
817 the on-screen soft keyboard. The setting for this attribute affects two
821 <li>The state of the soft keyboard — whether it is hidden or visible
822 — when the activity becomes the focus of user attention.</li>
824 <li>The adjustment made to the activity's main window — whether it is
825 resized smaller to make room for the soft keyboard or whether its contents
826 pan to make the current focus visible when part of the window is covered by
827 the soft keyboard.</li>
831 The setting must be one of the values listed in the following table, or a
832 combination of one "{@code state...}" value plus one "{@code adjust...}"
833 value. Setting multiple values in either group — multiple
834 "{@code state...}" values, for example — has undefined results.
835 Individual values are separated by a vertical bar ({@code |}). For example:
838 <pre><activity android:windowSoftInputMode="stateVisible|adjustResize" . . . ></pre>
841 Values set here (other than "{@code stateUnspecified}" and
842 "{@code adjustUnspecified}") override values set in the theme.
850 <td>"{@code stateUnspecified}"</td>
851 <td>The state of the soft keyboard (whether it is hidden or visible)
852 is not specified. The system will choose an appropriate state or
853 rely on the setting in the theme.
856 This is the default setting for the behavior of the soft keyboard.
859 <td>"{@code stateUnchanged}"</td>
860 <td>The soft keyboard is kept in whatever state it was last in,
861 whether visible or hidden, when the activity comes to the fore.</td>
863 <td>"{@code stateHidden}"</td>
864 <td>The soft keyboard is hidden when the user chooses the activity
865 — that is, when the user affirmatively navigates forward to the
866 activity, rather than backs into it because of leaving another activity.</td>
868 <td>"{@code stateAlwaysHidden}"</td>
869 <td>The soft keyboard is always hidden when the activity's main window
870 has input focus.</td>
872 <td>"{@code stateVisible}"</td>
873 <td>The soft keyboard is visible when that's normally appropriate
874 (when the user is navigating forward to the activity's main window).</td>
876 <td>"{@code stateAlwaysVisible}"</td>
877 <td>The soft keyboard is made visible when the user chooses the
878 activity — that is, when the user affirmatively navigates forward
879 to the activity, rather than backs into it because of leaving another
882 <td>"{@code adjustUnspecified}"</td>
883 <td>It is unspecified whether the activity's main window resizes
884 to make room for the soft keyboard, or whether the contents
885 of the window pan to make the currentfocus visible on-screen.
886 The system will automatically select one of these modes depending
887 on whether the content of the window has any layout views that
888 can scroll their contents. If there is such a view, the window
889 will be resized, on the assumption that scrolling can make all
890 of the window's contents visible within a smaller area.
893 This is the default setting for the behavior of the main window.
896 <td>"{@code adjustResize}"</td>
897 <td>The activity's main window is always resized to make room for
898 the soft keyboard on screen.</td>
900 <td>"{@code adjustPan}"</td>
901 <td>The activity's main window is not resized to make room for the soft
902 keyboard. Rather, the contents of the window are automatically
903 panned so that the current focus is never obscured by the keyboard
904 and users can always see what they are typing. This is generally less
905 desirable than resizing, because the user may need to close the soft
906 keyboard to get at and interact with obscured parts of the window.</td>
911 This attribute was introduced in API Level 3.
915 <!-- ##api level indication## -->
916 <dt>introduced in:</dt>
917 <dd>API Level 1 for all attributes except for
918 <code><a href="#nohist">noHistory</a></code> and
919 <code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API
923 <dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code>
924 <br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code></dd>