1 page.title=Tasks and Back Stack 2 parent.title=Activities 3 parent.link=activities.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#ActivityState">Saving Activity State</a></li></li> 12 <li><a href="#ManagingTasks">Managing Tasks</a> 13 <ol> 14 <li><a href="#TaskLaunchModes">Defining launch modes</a></li> 15 <li><a href="#Affinities">Handling affinities</a></li> 16 <li><a href="#Clearing">Clearing the back stack</a></li> 17 <li><a href="#Starting">Starting a task</a></li> 18 </ol> 19 </li> 20 </ol> 21 22 <h2>Articles</h2> 23 <ol> 24 <li><a href="http://android-developers.blogspot.com/2010/04/multitasking-android-way.html"> 25 Multitasking the Android Way</a></li> 26 </ol> 27 28 <h2>See also</h2> 29 <ol> 30 <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: 31 Navigation</a></li> 32 <li><a 33 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest 34 element</a></li> 35 <li><a href="{@docRoot}guide/components/recents.html">Overview Screen</a></li> 36 </ol> 37 </div> 38 </div> 39 40 41 <p>An application usually contains multiple <a 42 href="{@docRoot}guide/components/activities.html">activities</a>. Each activity 43 should be designed around a specific kind of action the user can perform and can start other 44 activities. For example, an email application might have one activity to show a list of new messages. 45 When the user selects a message, a new activity opens to view that message.</p> 46 47 <p>An activity can even start activities that exist in other applications on the device. For 48 example, if your application wants to send an email message, you can define an intent to perform a 49 "send" action and include some data, such as an email address and a message. An activity from another 50 application that declares itself to handle this kind of intent then opens. In this case, the intent 51 is to send an email, so an email application's "compose" activity starts (if multiple activities 52 support the same intent, then the system lets the user select which one to use). When the email is 53 sent, your activity resumes and it seems as if the email activity was part of your application. Even 54 though the activities may be from different applications, Android maintains this seamless user 55 experience by keeping both activities in the same <em>task</em>.</p> 56 57 <p>A task is a collection of activities that users interact with 58 when performing a certain job. The activities are arranged in a stack (the <em>back stack</em>), in 59 the order in which each activity is opened.</p> 60 61 <!-- SAVE FOR WHEN THE FRAGMENT DOC IS ADDED 62 <div class="sidebox-wrapper"> 63 <div class="sidebox"> 64 <h3>Adding fragments to a task's back stack</h3> 65 66 <p>Your activity can also include {@link android.app.Fragment}s to the back stack. For example, 67 suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the 68 other being a layout to display an item from the list (fragment B). When the user selects an item 69 from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be 70 desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p> 71 <p>In order to add fragment B to the back stack so that this is possible, you must call {@link 72 android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link 73 android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment 74 C.</p> 75 <p>For more information about using fragments and adding them to the back stack, see the {@link 76 android.app.Fragment} class documentation.</p> 77 78 </div> 79 </div> 80 --> 81 82 <p>The device Home screen is the starting place for most tasks. When the user touches an icon in the 83 application 84 launcher (or a shortcut on the Home screen), that application's task comes to the foreground. If no 85 task exists for the application (the application has not been used recently), then a new task 86 is created and the "main" activity for that application opens as the root activity in the stack.</p> 87 88 <p>When the current activity starts another, the new activity is pushed on the top of the stack and 89 takes focus. The previous activity remains in the stack, but is stopped. When an activity 90 stops, the system retains the current state of its user interface. When the user presses the 91 <em>Back</em> 92 button, the current activity is popped from the top of the stack (the activity is destroyed) and the 93 previous activity resumes (the previous state of its UI is restored). Activities in the stack are 94 never rearranged, only pushed and popped from the stack—pushed onto the stack when started by 95 the current activity and popped off when the user leaves it using the <em>Back</em> button. As such, 96 the back 97 stack operates as a "last in, first out" object structure. Figure 1 visualizes 98 this behavior with a timeline showing the progress between activities along with the current back 99 stack at each point in time.</p> 100 101 <img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> 102 <p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a 103 task adds an item to the back stack. When the user presses the <em>Back</em> button, the current 104 activity is 105 destroyed and the previous activity resumes.</p> 106 107 108 <p>If the user continues to press <em>Back</em>, then each activity in the stack is popped off to 109 reveal the 110 previous one, until the user returns to the Home screen (or to whichever activity was running when 111 the task began). When all activities are removed from the stack, the task no longer exists.</p> 112 113 <div class="figure" style="width:287px"> 114 <img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p 115 class="img-caption"><strong>Figure 2.</strong> Two tasks: Task B receives user interaction 116 in the foreground, while Task A is in the background, waiting to be resumed.</p> 117 </div> 118 <div class="figure" style="width:215px"> 119 <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p 120 class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated multiple times.</p> 121 </div> 122 123 <p>A task is a cohesive unit that can move to the "background" when users begin a new task or go 124 to the Home screen, via the <em>Home</em> button. While in the background, all the activities in the 125 task are 126 stopped, but the back stack for the task remains intact—the task has simply lost focus while 127 another task takes place, as shown in figure 2. A task can then return to the "foreground" so users 128 can pick up where they left off. Suppose, for example, that the current task (Task A) has three 129 activities in its stack—two under the current activity. The user presses the <em>Home</em> 130 button, then 131 starts a new application from the application launcher. When the Home screen appears, Task A goes 132 into the background. When the new application starts, the system starts a task for that application 133 (Task B) with its own stack of activities. After interacting with 134 that application, the user returns Home again and selects the application that originally 135 started Task A. Now, Task A comes to the 136 foreground—all three activities in its stack are intact and the activity at the top of the 137 stack resumes. At 138 this point, the user can also switch back to Task B by going Home and selecting the application icon 139 that started that task (or by selecting the app's task from the 140 <a href="{@docRoot}guide/components/recents.html">overview screen</a>). 141 This is an example of multitasking on Android.</p> 142 143 <p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once. 144 However, if the user is running many background tasks at the same time, the system might begin 145 destroying background activities in order to recover memory, causing the activity states to be lost. 146 See the following section about <a href="#ActivityState">Activity state</a>.</p> 147 148 <p>Because the activities in the back stack are never rearranged, if your application allows 149 users to start a particular activity from more than one activity, a new instance of 150 that activity is created and pushed onto the stack (rather than bringing any previous instance of 151 the activity to the top). As such, one activity in your application might be instantiated multiple 152 times (even from different tasks), as shown in figure 3. As such, if the user navigates backward 153 using the <em>Back</em> button, each instance of the activity is revealed in the order they were 154 opened (each 155 with their own UI state). However, you can modify this behavior if you do not want an activity to be 156 instantiated more than once. How to do so is discussed in the later section about <a 157 href="#ManagingTasks">Managing Tasks</a>.</p> 158 159 160 <p>To summarize the default behavior for activities and tasks:</p> 161 162 <ul> 163 <li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state 164 (such as scroll position and text entered into forms). 165 If the user presses the <em>Back</em> button while in Activity B, Activity A resumes with its state 166 restored.</li> 167 <li>When the user leaves a task by pressing the <em>Home</em> button, the current activity is 168 stopped and 169 its task goes into the background. The system retains the state of every activity in the task. If 170 the user later resumes the task by selecting the launcher icon that began the task, the task comes 171 to the foreground and resumes the activity at the top of the stack.</li> 172 <li>If the user presses the <em>Back</em> button, the current activity is popped from the stack 173 and 174 destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system 175 <em>does not</em> retain the activity's state.</li> 176 <li>Activities can be instantiated multiple times, even from other tasks.</li> 177 </ul> 178 179 180 <div class="note design"> 181 <p><strong>Navigation Design</strong></p> 182 <p>For more about how app navigation works on Android, read Android Design's <a 183 href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> 184 </div> 185 186 187 <h2 id="ActivityState">Saving Activity State</h2> 188 189 <p>As discussed above, the system's default behavior preserves the state of an activity when it is 190 stopped. This way, when users navigate back to a previous activity, its user interface appears 191 the way they left it. However, you can—and <strong>should</strong>—proactively retain 192 the state of your activities using callback methods, in case the activity is destroyed and must 193 be recreated.</p> 194 195 <p>When the system stops one of your activities (such as when a new activity starts or the task 196 moves to the background), the system might destroy that activity completely if it needs to recover 197 system memory. When this happens, information about the activity state is lost. If this happens, the 198 system still 199 knows that the activity has a place in the back stack, but when the activity is brought to the 200 top of the stack the system must recreate it (rather than resume it). In order to 201 avoid losing the user's work, you should proactively retain it by implementing the 202 {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} callback 203 methods in your activity.</p> 204 205 <p>For more information about how to save your activity state, see the <a 206 href="{@docRoot}guide/components/activities.html#SavingActivityState">Activities</a> 207 document.</p> 208 209 210 211 <h2 id="ManagingTasks">Managing Tasks</h2> 212 213 <p>The way Android manages tasks and the back stack, as described above—by placing all 214 activities started in succession in the same task and in a "last in, first out" stack—works 215 great for most applications and you shouldn't have to worry about how your activities are associated 216 with tasks or how they exist in the back stack. However, you might decide that you want to interrupt 217 the normal behavior. Perhaps you want an activity in your application to begin a new task when it is 218 started (instead of being placed within the current task); or, when you start an activity, you want 219 to bring forward an existing instance of it (instead of creating a new 220 instance on top of the back stack); or, you want your back stack to be cleared of all 221 activities except for the root activity when the user leaves the task.</p> 222 223 <p>You can do these things and more, with attributes in the 224 <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 225 manifest element and with flags in the intent that you pass to 226 {@link android.app.Activity#startActivity startActivity()}.</p> 227 228 <p>In this regard, the principal <a href="{@docRoot}guide/topics/manifest/activity-element.html"> 229 {@code <activity>}</a> attributes you can use are:</p> 230 231 <ul class="nolist"> 232 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff"> 233 {@code taskAffinity}</a></li> 234 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode"> 235 {@code launchMode}</a></li> 236 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent"> 237 {@code allowTaskReparenting}</a></li> 238 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear"> 239 {@code clearTaskOnLaunch}</a></li> 240 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always"> 241 {@code alwaysRetainTaskState}</a></li> 242 <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish"> 243 {@code finishOnTaskLaunch}</a></li> 244 </ul> 245 246 <p>And the principal intent flags you can use are:</p> 247 248 <ul class="nolist"> 249 <li>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</li> 250 <li>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</li> 251 <li>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</li> 252 </ul> 253 254 <p>In the following sections, you'll see how you can use these manifest attributes and intent 255 flags to define how activities are associated with tasks and how they behave in the back stack.</p> 256 257 <p>Also, discussed separately are the considerations for how tasks and activites may be represented 258 and managed in the overview screen. See <a href="{@docRoot}guide/components/recents.html">Overview Screen</a> 259 for more information. Normally you should allow the system to define how your task and 260 activities are represented in the overview screen, and you don't need to modify this behavior.</p> 261 262 <p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default 263 behavior for activities and tasks. If you determine that it's necessary for your activity to modify 264 the default behaviors, use caution and be sure to test the usability of the activity during 265 launch and when navigating back to it from other activities and tasks with the <em>Back</em> button. 266 Be sure to test for navigation behaviors that might conflict with the user's expected behavior.</p> 267 268 269 <h3 id="TaskLaunchModes">Defining launch modes</h3> 270 271 <p>Launch modes allow you to define how a new instance of an activity is associated with the 272 current task. You can define different launch modes in two ways:</p> 273 <ul class="nolist"> 274 <li><a href="#ManifestForTasks">Using the manifest file</a> 275 <p>When you declare an activity in your manifest file, you can specify how the activity 276 should associate with tasks when it starts.</li> 277 <li><a href="#IntentFlagsForTasks">Using Intent flags</a> 278 <p>When you call {@link android.app.Activity#startActivity startActivity()}, 279 you can include a flag in the {@link android.content.Intent} that declares how (or 280 whether) the new activity should associate with the current task.</p></li> 281 </ul> 282 283 <p>As such, if Activity A starts Activity B, Activity B can define in its manifest how it 284 should associate with the current task (if at all) and Activity A can also request how Activity 285 B should associate with current task. If both activities define how Activity B 286 should associate with a task, then Activity A's request (as defined in the intent) is honored 287 over Activity B's request (as defined in its manifest).</p> 288 289 <p class="note"><strong>Note:</strong> Some launch modes available for the manifest file 290 are not available as flags for an intent and, likewise, some launch modes available as flags 291 for an intent cannot be defined in the manifest.</p> 292 293 294 <h4 id="ManifestForTasks">Using the manifest file</h4> 295 296 <p>When declaring an activity in your manifest file, you can specify how the activity should 297 associate with a task using the <a 298 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 299 element's <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code 300 launchMode}</a> attribute.</p> 301 302 <p>The <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code 303 launchMode}</a> attribute specifies an instruction on how the activity should be launched into a 304 task. There are four different launch modes you can assign to the 305 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> 306 attribute:</p> 307 308 <dl> 309 <dt>{@code "standard"} (the default mode)</dt> 310 <dd>Default. The system creates a new instance of the activity in the task from 311 which it was started and routes the intent to it. The activity can be instantiated multiple times, 312 each instance can belong to different tasks, and one task can have multiple instances.</dd> 313 <dt>{@code "singleTop"}</dt> 314 <dd>If an instance of the activity already exists at the top of the current task, the system 315 routes the intent to that instance through a call to its {@link 316 android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance of the 317 activity. The activity can be instantiated multiple times, each instance can 318 belong to different tasks, and one task can have multiple instances (but only if the 319 activity at the top of the back stack is <em>not</em> an existing instance of the activity). 320 <p>For example, suppose a task's back stack consists of root activity A with activities B, C, 321 and D on top (the stack is A-B-C-D; D is on top). An intent arrives for an activity of type D. 322 If D has the default {@code "standard"} launch mode, a new instance of the class is launched and the 323 stack becomes A-B-C-D-D. However, if D's launch mode is {@code "singleTop"}, the existing instance 324 of D receives the intent through {@link 325 android.app.Activity#onNewIntent onNewIntent()}, because it's at the top of the stack—the 326 stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new 327 instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p> 328 <p class="note"><strong>Note:</strong> When a new instance of an activity is created, 329 the user can press the <em>Back</em> button to return to the previous activity. But when an existing 330 instance of 331 an activity handles a new intent, the user cannot press the <em>Back</em> button to return to the 332 state of 333 the activity before the new intent arrived in {@link android.app.Activity#onNewIntent 334 onNewIntent()}.</p> 335 </dd> 336 337 <dt>{@code "singleTask"}</dt> 338 <dd>The system creates a new task and instantiates the activity at the root of the new task. 339 However, if an instance of the activity already exists in a separate task, the system routes the 340 intent to the existing instance through a call to its {@link 341 android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only 342 one instance of the activity can exist at a time. 343 <p class="note"><strong>Note:</strong> Although the activity starts in a new task, the 344 <em>Back</em> button still returns the user to the previous activity.</p></dd> 345 <dt>{@code "singleInstance"}.</dt> 346 <dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into 347 the task holding the instance. The activity is always the single and only member of its task; 348 any activities started by this one open in a separate task.</dd> 349 </dl> 350 351 352 <p>As another example, the Android Browser application declares that the web browser activity should 353 always open in its own task—by specifying the {@code singleTask} launch mode in the <a 354 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element. 355 This means that if your application issues an 356 intent to open the Android Browser, its activity is <em>not</em> placed in the same 357 task as your application. Instead, either a new task starts for the Browser or, if the Browser 358 already has a task running in the background, that task is brought forward to handle the new 359 intent.</p> 360 361 <p>Regardless of whether an activity starts in a new task or in the same task as the activity that 362 started it, the <em>Back</em> button always takes the user to the previous activity. However, if you 363 start an activity that specifies the {@code singleTask} launch mode, then if an instance of 364 that activity exists in a background task, that whole task is brought to the foreground. At this 365 point, the back stack now includes all activities from the task brought forward, at the top of the 366 stack. Figure 4 illustrates this type of scenario.</p> 367 368 <img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> 369 <p class="img-caption"><strong>Figure 4.</strong> A representation of how an activity with 370 launch mode "singleTask" is added to the back stack. If the activity is already a part of a 371 background task with its own back stack, then the entire back stack also comes 372 forward, on top of the current task.</p> 373 374 <p>For more information about using launch modes in the manifest file, see the 375 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 376 element documentation, where the {@code launchMode} attribute and the accepted values are 377 discussed more.</p> 378 379 <p class="note"><strong>Note:</strong> The behaviors that you specify for your activity with the <a 380 href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> attribute 381 can be overridden by flags included with the intent that start your activity, as discussed in the 382 next section.</p> 383 384 385 386 <h4 id="#IntentFlagsForTasks">Using Intent flags</h4> 387 388 <p>When starting an activity, you can modify the default association of an activity to its task 389 by including flags in the intent that you deliver to {@link 390 android.app.Activity#startActivity startActivity()}. The flags you can use to modify the 391 default behavior are:</p> 392 393 <p> 394 <dt>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</dt> 395 <dd>Start the activity in a new task. If a task is already running for the activity you are now 396 starting, that task is brought to the foreground with its last state restored and the activity 397 receives the new intent in {@link android.app.Activity#onNewIntent onNewIntent()}. 398 <p>This produces the same behavior as the {@code "singleTask"} <a 399 href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, 400 discussed in the previous section.</p></dd> 401 <dt>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</dt> 402 <dd>If the activity being started is the current activity (at the top of the back stack), then 403 the existing instance receives a call to {@link android.app.Activity#onNewIntent onNewIntent()}, 404 instead of creating a new instance of the activity. 405 <p>This produces the same behavior as the {@code "singleTop"} <a 406 href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value, 407 discussed in the previous section.</p></dd> 408 <dt>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</dt> 409 <dd>If the activity being started is already running in the current task, then instead 410 of launching a new instance of that activity, all of the other activities on top of it are 411 destroyed and this intent is delivered to the resumed instance of the activity (now on top), 412 through {@link android.app.Activity#onNewIntent onNewIntent()}). 413 <p>There is no value for the <a 414 href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> 415 attribute that produces this behavior.</p> 416 <p>{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction with 417 {@code FLAG_ACTIVITY_NEW_TASK}. 418 When used together, these flags are a way of locating an existing activity 419 in another task and putting it in a position where it can respond to the intent. </p> 420 <p class="note"><strong>Note:</strong> If the launch mode of the designated activity is 421 {@code "standard"}, 422 it too is removed from the stack and a new instance is launched in its place to handle 423 the incoming intent. That's because a new instance is always created for a new intent when the 424 launch mode is {@code "standard"}. </p> 425 </dd> 426 </dl> 427 428 429 430 431 432 <h3 id="Affinities">Handling affinities</h3> 433 434 <p>The <em>affinity</em> indicates which task an activity prefers to belong to. By default, all the 435 activities from the same application have an affinity for each other. So, by default, all 436 activities in the same application prefer to be in the same task. However, you can modify 437 the default affinity for an activity. Activities defined in 438 different applications can share an affinity, or activities defined in the same application can be 439 assigned different task affinities.</p> 440 441 <p>You can modify the affinity for any given activity with the <a 442 href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> attribute 443 of the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 444 element.</p> 445 446 <p>The <a 447 href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> 448 attribute takes a string value, which must be unique from the default package name 449 declared in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"> 450 {@code <manifest>} 451 </a> element, because the system uses that name to identify the default task 452 affinity for the application.</p> 453 454 <p>The affinity comes into play in two circumstances:</p> 455 <ul> 456 <li>When the intent that launches an activity contains the 457 {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} 458 flag. 459 460 <p>A new activity is, by default, launched into the task of the activity 461 that called {@link android.app.Activity#startActivity startActivity()}. It's pushed onto the same 462 back stack as the caller. However, if the intent passed to 463 {@link android.app.Activity#startActivity startActivity()} 464 contains the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} 465 flag, the system looks for a different task to house the new activity. Often, it's a new task. 466 However, it doesn't have to be. If there's already an existing task with the same affinity as the 467 new activity, the activity is launched into that task. If not, it begins a new task.</p> 468 469 <p>If this flag causes an activity to begin a new task and the user presses the <em>Home</em> button 470 to leave 471 it, there must be some way for the user to navigate back to the task. Some entities (such as the 472 notification manager) always start activities in an external task, never as part of their own, so 473 they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to 474 {@link android.app.Activity#startActivity startActivity()}. 475 If you have an activity that can be invoked by 476 an external entity that might use this flag, take care that the user has a independent way to get 477 back to the task that's started, such as with a launcher icon (the root activity of the task 478 has a {@link android.content.Intent#CATEGORY_LAUNCHER} intent filter; see the <a 479 href="#Starting">Starting a task</a> section below).</p> 480 </li> 481 482 <li>When an activity has its <a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent"> 483 {@code allowTaskReparenting}</a> attribute set to {@code "true"}. 484 <p>In this case, the activity can move from the task it starts to the task it has an affinity 485 for, when that task comes to the foreground.</p> 486 <p>For example, suppose that an activity that reports weather conditions in selected cities is 487 defined as part of a travel application. It has the same affinity as other activities in the same 488 application (the default application affinity) and it allows re-parenting with this attribute. 489 When one of your activities starts the weather reporter activity, it initially belongs to the same 490 task as your activity. However, when the travel application's task comes to the foreground, the 491 weather reporter activity is reassigned to that task and displayed within it.</p> 492 </li> 493 </ul> 494 495 <p class="note"><strong>Tip:</strong> If an {@code .apk} file contains more than one "application" 496 from the user's point of view, you probably want to use the <a 497 href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> 498 attribute to assign different affinities to the activities associated with each "application".</p> 499 500 501 502 <h3 id="Clearing">Clearing the back stack</h3> 503 504 <p>If the user leaves a task for a long time, the system clears the task of all activities except 505 the root activity. When the user returns to the task again, only the root activity is restored. 506 The system behaves this way, because, after an extended amount of time, users likely have abandoned 507 what they were doing before and are returning to the task to begin something new. </p> 508 509 <p>There are some activity attributes that you can use to modify this behavior: </p> 510 511 <dl> 512 <dt><code><a 513 href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code> 514 </dt> 515 <dd>If this attribute is set to {@code "true"} in the root activity of a task, 516 the default behavior just described does not happen. 517 The task retains all activities in its stack even after a long period.</dd> 518 519 <dt><code><a 520 href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code></dt> 521 <dd>If this attribute is set to {@code "true"} in the root activity of a task, 522 the stack is cleared down to the root activity whenever the user leaves the task 523 and returns to it. In other words, it's the opposite of 524 <a href="{@docRoot}guide/topics/manifest/activity-element.html#always"> 525 {@code alwaysRetainTaskState}</a>. The user always returns to the task in its 526 initial state, even after a leaving the task for only a moment.</dd> 527 528 <dt><code><a 529 href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code> 530 </dt> 531 <dd>This attribute is like <a 532 href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code clearTaskOnLaunch}</a>, 533 but it operates on a 534 single activity, not an entire task. It can also cause any activity to go 535 away, including the root activity. When it's set to {@code "true"}, the 536 activity remains part of the task only for the current session. If the user 537 leaves and then returns to the task, it is no longer present.</dd> 538 </dl> 539 540 541 542 543 <h3 id="Starting">Starting a task</h3> 544 545 <p>You can set up an activity as the entry point for a task by giving it an intent filter with 546 {@code "android.intent.action.MAIN"} as the specified action and 547 {@code "android.intent.category.LAUNCHER"} 548 as the specified category. For example:</p> 549 550 <pre> 551 <activity ... > 552 <intent-filter ... > 553 <action android:name="android.intent.action.MAIN" /> 554 <category android:name="android.intent.category.LAUNCHER" /> 555 </intent-filter> 556 ... 557 </activity> 558 </pre> 559 560 <p>An intent filter of this kind causes an icon and label for the 561 activity to be displayed in the application launcher, giving users a way to launch the activity and 562 to return to the task that it creates any time after it has been launched. 563 </p> 564 565 <p>This second ability is important: Users must be able to leave a task and then come back to it 566 later using this activity launcher. For this reason, the two <a href="#LaunchModes">launch 567 modes</a> that mark activities as always initiating a task, {@code "singleTask"} and 568 {@code "singleInstance"}, should be used only when the activity has an 569 {@link android.content.Intent#ACTION_MAIN} 570 and a {@link android.content.Intent#CATEGORY_LAUNCHER} filter. Imagine, for example, what could 571 happen if the filter is missing: An intent launches a {@code "singleTask"} activity, initiating a 572 new task, and the user spends some time working in that task. The user then presses the <em>Home</em> 573 button. The task is now sent to the background and is not visible. Now the user has no way to return 574 to the task, because it is not represented in the application launcher.</p> 575 576 <p>For those cases where you don't want the user to be able to return to an activity, set the 577 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 578 element's 579 <a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code finishOnTaskLaunch}</a> 580 to {@code "true"} (see <a href="#Clearing">Clearing the stack</a>).</p> 581 582 <p>Further information about how tasks and activites are represented and managed in 583 the overview screen is available in <a href="{@docRoot}guide/components/recents.html"> 584 Overview Screen</a>.</p> 585 586 <!-- 587 <h2>Beginner's Path</h2> 588 589 <p>For more information about how to use intents to 590 activate other application components and publish the intents to which your components 591 respond, continue with the <b><a 592 href="{@docRoot}guide/components/intents-filters.html">Intents and Intent 593 Filters</a></b> document.</p> 594 --> 595
