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