activity-element.jd revision 4d06d970526b58ddaf8db89858615217fa88772b
1page.title=<activity> 2parent.title=The AndroidManifest.xml File 3parent.link=manifest-intro.html 4@jd:body 5 6<dl class="xml"> 7<dt>syntax:</dt> 8<dd><pre class="stx"><activity android:<a href="#embedded">allowEmbedded</a>=["true" | "false"] 9 android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] 10 android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] 11 android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"] 12 android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale", 13 "touchscreen", "keyboard", "keyboardHidden", 14 "navigation", "screenLayout", "fontScale", "uiMode", 15 "orientation", "screenSize", "smallestScreenSize"] 16 android:<a href="#enabled">enabled</a>=["true" | "false"] 17 android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"] 18 android:<a href="#exported">exported</a>=["true" | "false"] 19 android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"] 20 android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"] 21 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 22 android:<a href="#label">label</a>="<i>string resource</i>" 23 android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" | 24 "singleTask" | "singleInstance"] 25 android:<a href="#multi">multiprocess</a>=["true" | "false"] 26 android:<a href="#nm">name</a>="<i>string</i>" 27 android:<a href="#nohist">noHistory</a>=["true" | "false"] <!-- ##api level 3## --> 28 android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 --> 29 android:<a href="#prmsn">permission</a>="<i>string</i>" 30 android:<a href="#proc">process</a>="<i>string</i>" 31 android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" | 32 "landscape" | "portrait" | 33 "reverseLandscape" | "reversePortrait" | 34 "sensorLandscape" | "sensorPortrait" | 35 "userLandscape" | "userPortrait" | 36 "sensor" | "fullSensor" | "nosensor" | 37 "user" | "fullUser" | "locked"] 38 android:<a href="#state">stateNotNeeded</a>=["true" | "false"] 39 android:<a href="#aff">taskAffinity</a>="<i>string</i>" 40 android:<a href="#theme">theme</a>="<i>resource or theme</i>" 41 android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] 42 android:<a href="#wsoft">windowSoftInputMode</a>=["stateUnspecified", 43 "stateUnchanged", "stateHidden", 44 "stateAlwaysHidden", "stateVisible", 45 "stateAlwaysVisible", "adjustUnspecified", 46 "adjustResize", "adjustPan"] > <!-- ##api level 3## --> 47 . . . 48</activity></pre></dd> 49 50<dt>contained in:</dt> 51<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> 52 53<dt>can contain:</dt> 54<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> 55<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> 56 57<dt>description:</dt> 58<dd itemprop="description">Declares an activity (an {@link android.app.Activity} subclass) that 59implements part of the application's visual user interface. All activities 60must be represented by {@code <activity>} 61elements in the manifest file. Any that are not declared there will not be seen 62by the system and will never be run. 63 64<dt>attributes:</dt> 65<dd><dl class="attr"> 66<dt><a name="embedded"></a>{@code android:allowEmbedded}</dt> 67<dd> 68 Indicate that the activity can be launched as the embedded child of another 69 activity. Particularly in the case where the child lives in a container 70 such as a Display owned by another activity. For example, activities 71 that are used for Wear custom notifications must declare this so 72 Wear can display the activity in it's context stream, which resides 73 in another process. 74 75 <p>The default value of this attribute is <code>false</code>. 76</dd> 77<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> 78<dd>Whether or not the activity can move from the task that started it to 79the task it has an affinity for when that task is next brought to the 80front — "{@code true}" if it can move, and "{@code false}" if it 81must remain with the task where it started. 82 83<p> 84If this attribute is not set, the value set by the corresponding 85<code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code> 86attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element 87applies to the activity. The default value is "{@code false}". 88</p> 89 90<p> 91Normally when an activity is started, it's associated with the task of 92the activity that started it and it stays there for its entire lifetime. 93You can use this attribute to force it to be re-parented to the task it 94has an affinity for when its current task is no longer displayed. 95Typically, it's used to cause the activities of an application to move 96to the main task associated with that application. 97</p> 98 99<p> 100For example, if an e-mail message contains a link to a web page, clicking 101the link brings up an activity that can display the page. That activity 102is defined by the browser application, but is launched as part of the e-mail 103task. If it's reparented to the browser task, it will be shown when the 104browser next comes to the front, and will be absent when the e-mail task 105again comes forward. 106</p> 107 108<p> 109The affinity of an activity is defined by the 110<code><a href="#aff">taskAffinity</a></code> attribute. The affinity 111of a task is determined by reading the affinity of its root activity. 112Therefore, by definition, a root activity is always in a task with the 113same affinity. Since activities with "{@code singleTask}" or 114"{@code singleInstance}" launch modes can only be at the root of a task, 115re-parenting is limited to the "{@code standard}" and "{@code singleTop}" 116modes. (See also the <code><a href="#lmode">launchMode</a></code> 117attribute.) 118</p></dd> 119 120<dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt> 121<dd>Whether or not the state of the task that the activity is in will always 122be maintained by the system — "{@code true}" if it will be, and 123"{@code false}" if the system is allowed to reset the task to its initial 124state in certain situations. The default value is "{@code false}". This 125attribute is meaningful only for the root activity of a task; it's ignored 126for all other activities. 127 128<p> 129Normally, the system clears a task (removes all activities from the stack 130above the root activity) in certain situations when the user re-selects that 131task from the home screen. Typically, this is done if the user hasn't visited 132the task for a certain amount of time, such as 30 minutes. 133</p> 134 135<p> 136However, when this attribute is "{@code true}", users will always return 137to the task in its last state, regardless of how they get there. This is 138useful, for example, in an application like the web browser where there is 139a lot of state (such as multiple open tabs) that users would not like to lose. 140</p></dd> 141 142<dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> 143<dd>Whether or not all activities will be removed from the task, except for 144the root activity, whenever it is re-launched from the home screen — 145"{@code true}" if the task is always stripped down to its root activity, and 146"{@code false}" if not. The default value is "{@code false}". This attribute 147is meaningful only for activities that start a new task (the root activity); 148it's ignored for all other activities in the task. 149 150<p> 151When the value is "{@code true}", every time users start the task again, they 152are brought to its root activity regardless of what they were last doing in 153the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to 154leave it. When the value is "{@code false}", the task may be cleared of activities in 155some situations (see the 156<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. 157</p> 158 159<p> 160Suppose, for example, that someone launches activity P from the home screen, 161and from there goes to activity Q. The user next presses <em>Home</em>, and then returns 162to activity P. Normally, the user would see activity Q, since that is what they 163were last doing in P's task. However, if P set this flag to "{@code true}", all 164of the activities on top of it (Q in this case) were removed when the user pressed 165<em>Home</em> and the task went to the background. So the user sees only P when returning 166to the task. 167</p> 168 169<p> 170If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code> 171are both "{@code true}", any activities that can be re-parented are moved to 172the task they share an affinity with; the remaining activities are then dropped, 173as described above. 174</p></dd> 175 176<dt><a name="config"></a>{@code android:configChanges}</dt> 177<dd>Lists configuration changes that the activity will handle itself. When a configuration 178change occurs at runtime, the activity is shut down and restarted by default, but declaring a 179configuration with this attribute will prevent the activity from being restarted. Instead, the 180activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged 181onConfigurationChanged()}</code> method is called. 182 183<p class="note"><strong>Note:</strong> Using this attribute should be 184avoided and used only as a last resort. Please read <a 185href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more 186information about how to properly handle a restart due to a configuration change.</p> 187 188<p> 189Any or all of the following strings are valid values for this attribute. Multiple values are 190separated by '{@code |}' — for example, "{@code locale|navigation|orientation}". 191</p> 192 193<table> 194<tr> 195 <th>Value</th> 196 <th>Description</th> 197</tr><tr> 198 <td>"{@code mcc}"</td> 199 <td>The IMSI mobile country code (MCC) has changed — 200 a SIM has been detected and updated the MCC.</td> 201</tr><tr> 202 <td>"{@code mnc}"</td> 203 <td>The IMSI mobile network code (MNC) has changed — 204 a SIM has been detected and updated the MNC.</td> 205</tr><tr> 206 <td>"{@code locale}"</td> 207 <td>The locale has changed — the user has selected a new 208 language that text should be displayed in.</td> 209</tr><tr> 210 <td>"{@code touchscreen}"</td> 211 <td>The touchscreen has changed. (This should never normally happen.)</td> 212</tr><tr> 213 <td>"{@code keyboard}"</td> 214 <td>The keyboard type has changed — for example, the user has 215 plugged in an external keyboard.</td> 216</tr><tr> 217 <td>"{@code keyboardHidden}"</td> 218 <td>The keyboard accessibility has changed — for example, the 219 user has revealed the hardware keyboard.</td> 220</tr><tr> 221 <td>"{@code navigation}"</td> 222 <td>The navigation type (trackball/dpad) has changed. (This should never normally happen.)</td> 223</tr><tr> 224 <td>"{@code screenLayout}"</td> 225 <td>The screen layout has changed — this might be caused by a 226 different display being activated.</td> 227 </tr><tr> 228 <td>"{@code fontScale}"</td> 229 <td>The font scaling factor has changed — the user has selected 230 a new global font size.</td> 231 </tr><tr> 232 <td>"{@code uiMode}"</td> 233 <td>The user interface mode has changed — this can be caused when the user places the 234device into a desk/car dock or when the night mode changes. See {@link 235android.app.UiModeManager}. 236 <em>Added in API level 8</em>.</td> 237 </tr><tr> 238 <td>"{@code orientation}"</td> 239 <td>The screen orientation has changed — the user has rotated the device. 240 <p class="note"><strong>Note:</strong> If your application targets API level 13 or higher (as 241declared by the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 242minSdkVersion}</a> and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 243targetSdkVersion}</a> attributes), then you should also declare the {@code "screenSize"} 244configuration, because it also changes when a device switches between portrait and landscape 245orientations.</p></td> 246 </tr><tr> 247 <td>"{@code screenSize}"</td> 248 <td>The current available screen size has changed. This represents a change in the currently 249available size, relative to the current aspect ratio, so will change when the user switches between 250landscape and portrait. However, if your application targets API level 12 or lower, then your 251activity always handles this configuration change itself (this configuration change does not restart 252your activity, even when running on an Android 3.2 or higher device). 253 <p><em>Added in API level 13.</em></p></td> 254 </tr><tr> 255 <td>"{@code smallestScreenSize}"</td> 256 <td>The physical screen size has changed. This represents a change in size regardless of 257orientation, so will only change when the actual physical screen size has changed such as switching 258to an external display. A change to this configuration corresponds to a change in the <a 259href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> 260smallestWidth configuration</a>. However, if your application targets API level 12 or lower, then 261your activity always handles this configuration change itself (this configuration change does not 262restart your activity, even when running on an Android 3.2 or higher device). 263 <p><em>Added in API level 13.</em></p></td> 264 </tr><tr> 265 <td>"{@code layoutDirection}"</td> 266 <td>The layout direction has changed. For example, changing from left-to-right (LTR) 267 to right-to-left (RTL). 268 <em>Added in API level 17.</em></td> 269 </tr> 270</table> 271 272<p> 273All of these configuration changes can impact the resource values seen by the 274application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged 275onConfigurationChanged()}</code> is called, it will generally be necessary to again 276retrieve all resources (including view layouts, drawables, and so on) to correctly 277handle the change. 278</p></dd> 279 280<dt><a name="enabled"></a>{@code android:enabled}</dt> 281<dd>Whether or not the activity can be instantiated by the system — 282"{@code true}" if it can be, and "{@code false}" if not. The default value 283is "{@code true}". 284 285<p> 286The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own 287<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> 288attribute that applies to all application components, including activities. The 289<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 290and {@code <activity>} attributes must both be "{@code true}" (as they both 291are by default) for the system to be able to instantiate the activity. If either 292is "{@code false}", it cannot be instantiated. 293</p></dd> 294 295<dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt> 296<dd>Whether or not the task initiated by this activity should be excluded from the list of recently 297used applications ("recent apps"). That is, when this activity is the root activity of a new task, 298this attribute determines whether the task should not appear in the list of recent apps. Set "{@code 299true}" if the task should be <em>excluded</em> from the list; set "{@code false}" if it should be 300<em>included</em>. The default value is "{@code false}". 301</p></dd> 302 303<dt><a name="exported"></a>{@code android:exported}</dt> 304<dd>Whether or not the activity can be launched by components of other 305applications — "{@code true}" if it can be, and "{@code false}" if not. 306If "{@code false}", the activity can be launched only by components of the 307same application or applications with the same user ID. 308 309<p> 310The default value depends on whether the activity contains intent filters. The 311absence of any filters means that the activity can be invoked only by specifying 312its exact class name. This implies that the activity is intended only for 313application-internal use (since others would not know the class name). So in 314this case, the default value is "{@code false}". 315On the other hand, the presence of at least one filter implies that the activity 316is intended for external use, so the default value is "{@code true}". 317</p> 318 319<p> 320This attribute is not the only way to limit an activity's exposure to other 321applications. You can also use a permission to limit the external entities that 322can invoke the activity (see the 323<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code> 324attribute). 325</p></dd> 326 327<dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt> 328<dd>Whether or not an existing instance of the activity should be shut down 329(finished) whenever the user again launches its task (chooses the task on the 330home screen) — "{@code true}" if it should be shut down, and "{@code false}" 331if not. The default value is "{@code false}". 332 333<p> 334If this attribute and 335<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 336are both "{@code true}", this attribute trumps the other. The affinity of the 337activity is ignored. The activity is not re-parented, but destroyed. 338</p> 339 340<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt> 341<dd>Whether or not hardware-accelerated rendering should be enabled for this 342Activity — "{@code true}" if it should be enabled, and "{@code false}" if 343not. The default value is "{@code false}". 344 345 346<p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is 347available to applications, to improve performance for many common 2D graphics 348operations. When the hardware-accelerated renderer is enabled, most operations 349in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. 350This results in smoother animations, smoother scrolling, and improved 351responsiveness overall, even for applications that do not explicitly make use 352the framework's OpenGL libraries. Because of the increased resources required to 353enable hardware acceleration, your app will consume more RAM.</p> 354 355<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable 356the hardware-accelerated renderer, test your application to ensure that it can 357make use of the renderer without errors.</p> 358</dd> 359 360<dt><a name="icon"></a>{@code android:icon}</dt> 361<dd>An icon representing the activity. The icon is displayed to users when 362a representation of the activity is required on-screen. For example, icons 363for activities that initiate tasks are displayed in the launcher window. 364The icon is often accompanied by a label (see the <a href="#label">{@code 365android:label}</a> attribute). 366</p> 367 368<p> 369This attribute must be set as a reference to a drawable resource containing 370the image definition. If it is not set, the icon specified for the application 371as a whole is used instead (see the 372<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 373element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). 374</p> 375 376<p> 377The activity's icon — whether set here or by the 378<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 379element — is also the default icon for all the activity's intent filters (see the 380<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 381<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). 382</p></dd> 383 384<dt><a name="label"></a>{@code android:label}</dt> 385<dd>A user-readable label for the activity. The label is displayed on-screen 386when the activity must be represented to the user. It's often displayed along 387with the activity icon. 388 389<p> 390If this attribute is not set, the label set for the application as a whole is 391used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's 392<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). 393</p> 394 395<p> 396The activity's label — whether set here or by the 397<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the 398default label for all the activity's intent filters (see the 399<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's 400<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). 401</p> 402 403<p> 404The label should be set as a reference to a string resource, so that 405it can be localized like other strings in the user interface. 406However, as a convenience while you're developing the application, 407it can also be set as a raw string. 408</p></dd> 409 410<dt><a name="lmode"></a>{@code android:launchMode}</dt> 411<dd>An instruction on how the activity should be launched. There are four modes 412that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) 413in {@link android.content.Intent} objects to determine what should happen when 414the activity is called upon to handle an intent. They are:</p> 415 416<p style="margin-left: 2em">"{@code standard}" 417<br>"{@code singleTop}" 418<br>"{@code singleTask}" 419<br>"{@code singleInstance}"</p> 420 421<p> 422The default mode is "{@code standard}". 423</p> 424 425<p> 426As shown in the table below, the modes fall into two main groups, with 427"{@code standard}" and "{@code singleTop}" activities on one side, and 428"{@code singleTask}" and "{@code singleInstance}" activities on the other. 429An activity with the "{@code standard}" or "{@code singleTop}" launch mode 430can be instantiated multiple times. The instances can belong to any task 431and can be located anywhere in the activity stack. Typically, they're 432launched into the task that called 433<code>{@link android.content.Context#startActivity startActivity()}</code> 434(unless the Intent object contains a 435<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> 436instruction, in which case a different task is chosen — see the 437<a href="#aff">taskAffinity</a> attribute). 438</p> 439 440<p> 441In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities 442can only begin a task. They are always at the root of the activity stack. 443Moreover, the device can hold only one instance of the activity at a time 444— only one such task. 445</p> 446 447<p> 448The "{@code standard}" and "{@code singleTop}" modes differ from each other 449in just one respect: Every time there's a new intent for a "{@code standard}" 450activity, a new instance of the class is created to respond to that intent. 451Each instance handles a single intent. 452Similarly, a new instance of a "{@code singleTop}" activity may also be 453created to handle a new intent. However, if the target task already has an 454existing instance of the activity at the top of its stack, that instance 455will receive the new intent (in an 456{@link android.app.Activity#onNewIntent onNewIntent()} call); 457a new instance is not created. 458In other circumstances — for example, if an existing instance of the 459"{@code singleTop}" activity is in the target task, but not at the top of 460the stack, or if it's at the top of a stack, but not in the target task 461— a new instance would be created and pushed on the stack. 462</p> 463 464<p>Similarly, if you 465<a href="{@docRoot}training/implementing-navigation/ancestral.html">navigate 466up</a> to an activity on the current stack, the behavior is determined by the 467parent activity's launch mode. If the parent activity has launch mode {@code 468singleTop} (or the <code>up</code> intent contains {@link 469android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the parent is brought to the 470top of the stack, and its state is preserved. The navigation intent is received 471by the parent activity's {@link android.app.Activity#onNewIntent onNewIntent()} 472method. If the parent activity has launch mode {@code standard} (and the 473<code>up</code> intent does not contain {@link 474android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}), the current activity and its 475parent are both popped off the stack, and a new instance of the parent activity 476is created to receive the navigation intent. 477</p> 478 479 480<p> 481The "{@code singleTask}" and "{@code singleInstance}" modes also differ from 482each other in only one respect: A "{@code singleTask}" activity allows other 483activities to be part of its task. It's always at the root of its task, but 484other activities (necessarily "{@code standard}" and "{@code singleTop}" 485activities) can be launched into that task. A "{@code singleInstance}" 486activity, on the other hand, permits no other activities to be part of its task. 487It's the only activity in the task. If it starts another activity, that 488activity is assigned to a different task — as if {@code 489FLAG_ACTIVITY_NEW_TASK} was in the intent. 490</p> 491 492<table> 493<tr> 494<th>Use Cases</th> 495<th>Launch Mode</th> 496<th>Multiple Instances?</th> 497<th>Comments</th> 498</tr> 499<tr> 500<td rowspan="2" style="width:20%;">Normal launches for most activities</td> 501<td>"<code>standard</code>"</td> 502<td>Yes</td> 503<td>Default. The system always creates a new instance of the activity in the 504target task and routes the intent to it.</td> 505</tr> 506<tr> 507<td>"<code>singleTop</code>"</td> 508<td>Conditionally</td> 509<td>If an instance of the activity already exists at the top of the target task, 510the system routes the intent to that instance through a call to its {@link 511android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a 512new instance of the activity.</td> 513</tr> 514<tr> 515<td rowspan="2">Specialized launches<br> 516<em>(not recommended for general use)</em></td> 517<td>"<code>singleTask</code>"</td> 518<td>No</td> 519<td>The system creates the activity at the root of a new task and routes the 520intent to it. However, if an instance of the activity already exists, the system 521routes the intent to existing instance through a call to its {@link 522android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a 523new one.</td> 524</tr> 525<tr> 526<td>"<code>singleInstance</code>"</td> 527<td>No</td> 528<td>Same as "<code>singleTask"</code>, except that the system doesn't launch any 529other activities into the task holding the instance. The activity is always the 530single and only member of its task.</td> 531</tr> 532</table> 533 534<p>As shown in the table above, <code>standard</code> is the default mode and is 535appropriate for most types of activities. <code>SingleTop</code> is also a 536common and useful launch mode for many types of activities. The other modes 537— <code>singleTask</code> and <code>singleInstance</code> — are 538<span style="color:red">not appropriate for most applications</span>, 539since they result in an interaction model that is likely to be unfamiliar to 540users and is very different from most other applications. 541 542<p>Regardless of the launch mode that you choose, make sure to test the usability 543of the activity during launch and when navigating back to it from 544other activities and tasks using the <em>Back</em> button. </p> 545 546<p>For more information on launch modes and their interaction with Intent 547flags, see the 548<a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> 549document. 550</p> 551</dd> 552 553<dt><a name="multi"></a>{@code android:multiprocess}</dt> 554<dd>Whether an instance of the activity can be launched into the process of the component 555that started it — "{@code true}" if it can be, and "{@code false}" if not. 556The default value is "{@code false}". 557 558<p> 559Normally, a new instance of an activity is launched into the process of the 560application that defined it, so all instances of the activity run in the same 561process. However, if this flag is set to "{@code true}", instances of the 562activity can run in multiple processes, allowing the system to create instances 563wherever they are used (provided permissions allow it), something that is almost 564never necessary or desirable. 565</p></dd> 566 567<dt><a name="nm"></a>{@code android:name}</dt> 568<dd>The name of the class that implements the activity, a subclass of 569{@link android.app.Activity}. The attribute value should be a fully qualified 570class name (such as, "{@code com.example.project.ExtracurricularActivity}"). 571However, as a shorthand, if the first character of the name is a period 572(for example, "{@code .ExtracurricularActivity}"), it is appended to the 573package name specified in the 574<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 575element. 576<p>Once you publish your application, you <a 577href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not 578change this name</a> (unless you've set <code><a 579href="#exported">android:exported</a>="false"</code>).</p> 580 581<p> 582There is no default. The name must be specified. 583</p></dd> 584 585<!-- ##api level 3## --> 586<dt><a name="nohist"></a>{@code android:noHistory}</dt> 587<dd>Whether or not the activity should be removed from the activity stack and 588finished (its <code>{@link android.app.Activity#finish finish()}</code> 589method called) when the user navigates away from it and it's no longer 590visible on screen — "{@code true}" if it should be finished, and 591"{@code false}" if not. The default value is "{@code false}". 592 593<p> 594A value of "{@code true}" means that the activity will not leave a 595historical trace. It will not remain in the activity stack for the task, 596so the user will not be able to return to it. 597</p> 598 599<p> 600This attribute was introduced in API Level 3. 601</p> 602</dd> 603 604<!-- api level 16 --> 605<dt><a name="parent"></a>{@code android:parentActivityName}</dt> 606<dd>The class name of the logical parent of the activity. The name here must match the class 607 name given to the corresponding {@code <activity>} element's 608 <a href="#nm"><code>android:name</code></a> attribute. 609 610<p>The system reads this attribute to determine which activity should be started when 611 the use presses the Up button in the action bar. The system can also use this information to 612 synthesize a back stack of activities with {@link android.app.TaskStackBuilder}.</p> 613 614<p>To support API levels 4 - 16, you can also declare the parent activity with a {@code 615<meta-data>} element that specifies a value for {@code "android.support.PARENT_ACTIVITY"}. 616For example:</p> 617<pre> 618<activity 619 android:name="com.example.app.ChildActivity" 620 android:label="@string/title_child_activity" 621 android:parentActivityName="com.example.myfirstapp.MainActivity" > 622 <!-- Parent activity meta-data to support API level 4+ --> 623 <meta-data 624 android:name="android.support.PARENT_ACTIVITY" 625 android:value="com.example.app.MainActivity" /> 626</activity> 627</pre> 628 629<p>For more information about declaring the parent activity to support Up navigation, 630read <a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up 631Navigation</a>.</p> 632 633<p> 634This attribute was introduced in API Level 16. 635</p> 636</dd> 637 638 639 640<dt><a name="prmsn"></a>{@code android:permission}</dt> 641<dd>The name of a permission that clients must have to launch the activity 642or otherwise get it to respond to an intent. If a caller of 643<code>{@link android.content.Context#startActivity startActivity()}</code> or 644<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code> 645has not been granted the specified permission, its intent will not be 646delivered to the activity. 647 648<p> 649If this attribute is not set, the permission set by the 650<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 651element's 652<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> 653attribute applies to the activity. If neither attribute is set, the activity is 654not protected by a permission. 655</p> 656 657<p> 658For more information on permissions, see the 659<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 660section in the introduction and another document, 661<a href="{@docRoot}guide/topics/security/security.html">Security and 662Permissions</a>. 663</p></dd> 664 665<dt><a name="proc"></a>{@code android:process}</dt> 666<dd>The name of the process in which the activity should run. Normally, all components of an 667application run in a default process name created for the application and you do 668not need to use this attribute. But if necessary, you can override the default process 669name with this attribute, allowing you to spread your app components across 670multiple processes. 671 672<p> 673If the name assigned to this attribute begins with a colon (':'), a new 674process, private to the application, is created when it's needed and 675the activity runs in that process. 676If the process name begins with a lowercase character, the activity will run 677in a global process of that name, provided that it has permission to do so. 678This allows components in different applications to share a process, reducing 679resource usage. 680</p> 681 682<p>The <code><a href="{@docRoot}guide/topics/manifest/application-element.html" 683><application></a></code> element's 684<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> 685attribute can set a different default process name for all components. 686</dd> 687 688<dt><a name="screen"></a>{@code android:screenOrientation}</dt> 689<dd>The orientation of the activity's display on the device. 690 691<p>The value can be any one of the following strings:</p> 692 693<table> 694<tr> 695 <td>"{@code unspecified}"</td> 696 <td>The default value. The system chooses the orientation. The policy it 697 uses, and therefore the choices made in specific contexts, may differ 698 from device to device.</td> 699</tr><tr> 700 <td>"{@code behind}"</td> 701 <td>The same orientation as the activity that's immediately beneath it in 702 the activity stack.</td> 703</tr><tr> 704 <td>"{@code landscape}"</td> 705 <td>Landscape orientation (the display is wider than it is tall).</td> 706</tr><tr> 707 <td>"{@code portrait}"</td> 708 <td>Portrait orientation (the display is taller than it is wide).</td> 709</tr><tr> 710 <td>"{@code reverseLandscape}"</td> 711 <td>Landscape orientation in the opposite direction from normal landscape. 712<em>Added in API level 9.</em></td> 713</tr><tr> 714 <td>"{@code reversePortrait}"</td> 715 <td>Portrait orientation in the opposite direction from normal portrait. 716<em>Added in API level 9.</em></td> 717</tr><tr> 718 <td>"{@code sensorLandscape}"</td> 719 <td>Landscape orientation, but can be either normal or reverse landscape based on the device 720sensor. 721<em>Added in API level 9.</em></td> 722</tr><tr> 723 <td>"{@code sensorPortrait}"</td> 724 <td>Portrait orientation, but can be either normal or reverse portrait based on the device 725sensor. 726<em>Added in API level 9.</em></td> 727</tr><tr> 728 <td>"{@code userLandscape}"</td> 729 <td>Landscape orientation, but can be either normal or reverse landscape based on the device 730sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves 731the same as {@code landscape}, otherwise it behaves the same as {@code sensorLandscape}. 732<em>Added in API level 18.</em></td> 733</tr><tr> 734 <td>"{@code userPortrait}"</td> 735 <td>Portrait orientation, but can be either normal or reverse portrait based on the device 736sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves 737the same as {@code portrait}, otherwise it behaves the same as {@code sensorPortrait}. 738<em>Added in API level 18.</em></td> 739</tr><tr> 740 <td>"{@code sensor}"</td> 741 <td>The orientation is determined by the device orientation sensor. The orientation of the 742display depends on how the user is holding the device; it changes when the user rotates the 743device. Some devices, though, will not rotate to all four possible orientations, by default. To 744allow all four orientations, use {@code "fullSensor"}.</td> 745</tr><tr> 746 <td>"{@code fullSensor}"</td> 747 <td>The orientation is determined by the device orientation sensor for any of the 4 orientations. 748This is similar to {@code "sensor"} except this allows any of the 4 possible screen orientations, 749regardless of what the device will normally do (for example, some devices won't normally use reverse 750portrait or reverse landscape, but this enables those). <em>Added in API level 9.</em></td> 751</tr><tr> 752 <td>"{@code nosensor}"</td> 753 <td>The orientation is determined without reference to a physical orientation sensor. The sensor 754is ignored, so the display will not rotate based on how the user moves the device. Except for this 755distinction, the system chooses the orientation using the same policy as for the "{@code 756unspecified}" setting.</td> 757</tr><tr> 758 <td>"{@code user}"</td> 759 <td>The user's current preferred orientation.</td> 760</tr><tr> 761 <td>"{@code fullUser}"</td> 762 <td>If the user has locked sensor-based rotation, this behaves the same as {@code user}, 763 otherwise it behaves the same as {@code fullSensor} and allows any of the 4 possible 764 screen orientations. 765 <em>Added in API level 18.</em></td> 766</tr><tr> 767 <td>"{@code locked}"</td> 768 <td>Locks the orientation to its current rotation, whatever that is. 769<em>Added in API level 18.</em></td> 770</tr> 771</table> 772 773<p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values, 774it is considered a hard requirement for the orientation in which the activity runs. As such, 775the value you declare enables filtering by services such as Google Play so your application is 776available only to devices that support the orientation required by your activities. For 777example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or 778{@code "sensorLandscape"}, then your application will be available only to devices that support 779landscape orientation. However, you should also explicitly declare that 780your application requires either portrait or landscape orientation with the <a 781href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 782element. For example, <code><uses-feature 783android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior 784provided by Google Play (and other services that support it) and the platform itself does not 785control whether your app can be installed when a device supports only certain orientations.</p> 786 787</dd> 788 789<dt><a name="state"></a>{@code android:stateNotNeeded}</dt> 790<dd>Whether or not the activity can be killed and successfully restarted 791without having saved its state — "{@code true}" if it can be restarted 792without reference to its previous state, and "{@code false}" if its previous 793state is required. The default value is "{@code false}". 794 795<p> 796Normally, before an activity is temporarily shut down to save resources, its 797<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code> 798method is called. This method stores the current state of the activity in a 799{@link android.os.Bundle} object, which is then passed to 800<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity 801is restarted. If this attribute is set to "{@code true}", 802{@code onSaveInstanceState()} may not be called and {@code onCreate()} will 803be passed {@code null} instead of the Bundle — just as it was when the 804activity started for the first time. 805</p> 806 807<p> 808A "{@code true}" setting ensures that the activity can be restarted in the 809absence of retained state. For example, the activity that displays the 810home screen uses this setting to make sure that it does not get removed if it 811crashes for some reason. 812</p></dd> 813 814<dt><a name="aff"></a>{@code android:taskAffinity}</dt> 815<dd>The task that the activity has an affinity for. Activities with 816the same affinity conceptually belong to the same task (to the same 817"application" from the user's perspective). The affinity of a task 818is determined by the affinity of its root activity. 819 820<p> 821The affinity determines two things — the task that the activity is re-parented 822to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 823attribute) and the task that will house the activity when it is launched 824with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> 825flag. 826</p> 827 828<p> 829By default, all activities in an application have the same affinity. You 830can set this attribute to group them differently, and even place 831activities defined in different applications within the same task. To 832specify that the activity does not have an affinity for any task, set 833it to an empty string. 834 835<p> 836If this attribute is not set, the activity inherits the affinity set 837for the application (see the 838<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 839element's 840<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code> 841attribute). The name of the default affinity for an application is 842the package name set by the 843<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 844element. 845</p> 846 847<dt><a name="theme"></a>{@code android:theme}</dt> 848<dd>A reference to a style resource defining an overall theme for the activity. 849This automatically sets the activity's context to use this theme (see 850<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also 851cause "starting" animations prior to the activity being launched (to better 852match what the activity actually looks like). 853 854<p> 855If this attribute is not set, the activity inherits the theme set for the 856application as a whole — from the 857<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 858element's 859<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code> 860attribute. If that attribute is also not set, the default system theme is used. For more 861information, see the <a 862href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. 863</p> 864<dd> 865 866<!-- ##api level 14## --> 867<dt><a name="uioptions"></a>{@code android:uiOptions}</dt> 868<dd>Extra options for an activity's UI. 869 <p>Must be one of the following values.</p> 870 871 <table> 872 <tr><th>Value</th><th>Description</th></tr> 873 <tr><td>{@code "none"}</td><td>No extra UI options. This is the default.</td></tr> 874 <tr><td>{@code "splitActionBarWhenNarrow"}</td><td>Add a bar at 875the bottom of the screen to display action items in the {@link android.app.ActionBar}, when 876constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small 877number of action items appearing in the action bar at the top of the screen, the action bar is 878split into the top navigation section and the bottom bar for action items. This ensures a reasonable 879amount of space is made available not only for the action items, but also for navigation and title 880elements at the top. Menu items are not split across the two bars; they always appear 881together.</td></tr> 882 </table> 883 <p>For more information about the action bar, see the <a 884href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p> 885 <p>This attribute was added in API level 14.</p> 886</dd> 887 888 889<!-- ##api level 3## --> 890<dt><a name="wsoft"></a>{@code android:windowSoftInputMode}</dt> 891<dd>How the main window of the activity interacts with the window containing 892the on-screen soft keyboard. The setting for this attribute affects two 893things: 894 895<ul> 896<li>The state of the soft keyboard — whether it is hidden or visible 897— when the activity becomes the focus of user attention.</li> 898 899<li>The adjustment made to the activity's main window — whether it is 900resized smaller to make room for the soft keyboard or whether its contents 901pan to make the current focus visible when part of the window is covered by 902the soft keyboard.</li> 903</ul> 904 905<p> 906The setting must be one of the values listed in the following table, or a 907combination of one "{@code state...}" value plus one "{@code adjust...}" 908value. Setting multiple values in either group — multiple 909"{@code state...}" values, for example — has undefined results. 910Individual values are separated by a vertical bar ({@code |}). For example: 911</p> 912 913<pre><activity android:windowSoftInputMode="stateVisible|adjustResize" . . . ></pre> 914 915<p> 916Values set here (other than "{@code stateUnspecified}" and 917"{@code adjustUnspecified}") override values set in the theme. 918</p> 919 920<table> 921<tr> 922 <th>Value</th> 923 <th>Description</th> 924</tr><tr> 925 <td>"{@code stateUnspecified}"</td> 926 <td>The state of the soft keyboard (whether it is hidden or visible) 927 is not specified. The system will choose an appropriate state or 928 rely on the setting in the theme. 929 930 <p> 931 This is the default setting for the behavior of the soft keyboard. 932 </p></td> 933</tr></tr> 934 <td>"{@code stateUnchanged}"</td> 935 <td>The soft keyboard is kept in whatever state it was last in, 936 whether visible or hidden, when the activity comes to the fore.</td> 937</tr></tr> 938 <td>"{@code stateHidden}"</td> 939 <td>The soft keyboard is hidden when the user chooses the activity 940 — that is, when the user affirmatively navigates forward to the 941 activity, rather than backs into it because of leaving another activity.</td> 942</tr></tr> 943 <td>"{@code stateAlwaysHidden}"</td> 944 <td>The soft keyboard is always hidden when the activity's main window 945 has input focus.</td> 946</tr></tr> 947 <td>"{@code stateVisible}"</td> 948 <td>The soft keyboard is visible when that's normally appropriate 949 (when the user is navigating forward to the activity's main window).</td> 950</tr></tr> 951 <td>"{@code stateAlwaysVisible}"</td> 952 <td>The soft keyboard is made visible when the user chooses the 953 activity — that is, when the user affirmatively navigates forward 954 to the activity, rather than backs into it because of leaving another 955 activity.</td> 956</tr></tr> 957 <td>"{@code adjustUnspecified}"</td> 958 <td>It is unspecified whether the activity's main window resizes 959 to make room for the soft keyboard, or whether the contents 960 of the window pan to make the current focus visible on-screen. 961 The system will automatically select one of these modes depending 962 on whether the content of the window has any layout views that 963 can scroll their contents. If there is such a view, the window 964 will be resized, on the assumption that scrolling can make all 965 of the window's contents visible within a smaller area. 966 967 <p> 968 This is the default setting for the behavior of the main window. 969 </p></td> 970</tr></tr> 971 <td>"{@code adjustResize}"</td> 972 <td>The activity's main window is always resized to make room for 973 the soft keyboard on screen.</td> 974</tr></tr> 975 <td>"{@code adjustPan}"</td> 976 <td>The activity's main window is not resized to make room for the soft 977 keyboard. Rather, the contents of the window are automatically 978 panned so that the current focus is never obscured by the keyboard 979 and users can always see what they are typing. This is generally less 980 desirable than resizing, because the user may need to close the soft 981 keyboard to get at and interact with obscured parts of the window.</td> 982</tr> 983</table> 984 985<p> 986This attribute was introduced in API Level 3. 987</p></dd> 988</dl></dd> 989 990<!-- ##api level indication## --> 991<dt>introduced in:</dt> 992<dd>API Level 1 for all attributes except for 993<code><a href="#nohist">noHistory</a></code> and 994<code><a href="#wsoft">windowSoftInputMode</a></code>, which were added in API 995Level 3.</dd> 996 997<dt>see also:</dt> 998<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 999<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code></dd> 1000</dl> 1001