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