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