activity-element.jd revision 22d17c984ae91e85a67d3fc03c092538c5080b0f
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="#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## --> 44 . . . 45</activity></pre></dd> 46 47<dt>contained in:</dt> 48<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> 49 50<dt>can contain:</dt> 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> 53 54<dt>description:</dt> 55<dd>Declares an activity (an {@link android.app.Activity} subclass) that 56implements part of the application's visual user interface. All activities 57must be represented by {@code <activity>} 58elements in the manifest file. Any that are not declared there will not be seen 59by the system and will never be run. 60 61<dt>attributes:</dt> 62<dd><dl class="attr"> 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 65the task it has an affinity for when that task is next brought to the 66front — "{@code true}" if it can move, and "{@code false}" if it 67must remain with the task where it started. 68 69<p> 70If 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> 72attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element 73applies to the activity. The default value is "{@code false}". 74</p> 75 76<p> 77Normally when an activity is started, it's associated with the task of 78the activity that started it and it stays there for its entire lifetime. 79You can use this attribute to force it to be re-parented to the task it 80has an affinity for when its current task is no longer displayed. 81Typically, it's used to cause the activities of an application to move 82to the main task associated with that application. 83</p> 84 85<p> 86For example, if an e-mail message contains a link to a web page, clicking 87the link brings up an activity that can display the page. That activity 88is defined by the browser application, but is launched as part of the e-mail 89task. If it's reparented to the browser task, it will be shown when the 90browser next comes to the front, and will be absent when the e-mail task 91again comes forward. 92</p> 93 94<p> 95The affinity of an activity is defined by the 96<code><a href="#aff">taskAffinity</a></code> attribute. The affinity 97of a task is determined by reading the affinity of its root activity. 98Therefore, by definition, a root activity is always in a task with the 99same affinity. Since activities with "{@code singleTask}" or 100"{@code singleInstance}" launch modes can only be at the root of a task, 101re-parenting is limited to the "{@code standard}" and "{@code singleTop}" 102modes. (See also the <code><a href="#lmode">launchMode</a></code> 103attribute.) 104</p></dd> 105 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 108be 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 110state in certain situations. The default value is "{@code false}". This 111attribute is meaningful only for the root activity of a task; it's ignored 112for all other activities. 113 114<p> 115Normally, the system clears a task (removes all activities from the stack 116above the root activity) in certain situations when the user re-selects that 117task from the home screen. Typically, this is done if the user hasn't visited 118the task for a certain amount of time, such as 30 minutes. 119</p> 120 121<p> 122However, when this attribute is "{@code true}", users will always return 123to the task in its last state, regardless of how they get there. This is 124useful, for example, in an application like the web browser where there is 125a lot of state (such as multiple open tabs) that users would not like to lose. 126</p></dd> 127 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 130the 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 133is meaningful only for activities that start a new task (the root activity); 134it's ignored for all other activities in the task. 135 136<p> 137When the value is "{@code true}", every time users start the task again, they 138are brought to its root activity regardless of what they were last doing in 139the task and regardless of whether they used the <em>Back</em> or <em>Home</em> button to 140leave it. When the value is "{@code false}", the task may be cleared of activities in 141some situations (see the 142<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. 143</p> 144 145<p> 146Suppose, for example, that someone launches activity P from the home screen, 147and from there goes to activity Q. The user next presses <em>Home</em>, and then returns 148to activity P. Normally, the user would see activity Q, since that is what they 149were last doing in P's task. However, if P set this flag to "{@code true}", all 150of 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 152to the task. 153</p> 154 155<p> 156If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code> 157are both "{@code true}", any activities that can be re-parented are moved to 158the task they share an affinity with; the remaining activities are then dropped, 159as described above. 160</p></dd> 161 162<dt><a name="config"></a>{@code android:configChanges}</dt> 163<dd>Lists configuration changes that the activity will handle itself. When a configuration 164change occurs at runtime, the activity is shut down and restarted by default, but declaring a 165configuration with this attribute will prevent the activity from being restarted. Instead, the 166activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged 167onConfigurationChanged()}</code> method is called. 168 169<p class="note"><strong>Note:</strong> Using this attribute should be 170avoided and used only as a last-resort. Please read <a 171href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a> for more 172information about how to properly handle a restart due to a configuration change.</p> 173 174<p> 175Any or all of the following strings are valid values for this attribute. Multiple values are 176separated by '{@code |}' — for example, "{@code locale|navigation|orientation}". 177</p> 178 179<table> 180<tr> 181 <th>Value</th> 182 <th>Description</th> 183</tr><tr> 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> 187</tr><tr> 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> 191</tr><tr> 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> 195</tr><tr> 196 <td>"{@code touchscreen}"</td> 197 <td>The touchscreen has changed. (This should never normally happen.)</td> 198</tr><tr> 199 <td>"{@code keyboard}"</td> 200 <td>The keyboard type has changed — for example, the user has 201 plugged in an external keyboard.</td> 202</tr><tr> 203 <td>"{@code keyboardHidden}"</td> 204 <td>The keyboard accessibility has changed — for example, the 205 user has revealed the hardware keyboard.</td> 206</tr><tr> 207 <td>"{@code navigation}"</td> 208 <td>The navigation type (trackball/dpad) has changed. (This should never normally happen.)</td> 209</tr><tr> 210 <td>"{@code screenLayout}"</td> 211 <td>The screen layout has changed — this might be caused by a 212 different display being activated.</td> 213 </tr><tr> 214 <td>"{@code fontScale}"</td> 215 <td>The font scaling factor has changed — the user has selected 216 a new global font size.</td> 217 </tr><tr> 218 <td>"{@code uiMode}"</td> 219 <td>The user interface mode has changed — this can be caused when the user places the 220device into a desk/car dock or when the the night mode changes. See {@link 221android.app.UiModeManager}. 222 <em>Added in API level 8</em>.</td> 223 </tr><tr> 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 227declared by the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 228minSdkVersion}</a> and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 229targetSdkVersion}</a> attributes), then you should also declare the {@code "screenSize"} 230configuration, because it also changes when a device switches between portrait and landscape 231orientations.</p></td> 232 </tr><tr> 233 <td>"{@code screenSize}"</td> 234 <td>The current available screen size has changed. This represents a change in the currently 235available size, relative to the current aspect ratio, so will change when the user switches between 236landscape and portrait. However, if your application targets API level 12 or lower, then your 237activity always handles this configuration change itself (this configuration change does not restart 238your activity, even when running on an Android 3.2 or higher device). 239 <p><em>Added in API level 13.</em></p></td> 240 </tr><tr> 241 <td>"{@code smallestScreenSize}"</td> 242 <td>The physical screen size has changed. This represents a change in size regardless of 243orientation, so will only change when the actual physical screen size has changed such as switching 244to an external display. A change to this configuration corresponds to a change in the <a 245href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> 246smallestWidth configuration</a>. However, if your application targets API level 12 or lower, then 247your activity always handles this configuration change itself (this configuration change does not 248restart your activity, even when running on an Android 3.2 or higher device). 249 <p><em>Added in API level 13.</em></p></td> 250 </tr><tr> 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> 255 </tr> 256</table> 257 258<p> 259All of these configuration changes can impact the resource values seen by the 260application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged 261onConfigurationChanged()}</code> is called, it will generally be necessary to again 262retrieve all resources (including view layouts, drawables, and so on) to correctly 263handle the change. 264</p></dd> 265 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 269is "{@code true}". 270 271<p> 272The <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> 274attribute that applies to all application components, including activities. The 275<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 276and {@code <activity>} attributes must both be "{@code true}" (as they both 277are by default) for the system to be able to instantiate the activity. If either 278is "{@code false}", it cannot be instantiated. 279</p></dd> 280 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 283used applications ("recent apps"). That is, when this activity is the root activity of a new task, 284this attribute determines whether the task should not appear in the list of recent apps. "{@code 285true}" 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}". 287</p></dd> 288 289<dt><a name="exported"></a>{@code android:exported}</dt> 290<dd>Whether or not the activity can be launched by components of other 291applications — "{@code true}" if it can be, and "{@code false}" if not. 292If "{@code false}", the activity can be launched only by components of the 293same application or applications with the same user ID. 294 295<p> 296The default value depends on whether the activity contains intent filters. The 297absence of any filters means that the activity can be invoked only by specifying 298its exact class name. This implies that the activity is intended only for 299application-internal use (since others would not know the class name). So in 300this case, the default value is "{@code false}". 301On the other hand, the presence of at least one filter implies that the activity 302is intended for external use, so the default value is "{@code true}". 303</p> 304 305<p> 306This attribute is not the only way to limit an activity's exposure to other 307applications. You can also use a permission to limit the external entities that 308can invoke the activity (see the 309<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code> 310attribute). 311</p></dd> 312 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 316home screen) — "{@code true}" if it should be shut down, and "{@code false}" 317if not. The default value is "{@code false}". 318 319<p> 320If this attribute and 321<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 322are both "{@code true}", this attribute trumps the other. The affinity of the 323activity is ignored. The activity is not re-parented, but destroyed. 324</p> 325 326<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt> 327<dd>Whether or not hardware-accelerated rendering should be enabled for this 328Activity — "{@code true}" if it should be enabled, and "{@code false}" if 329not. The default value is "{@code false}". 330 331 332<p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is 333available to applications, to improve performance for many common 2D graphics 334operations. When the hardware-accelerated renderer is enabled, most operations 335in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. 336This results in smoother animations, smoother scrolling, and improved 337responsiveness overall, even for applications that do not explicitly make use 338the framework's OpenGL libraries. Because of the increased resources required to 339enable hardware acceleration, your app will consume more RAM.</p> 340 341<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable 342the hardware-accelerated renderer, test your application to ensure that it can 343make use of the renderer without errors.</p> 344</dd> 345 346<dt><a name="icon"></a>{@code android:icon}</dt> 347<dd>An icon representing the activity. The icon is displayed to users when 348a representation of the activity is required on-screen. For example, icons 349for activities that initiate tasks are displayed in the launcher window. 350The icon is often accompanied by a label (see the <a href="#label">{@code 351android:label}</a> attribute). 352</p> 353 354<p> 355This attribute must be set as a reference to a drawable resource containing 356the image definition. If it is not set, the icon specified for the application 357as a whole is used instead (see the 358<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 359element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). 360</p> 361 362<p> 363The activity's icon — whether set here or by the 364<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 365element — 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). 368</p></dd> 369 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 372when the activity must be represented to the user. It's often displayed along 373with the activity icon. 374 375<p> 376If this attribute is not set, the label set for the application as a whole is 377used 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). 379</p> 380 381<p> 382The 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 384default 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). 387</p> 388 389<p> 390The label should be set as a reference to a string resource, so that 391it can be localized like other strings in the user interface. 392However, as a convenience while you're developing the application, 393it can also be set as a raw string. 394</p></dd> 395 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 398that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) 399in {@link android.content.Intent} objects to determine what should happen when 400the activity is called upon to handle an intent. They are:</p> 401 402<p style="margin-left: 2em">"{@code standard}" 403<br>"{@code singleTop}" 404<br>"{@code singleTask}" 405<br>"{@code singleInstance}"</p> 406 407<p> 408The default mode is "{@code standard}". 409</p> 410 411<p> 412As 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. 415An activity with the "{@code standard}" or "{@code singleTop}" launch mode 416can be instantiated multiple times. The instances can belong to any task 417and can be located anywhere in the activity stack. Typically, they're 418launched 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> 422instruction, in which case a different task is chosen — see the 423<a href="#aff">taskAffinity</a> attribute). 424</p> 425 426<p> 427In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities 428can only begin a task. They are always at the root of the activity stack. 429Moreover, the device can hold only one instance of the activity at a time 430— only one such task. 431</p> 432 433<p> 434The "{@code standard}" and "{@code singleTop}" modes differ from each other 435in just one respect: Every time there's a new intent for a "{@code standard}" 436activity, a new instance of the class is created to respond to that intent. 437Each instance handles a single intent. 438Similarly, a new instance of a "{@code singleTop}" activity may also be 439created to handle a new intent. However, if the target task already has an 440existing instance of the activity at the top of its stack, that instance 441will receive the new intent (in an 442<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call); 443a new instance is not created. 444In 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 446the 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. 448</p> 449 450<p> 451The "{@code singleTask}" and "{@code singleInstance}" modes also differ from 452each other in only one respect: A "{@code singleTask}" activity allows other 453activities to be part of its task. It's always at the root of its task, but 454other activities (necessarily "{@code standard}" and "{@code singleTop}" 455activities) can be launched into that task. A "{@code singleInstance}" 456activity, on the other hand, permits no other activities to be part of its task. 457It's the only activity in the task. If it starts another activity, that 458activity is assigned to a different task — as if {@code 459FLAG_ACTIVITY_NEW_TASK} was in the intent. 460</p> 461 462<table> 463<tr> 464<th>Use Cases</th> 465<th>Launch Mode</th> 466<th>Multiple Instances?</th> 467<th>Comments</th> 468</tr> 469<tr> 470<td rowspan="2" style="width:20%;">Normal launches for most activities</td> 471<td>"<code>standard</code>"</td> 472<td>Yes</td> 473<td>Default. The system always creates a new instance of the activity in the 474target task and routes the intent to it.</td> 475</tr> 476<tr> 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, 480the system routes the intent to that instance through a call to its {@link 481android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a 482new instance of the activity.</td> 483</tr> 484<tr> 485<td rowspan="2">Specialized launches<br> 486<em>(not recommended for general use)</em></td> 487<td>"<code>singleTask</code>"</td> 488<td>No</td> 489<td>The system creates the activity at the root of a new task and routes the 490intent to it. However, if an instance of the activity already exists, the system 491routes the intent to existing instance through a call to its {@link 492android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a 493new one.</td> 494</tr> 495<tr> 496<td>"<code>singleInstance</code>"</td> 497<td>No</td> 498<td>Same as "<code>singleTask"</code>, except that the system doesn't launch any 499other activities into the task holding the instance. The activity is always the 500single and only member of its task.</td> 501</tr> 502</table> 503 504<p>As shown in the table above, <code>standard</code> is the default mode and is 505appropriate for most types of activities. <code>SingleTop</code> is also a 506common 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>, 509since they result in an interaction model that is likely to be unfamiliar to 510users and is very different from most other applications. 511 512<p>Regardless of the launch mode that you choose, make sure to test the usability 513of the activity during launch and when navigating back to it from 514other activities and tasks using the <em>Back</em> button. </p> 515 516<p>For more information on launch modes and their interaction with Intent 517flags, see the 518<a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> 519document. 520</p> 521</dd> 522 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 525that started it — "{@code true}" if it can be, and "{@code false}" if not. 526The default value is "{@code false}". 527 528<p> 529Normally, a new instance of an activity is launched into the process of the 530application that defined it, so all instances of the activity run in the same 531process. However, if this flag is set to "{@code true}", instances of the 532activity can run in multiple processes, allowing the system to create instances 533wherever they are used (provided permissions allow it), something that is almost 534never necessary or desirable. 535</p></dd> 536 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 540class name (such as, "{@code com.example.project.ExtracurricularActivity}"). 541However, as a shorthand, if the first character of the name is a period 542(for example, "{@code .ExtracurricularActivity}"), it is appended to the 543package name specified in the 544<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 545element. 546<p>Once you publish your application, you <a 547href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not 548change this name</a> (unless you've set <code><a 549href="#exported">android:exported</a>="false"</code>).</p> 550 551<p> 552There is no default. The name must be specified. 553</p></dd> 554 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 558finished (its <code>{@link android.app.Activity#finish finish()}</code> 559method called) when the user navigates away from it and it's no longer 560visible on screen — "{@code true}" if it should be finished, and 561"{@code false}" if not. The default value is "{@code false}". 562 563<p> 564A value of "{@code true}" means that the activity will not leave a 565historical trace. It will not remain in the activity stack for the task, 566so the user will not be able to return to it. 567</p> 568 569<p> 570This attribute was introduced in API Level 3. 571</p> 572</dd> 573 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>. 579 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> 583 584<p> 585This attribute was introduced in API Level 16. 586</p> 587</dd> 588 589 590 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 593or 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> 596has not been granted the specified permission, its intent will not be 597delivered to the activity. 598 599<p> 600If this attribute is not set, the permission set by the 601<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 602element's 603<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> 604attribute applies to the activity. If neither attribute is set, the activity is 605not protected by a permission. 606</p> 607 608<p> 609For more information on permissions, see the 610<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 611section in the introduction and another document, 612<a href="{@docRoot}guide/topics/security/security.html">Security and 613Permissions</a>. 614</p></dd> 615 616<dt><a name="proc"></a>{@code android:process}</dt> 617<dd>The name of the process in which the activity should run. Normally, 618all components of an application run in the default process created for the 619application. 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> 621attribute can set a different default for all components. But each component 622can override the default, allowing you to spread your application across 623multiple processes. 624 625<p> 626If the name assigned to this attribute begins with a colon (':'), a new 627process, private to the application, is created when it's needed and 628the activity runs in that process. 629If the process name begins with a lowercase character, the activity will run 630in a global process of that name, provided that it has permission to do so. 631This allows components in different applications to share a process, reducing 632resource usage. 633</p></dd> 634 635<dt><a name="screen"></a>{@code android:screenOrientation}</dt> 636<dd>The orientation of the activity's display on the device. 637 638<p>The value can be any one of the following strings:</p> 639 640<table> 641<tr> 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> 646</tr><tr> 647 <td>"{@code user}"</td> 648 <td>The user's current preferred orientation.</td> 649</tr><tr> 650 <td>"{@code behind}"</td> 651 <td>The same orientation as the activity that's immediately beneath it in 652 the activity stack.</td> 653</tr><tr> 654 <td>"{@code landscape}"</td> 655 <td>Landscape orientation (the display is wider than it is tall).</td> 656</tr><tr> 657 <td>"{@code portrait}"</td> 658 <td>Portrait orientation (the display is taller than it is wide).</td> 659</tr><tr> 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> 663</tr><tr> 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> 667</tr><tr> 668 <td>"{@code sensorLandscape}"</td> 669 <td>Landscape orientation, but can be either normal or reverse landscape based on the device 670sensor. 671<em>Added in API level 9.</em></td> 672</tr><tr> 673 <td>"{@code sensorPortrait}"</td> 674 <td>Portrait orientation, but can be either normal or reverse portrait based on the device 675sensor. 676<em>Added in API level 9.</em></td> 677</tr><tr> 678 <td>"{@code sensor}"</td> 679 <td>The orientation is determined by the device orientation sensor. The orientation of the 680display depends on how the user is holding the device; it changes when the user rotates the 681device. Some devices, though, will not rotate to all four possible orientations, by default. To 682allow all four orientations, use {@code "fullSensor"}.</td> 683</tr><tr> 684 <td>"{@code fullSensor}"</td> 685 <td>The orientation is determined by the device orientation sensor for any of the 4 orientations. 686This is similar to {@code "sensor"} except this allows any of the 4 possible screen orientations, 687regardless of what the device will normally do (for example, some devices won't normally use reverse 688portrait or reverse landscape, but this enables those). <em>Added in API level 9.</em></td> 689</tr><tr> 690 <td>"{@code nosensor}"</td> 691 <td>The orientation is determined without reference to a physical orientation sensor. The sensor 692is ignored, so the display will not rotate based on how the user moves the device. Except for this 693distinction, the system chooses the orientation using the same policy as for the "{@code 694unspecified}" setting.</td> 695</tr> 696</table> 697 698<p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values, 699it is considered a hard requirement for the orientation in which the activity runs. As such, 700the value you declare enables filtering by services such as Google Play so your application is 701available only to devices that support the orientation required by your activities. For 702example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or 703{@code "sensorLandscape"}, then your application will be available only to devices that support 704landscape orientation. However, you should also explicitly declare that 705your application requires either portrait or landscape orientation with the <a 706href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 707element. For example, <code><uses-feature 708android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior 709provided by Google Play (and other services that support it) and the platform itself does not 710control whether your app can be installed when a device supports only certain orientations.</p> 711 712</dd> 713 714<dt><a name="state"></a>{@code android:stateNotNeeded}</dt> 715<dd>Whether or not the activity can be killed and successfully restarted 716without having saved its state — "{@code true}" if it can be restarted 717without reference to its previous state, and "{@code false}" if its previous 718state is required. The default value is "{@code false}". 719 720<p> 721Normally, before an activity is temporarily shut down to save resources, its 722<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code> 723method 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 726is restarted. If this attribute is set to "{@code true}", 727{@code onSaveInstanceState()} may not be called and {@code onCreate()} will 728be passed {@code null} instead of the Bundle — just as it was when the 729activity started for the first time. 730</p> 731 732<p> 733A "{@code true}" setting ensures that the activity can be restarted in the 734absence of retained state. For example, the activity that displays the 735home screen uses this setting to make sure that it does not get removed if it 736crashes for some reason. 737</p></dd> 738 739<dt><a name="aff"></a>{@code android:taskAffinity}</dt> 740<dd>The task that the activity has an affinity for. Activities with 741the same affinity conceptually belong to the same task (to the same 742"application" from the user's perspective). The affinity of a task 743is determined by the affinity of its root activity. 744 745<p> 746The affinity determines two things — the task that the activity is re-parented 747to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 748attribute) and the task that will house the activity when it is launched 749with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> 750flag. 751</p> 752 753<p> 754By default, all activities in an application have the same affinity. You 755can set this attribute to group them differently, and even place 756activities defined in different applications within the same task. To 757specify that the activity does not have an affinity for any task, set 758it to an empty string. 759 760<p> 761If this attribute is not set, the activity inherits the affinity set 762for the application (see the 763<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 764element's 765<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code> 766attribute). The name of the default affinity for an application is 767the package name set by the 768<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 769element. 770</p> 771 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. 774This automatically sets the activity's context to use this theme (see 775<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also 776cause "starting" animations prior to the activity being launched (to better 777match what the activity actually looks like). 778 779<p> 780If this attribute is not set, the activity inherits the theme set for the 781application as a whole — from the 782<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> 783element's 784<code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code> 785attribute. If that attribute is also not set, the default system theme is used. For more 786information, see the <a 787href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. 788</p> 789<dd> 790 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> 795 796 <table> 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 800the bottom of the screen to display action items in the {@link android.app.ActionBar}, when 801constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small 802number of action items appearing in the action bar at the top of the screen, the action bar is 803split into the top navigation section and the bottom bar for action items. This ensures a reasonable 804amount of space is made available not only for the action items, but also for navigation and title 805elements at the top. Menu items are not split across the two bars; they always appear 806together.</td></tr> 807 </table> 808 <p>For more information about the action bar, see the <a 809href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p> 810 <p>This attribute was added in API level 14.</p> 811</dd> 812 813 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 817the on-screen soft keyboard. The setting for this attribute affects two 818things: 819 820<ul> 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> 823 824<li>The adjustment made to the activity's main window — whether it is 825resized smaller to make room for the soft keyboard or whether its contents 826pan to make the current focus visible when part of the window is covered by 827the soft keyboard.</li> 828</ul> 829 830<p> 831The setting must be one of the values listed in the following table, or a 832combination of one "{@code state...}" value plus one "{@code adjust...}" 833value. Setting multiple values in either group — multiple 834"{@code state...}" values, for example — has undefined results. 835Individual values are separated by a vertical bar ({@code |}). For example: 836</p> 837 838<pre><activity android:windowSoftInputMode="stateVisible|adjustResize" . . . ></pre> 839 840<p> 841Values set here (other than "{@code stateUnspecified}" and 842"{@code adjustUnspecified}") override values set in the theme. 843</p> 844 845<table> 846<tr> 847 <th>Value</th> 848 <th>Description</th> 849</tr><tr> 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. 854 855 <p> 856 This is the default setting for the behavior of the soft keyboard. 857 </p></td> 858</tr></tr> 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> 862</tr></tr> 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> 867</tr></tr> 868 <td>"{@code stateAlwaysHidden}"</td> 869 <td>The soft keyboard is always hidden when the activity's main window 870 has input focus.</td> 871</tr></tr> 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> 875</tr></tr> 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 880 activity.</td> 881</tr></tr> 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. 891 892 <p> 893 This is the default setting for the behavior of the main window. 894 </p></td> 895</tr></tr> 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> 899</tr></tr> 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> 907</tr> 908</table> 909 910<p> 911This attribute was introduced in API Level 3. 912</p></dd> 913</dl></dd> 914 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 920Level 3.</dd> 921 922<dt>see also:</dt> 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> 925</dl> 926