1 page.title=Activity and Task Design Guidelines 2 parent.title=UI Guidelines 3 parent.link=index.html 4 @jd:body 5 6 7 8 9 <div id="deprecatedSticker"> 10 <a href="#" 11 onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> 12 <strong>This doc is deprecated</strong></a> 13 </div> 14 15 16 <div id="naMessage" style="display:block"> 17 <div><p><strong>This document has been deprecated.</strong></p> 18 <p>For information about designing an activity structure and navigation, read the design guidelines 19 for <a href="{@docRoot}design/patterns/app-structure.html">App Structure</a> and 20 <a href="{@docRoot}design/patterns/navigation.html">Navigation</a>, or the developer guide 21 about <a 22 href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a>.</p> 23 24 <input style="margin-top:1em;padding:5px" type="button" 25 value="That's nice, but I still want to read this document" 26 onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> 27 </div> 28 </div> 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 <div id="qv-wrapper"> 44 <div id="qv"> 45 46 <h2>Quickview</h2> 47 48 <ul> 49 <li>Activities are the main building blocks of Android applications. </li> 50 <li>In addition to writing your own activities, you are free to re-use activities from many other applications through intents.</li> 51 <li>You can enable activities in your application to be started from intents in other applications.</li> 52 <li>In nearly all cases, the activity stack just works as expected.</li> 53 In a couple of cases you might need to ensure the right thing happens by setting a string or flag.</li> 54 </ul> 55 56 <h2>In this document</h2> 57 58 <ol> 59 <li><a href=#applications_activities>Applications, Activities, Activity Stack and Tasks</a> 60 </li> 61 <li><a href=#tour>A Tour of Activities and Tasks 62 <ol> 63 <li><a href=#starting_an_activity_from_home>Starting an Activity from Home</a></li> 64 <li><a href=#navigating_away_from_an_activity>Navigating Away from an Activity</a></li> 65 <li><a href=#reusing_an_activity>Re-using an Activity</a></li> 66 <li><a href=#replacing_an_activity>Replacing an Activity</a></li> 67 <li><a href=#multitasking>Multitasking</a></li> 68 <li><a href=#launching_from_two_entry_points>Launching from Two Entry Points</a></li> 69 <li><a href=#intents>Intents</a></li> 70 <li><a href=#switching_between_tasks>Switching Between Tasks</a></li> 71 </ol> 72 </li> 73 <li><a href=#tips>Design Tips 74 <ol> 75 <li><a href=#activity_not_reused_tip>Don't specify intent filters in an activity that won't be re-used</a></li> 76 <!-- <li><a href=#others_to_reuse_tip>Don't define your own URI schemes</a></li> --> 77 <li><a href=#reusing_tip>Handle case where no activity matches</a></li> 78 <li><a href=#activity_launching_tip>Consider how to launch your activities</a></li> 79 <li><a href=#activities_added_to_task_tip>Allow activities to add to current task</a></li> 80 <li><a href=#notifications_get_back_tip>Notifications and App Widgets should provide consistent back behavior</li> 81 <li><a href=#use_notification_tip>Use the notification system</a></li> 82 <li><a href=#taking_over_back_key>Don't take over <em>Back</em> button unless you absolutely 83 need to</a></li> 84 </ol> 85 </li> 86 </ol> 87 88 <h2>See also</h2> 89 90 <ol> 91 <li><a href="{@docRoot}guide/components/fundamentals.html">Application Fundamentals</a></li> 92 </ol> 93 94 </div> 95 </div> 96 97 <p> 98 This document describes core principles of the Android application 99 framework, from a high-level, user-centric perspective useful to 100 interaction and application designers as well as application 101 developers. 102 </p> 103 104 <p> 105 It illustrates activities and tasks with examples, and describes some 106 of their underlying principles and mechanisms, such as navigation, 107 multitasking, activity re-use, intents, and the activity stack. 108 The document also highlights design decisions that are available to you 109 and what control they give you over the UI of your application. 110 </p> 111 112 <p> 113 This document draws examples from several Android applications, 114 including default applications (such as Dialer) and Google 115 applications (such as Maps). You can try out the examples yourself in 116 the Android emulator or on an Android-powered device. If you are using 117 a device, note that your device may not offer all of the example 118 applications used in this document. 119 </p> 120 121 <p> 122 Be sure to look at the <a href="#design_tips">Design Tips</a> section 123 for guidelines, tips, and things to avoid. This document is a 124 complement to the <a href="{@docRoot}guide/components/fundamentals.html">Application 125 Fundamentals</a> documentation (particularly the <a 126 href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> 127 document), 128 which covers the underlying mechanics for programmers. 129 </p> 130 131 <h2 id="applications_activities">Applications, Activities, Activity Stack and Tasks</h2> 132 133 <p> 134 Four fundamental concepts in the Android system that are helpful for you to understand are: 135 </p> 136 137 <ul> 138 <li>Applications 139 <li>Activities 140 <li>Activity Stack 141 <li>Tasks 142 </ul> 143 144 <h3 id=applications>Applications</h3> 145 146 <p> 147 An Android <em>application</em> typically consists of one or more 148 related, loosely bound activities <!--(and possibly 149 <a href=#services_broadcast_receivers title="other components">other 150 components</a>)--> for the user to interact with, typically bundled up 151 in a single file (with an .apk suffix). Android ships with a rich set 152 of applications that may include email, calendar, browser, maps, text 153 messaging, contacts, camera, dialer, music player, settings and 154 others. 155 </p> 156 157 <p> 158 Android has an application launcher available at the Home screen, 159 typically in a sliding drawer which displays applications as icons, 160 which the user can pick to start an application. 161 </p> 162 163 164 <h3 id=activities>Activities</h3> 165 166 <p> 167 <em>Activities</em> are the main building blocks of Android 168 applications. When you create an application, you can assemble it from 169 activities that you create and from activities you re-use from other 170 applications. These activities are bound at runtime, so that newly 171 installed applications can take advantage of already installed 172 activities. Once assembled, activities work together to form a 173 cohesive user interface. An activity has a distinct visual user 174 interface designed around a single, well-bounded purpose, such as 175 viewing, editing, dialing the phone, taking a photo, searching, 176 sending data, starting a voice command, or performing some other type 177 of user action. Any application that presents anything on the display 178 must have at least one activity responsible for that display. 179 </p> 180 181 <p> 182 When using an Android device, as the user moves through the user 183 interface they start activities one after the other, totally oblivious 184 to the underlying behavior — to them the experience should be 185 seamless, activity after activity, <a href="#tasks">task</a> after 186 task. 187 </p> 188 189 <p> 190 An activity handles a particular type of content (data) and accepts a 191 set of related user actions. Each activity has a 192 <a href="{@docRoot}guide/components/activities.html#Lifecycle">lifecycle</a> that is 193 independent of the other 194 activities in its application or task — each activity is 195 launched (started) independently, and the user or system can start, 196 run, pause, resume, stop and restart it as needed. Because of this 197 independence, activities can be re-used and replaced by other 198 activities in a variety of ways. 199 </p> 200 201 <p> 202 The Dialer application is an example of an application that consists 203 basically of four activities: dialer, contacts list, view contact, and 204 new contact, as shown in the following screenshots: 205 </p> 206 207 <table style="border: none;"> 208 <tbody> 209 <tr> 210 <td style="border: none !important;"> 211 <img src={@docRoot}images/activity_task_design/ContactsDialer.png> 212 <div style=TEXT-ALIGN:center> 213 Dialer 214 </div> 215 </td> 216 <td style="border: none !important;"> 217 <img src={@docRoot}images/activity_task_design/ContactsList.png> 218 <div style=TEXT-ALIGN:center> 219 Contacts 220 </div> 221 </td> 222 <td style="border: none !important;"> 223 <img src={@docRoot}images/activity_task_design/ContactView.png> 224 <div style=TEXT-ALIGN:center> 225 View Contact 226 </div> 227 </td> 228 <td style="border: none !important;"> 229 <img src={@docRoot}images/activity_task_design/ContactNew.png> 230 <div style=TEXT-ALIGN:center> 231 New Contact 232 </div> 233 </td> 234 </tr> 235 </tbody> 236 </table> 237 238 <p> 239 Here are other examples of applications and the activities they might contain: 240 </p> 241 242 <ul> 243 <li> 244 Email - activities to view folders, view list of messages, 245 view a message, compose a message, and set up an account 246 </li> 247 <li> 248 Calendar - activities to view day, view week, view month, view 249 agenda, edit an event, edit preferences, and view an alert 250 </li> 251 <li> 252 Camera - activities for running the camera, viewing the list 253 of pictures, viewing a picture, cropping a picture, running 254 the camcorder, viewing the list of movies, and viewing a movie 255 </li> 256 <li> 257 Game - one activity to play the game, typically another for setup 258 </li> 259 <li> 260 Maps - one activity to view a location on a map, a second for lists 261 (such as turn list or friend list), and a third for details 262 (friend location, status, photo) 263 </li> 264 </ul> 265 266 267 <p> 268 An activity is the most prominent of four <em>components</em> of an 269 application. The other components are service, content provider and 270 broadcast receiver. For more details on activities, see the 271 <a href="{@docRoot}guide/components/activities.html">Activities</a> document. 272 </p> 273 274 275 <h3 id="activity_stack">Activity Stack</h3> 276 277 <p> 278 As the user moves from activity to activity, across applications, the 279 Android system keeps a linear navigation history of activities the 280 user has visited. This is the <em>activity stack</em>, also known as the 281 back stack. In general, when a user starts a new activity, it is added 282 to the activity stack, so that pressing <em>Back</em> displays the previous 283 activity on the stack. However, the user cannot use the <em>Back</em> button to go 284 back further than the last visit to Home. The adding of an activity to 285 the current stack happens whether or not that activity begins a new 286 <a href=#tasks title=task>task</a> (as long as that task was started 287 without going Home), so going back can let the user go back to 288 activities in previous tasks. The user can get to tasks earlier than 289 the most recent Home by selecting its root activity from the 290 application launcher, a shortcut, or the "Recent tasks" screen. 291 </p> 292 293 <p> 294 Activities are the only things that can be added to the activity stack 295 — views, windows, menus, and dialogs cannot. That is, when 296 designing the navigation, if you have screen A and you want the user 297 to be able go to a subsequent screen B and then use the <em>Back</em> button to go 298 back to screen A, then the screen A needs to be implemented as an 299 activity. The one exception to this rule is if your application 300 <a href="#taking_over_back_key">takes control of the <em>Back</em> button</a> and manages the 301 navigation 302 itself. 303 </p> 304 305 306 307 <h3 id=tasks>Tasks</h3> 308 309 <p> 310 A <em>task</em> is the sequence of activities the user follows to 311 accomplish an objective, regardless of which applications the 312 activities belong to. Until a new task is explicitly specified (see 313 "Interrupting the Task"), all activities the user starts are 314 considered to be part of the current task. It's notable that these 315 activities can be in any application — that is, all in the same 316 application or in different ones. That is, a task that starts out in 317 contacts can continue, by choosing an email address, to an email 318 activity and then, by attaching a file, to a picture gallery to pick 319 from. Contacts, email and picture gallery are all separate 320 applications. 321 </p> 322 323 <p> 324 The activity that starts a task is called the <em>root activity</em>. 325 It is often, but not necessarily, started from the application 326 launcher, Home screen shortcut or "Recent tasks" switcher (a long 327 press on Home on some devices). The user can return to a task by 328 choosing the icon for its root activity the same way they started the 329 task. Once inside a task, the <em>Back</em> button goes to previous activities in 330 that task. The activity stack is made up of one or more tasks. 331 </p> 332 333 <p> 334 Here are some examples of tasks: 335 </p> 336 337 <ul> 338 <li> 339 Send a text message with an attachment 340 </li> 341 <li> 342 View a YouTube video and share it by email with someone else 343 </li> 344 </ul> 345 346 <p> 347 <b>Interrupting the Task</b> - An important property of a task is that 348 the user can interrupt what they're doing (their task) to perform a 349 different task, then are able to return to where they left off to 350 complete the original task. The idea is that users can run multiple 351 tasks simultaneously and switch between them. There are two primary 352 ways to jump off to that other task — in both cases the user 353 should be able to return to where they were before the interruption: 354 </p> 355 356 357 <ul> 358 <li> 359 User is interrupted by a notification a notification appears and the user wants to act on it 360 </li> 361 <li> 362 User deciding to perform another task user just presses Home and starts an application 363 </li> 364 </ul> 365 366 <p> 367 Of course, there are exceptions to the rules. Beyond the two ways just 368 mentioned, there is a third way to start a task, and that is by 369 starting an activity that defines itself as a new task. Maps and 370 Browser are two applications that do this. For example, choosing an 371 address in an email starts the Maps activity as a new task, and 372 choosing a link in an email starts the Browser activity as a new 373 task. In these cases, the <em>Back</em> button will return to the previous 374 activity in a different task (Email), because it was not started from 375 Home. 376 </p> 377 378 379 <h2 id="tour">A Tour of Activities and Tasks</h2> 380 381 <p> 382 The following examples illustrate basic principles for applications, 383 activities, the activity stack, the <em>Back</em> button, tasks and intents. It 384 shows how the system responds to user actions such as starting 385 activities and switching between tasks. With most of these examples 386 you can follow along, launching activities on your device as 387 indicated. 388 </p> 389 390 391 <h3 id=starting_an_activity_from_home>Starting an Activity from Home</h3> 392 393 <p> 394 Home is the starting place for most applications. (Some applications 395 can be launched only from other applications.) When the user touches 396 an icon in the application launcher (or a shortcut on the Home 397 screen), the main activity for that application is launched into the 398 foreground where it has user focus. As shown in the following figure, 399 the user action of going Home and touching the Email icon launches the 400 List Messages activity of the Email application. The Home activity 401 remains stopped in the background, ready to restart when called on by 402 the user. 403 </p> 404 405 <p> 406 <img src={@docRoot}images/activity_task_design/HomeTaskBasics1a.png> 407 </p> 408 409 <h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with <em>Back</em> and 410 <em>Home</em> buttons</h3> 411 412 <p> 413 An activity can keep or lose its state depending on how the user 414 leaves the activity — by the <em>Home</em> or <em>Back</em> button. 415 </p> 416 417 <p> 418 By default, pressing the <em>Back</em> button finishes (destroys) the current 419 activity and displays the previous activity to the user. In the 420 following figure, the user starts email by touching the Email icon in 421 the Home screen, which displays a list of email messages. The user 422 scrolls down the list (changing its initial state). Pressing <em>Back</em> 423 destroys the List Messages activity and returns to the previous 424 activity, which is Home. If the user re-launches Email, it would 425 re-load the messages and display its initial, non-scrolled state. 426 </p> 427 428 <p> 429 <img src={@docRoot}images/activity_task_design/HomeTaskBasics1b.png> 430 </p> 431 432 <p> 433 In the above example, pressing <em>Back</em> goes to Home because it was the 434 last activity the user was viewing. But if the user had gotten to List 435 Message from some other activity, then pressing <em>Back</em> would have 436 returned there. 437 </p> 438 439 <p> 440 By contrast, the next figure shows the user leaving List Messages by 441 pressing <em>Home</em> instead of <em>Back</em> — the List Messages activity is 442 stopped and moved to the background rather than being 443 destroyed. Starting Email again from its icon would simply bring the 444 List Messages activity to the foreground (changing it from stopped to 445 running) in the same scrolled state the user last left it. 446 </p> 447 448 <p> 449 <img src={@docRoot}images/activity_task_design/HomeTaskBasics1c.png> 450 </p> 451 452 <p> 453 <b>Exceptions.</b> Some background activities return to their initial 454 screen (they lose any state, such as scrolling) when they are brought 455 to the foreground. This is true for Contacts and Gallery. If the user 456 chooses Home > Contacts then chooses a contact, they are viewing 457 the details of a contact. If they start again by choosing Home > 458 Contacts, they are presented with the initial list of contacts rather 459 than the contact they were last viewing. Contacts is designed this way 460 because this initial screen is the main entry point for the 461 application with four tabs for accessing the full range of features. 462 </p> 463 464 <p> 465 In addition, not all activities have the behavior that they are 466 destroyed when <em>Back</em> is pressed. When the user starts playing music in 467 the Music application and then presses <em>Back</em>, the application overrides 468 the normal back behavior, preventing the player activity from being 469 destroyed, and continues playing music, even though its activity is no 470 longer visible — as a visual substitute, the Music application 471 places a notification in the status bar so the user still has an easy 472 way to get to the application to stop or control the music. Note that 473 you can write an activity to stop when its screen is no longer 474 visible, or to continue running in the background — the latter 475 was chosen for the music player. 476 </p> 477 478 479 <h3 id=reusing_an_activity>Re-using an Activity</h3> 480 481 <p> 482 When activity A starts activity B in a different application, activity 483 B is said to be <em>re-used</em>. This use case normally takes place 484 because activity A is lacking a capability and can find it in activity B. 485 </p> 486 487 <p> 488 <b>Contacts Re-Uses Gallery to Get a Picture</b> - The Contacts 489 activity has a field for a picture of a contact, but the Gallery is 490 normally where pictures are kept. So Contacts can re-use the Gallery 491 activity to get a picture. This is a good example of re-use of the 492 Gallery activity. The following figure illustrates the sequence of 493 activities to do this (up to crop). This is how it's done: The user 494 chooses Contacts, selects the contact for viewing, chooses <em>Menu</em> > 495 Edit contact and touches the picture field, which launches the Gallery 496 activity. The user then chooses the picture they want, crops and saves 497 it. Saving it causes the picture to be inserted into the picture field 498 in the contact. 499 </p> 500 501 <p> 502 Notice the Gallery returns a picture to the Contacts application that 503 started it. The next example illustrates re-use of an activity that 504 does not return a result. Also notice that the following figure is 505 illustrates the navigation history through the activities, or the 506 activity stack — the user can back up through each activity all 507 the way to Home. 508 </p> 509 510 <p> 511 When designing an application, it's good to think about how it can 512 re-use activities in other applications, and how your activities might 513 be re-used by other applications. If you add an activity with the same 514 <a href=#intents title="intent filter">intent filter</a> as an 515 existing activity, then the system presents the user with a choice 516 between the activities. 517 </p> 518 519 <p> 520 <img src={@docRoot}images/activity_task_design/ReusingAnActivity1.png> 521 </p> 522 523 <p> 524 <b>Gallery Re-Uses Messaging for Sharing a Picture</b> - Sharing is 525 another good example of one application re-using an activity from a 526 different application. As shown in the following figure, the user 527 starts Gallery, picks a picture to view, chooses <em>Menu</em> > Share, and 528 picks "Messaging". This starts the Messaging activity, creates a new 529 message and attaches the original picture to it. The user then fills 530 in the "To" field, writes a short message and sends it. User focus 531 remains in the Messaging program. If the user wants to go back to the 532 Gallery, they must press the <em>Back</em> button. (The user can back up through 533 each activity all the way to Home.) 534 </p> 535 536 <p> 537 In contrast to the previous example, this re-use of the Messaging 538 activity does not return anything to the Gallery activity that started it. 539 </p> 540 541 <p> 542 <img src={@docRoot}images/activity_task_design/ReusingAnActivity2.png> 543 </p> 544 545 <p> 546 Both of these examples illustrate tasks — a sequence of 547 activities that accomplish an objective. Each case uses activities 548 from two different applications to get the job done. 549 </p> 550 551 552 <h3 id=replacing_an_activity>Replacing an Activity</h3> 553 554 <p> 555 This is the use case where activity A replaces activity B in a 556 different application. This situation normally happens because 557 activity A is better at doing the job than activity B. In other words, 558 A and B are equivalent enough that A can replace B. This case stands 559 in contrast with re-using an activity, where A and B are quite 560 different activities and supplement each other. 561 </p> 562 563 <p> 564 In this example, the user has downloaded a replacement for the Phone 565 Ringtone activity, called Rings Extended. Now when they go to 566 Settings, Sound & Display, Phone Ringtone, the system presents 567 them with a choice between the Android System's ringtone activity and 568 the new one. This dialog box has an option to remember their choice 569 "Use by default for this action". When they choose "Rings Extended", 570 that activity loads, replacing the original Android ringtone activity. 571 </p> 572 573 <p> 574 <img src={@docRoot}images/activity_task_design/ReplacingAnActivity.png> 575 </p> 576 577 <h3 id=multitasking>Multitasking</h3> 578 579 <p> 580 As previously noted, when an activity has been launched, the user can 581 go to Home and launch a second activity without destroying the first 582 activity. This scenario demonstrates launching the Maps application. 583 </p> 584 585 <ul> 586 <li> 587 State 1 - The user launches the View Map activity and searches 588 for a map location. Let's say the network is slow, so the map is 589 taking an unusually long taking time to draw. 590 </li> 591 </ul> 592 <ul> 593 <li> 594 State 2 - The user wants to do something else while they're 595 waiting, so they press <em>Home</em>, which does not interrupt the map's 596 network connection and allows the map to continue loading in the 597 background. 598 599 </li> 600 601 <li> 602 State 3 - The map activity is now running in the background, 603 with Home in the foreground. The user then launches the Calendar 604 activity, which launches into the foreground, taking user focus, 605 where they view today's calendar (as indicated by the heavy 606 outline). 607 </li> 608 </ul> 609 610 <p> 611 <img src={@docRoot}images/activity_task_design/HomeTaskBasics1d.png> 612 </p> 613 <ul> 614 <li> 615 State 4 - The user presses Home, then Maps to return to the map, which by now has fully loaded. 616 </li> 617 </ul> 618 619 <p> 620 <img src={@docRoot}images/activity_task_design/HomeTaskBasics1e.png> 621 </p> 622 623 <p> 624 The application launcher at Home has launched "View Map" and "Day 625 View" activities into separate <em>tasks</em>, hence the system is 626 multitasking — running multiple <a href=#tasks 627 title=tasks>tasks</a>. 628 </p> 629 630 631 <h3 id=launching_from_two_entry_points>Launching from Two Entry Points</h3> 632 633 <p> 634 Every application must have at least one entry point — a way 635 for the user or system to access activities inside the 636 application. Each icon in the application launcher at home 637 represents an entry point. Applications can also be launched from another 638 application. Each activity is a potential entry point into the 639 application. 640 </p> 641 642 <p> 643 The phone application has two entry points: Contacts and Dialer. A 644 user entering from Contacts can choose a phone number to launch the 645 Dialer. As shown in the following figure, a user could choose the 646 Contacts icon to launch the Contacts activity, then pick a phone 647 number to launch the Dialer activity and dial the phone. 648 </p> 649 650 <p> 651 Once the user is inside the application, they can access other 652 activities, such as New Contact and Edit Contact, through tabs, menu 653 items, list items, onscreen buttons, or other user interface 654 controls. 655 </p> 656 657 <p> 658 <img src={@docRoot}images/activity_task_design/PhoneActivitiesDiagram.png> 659 </p> 660 661 <h3 id=intents>Intents</h3> 662 663 <p> 664 When the user takes an action on some data, such as touching a 665 mailto:info (a] example.com link, they are actually initiating an Intent 666 object, or just an <em>intent</em>, which then gets resolved to a 667 particular component (we consider only activity components here). 668 So, the result of a user touching a mailto: link is an Intent object 669 that the system tries to match to an activity. If that Intent object was 670 written explicitly naming an activity (an <em>explicit intent</em>), 671 then the system immediately launches that activity in response to the user 672 action. However, if that Intent object was written without naming an 673 activity (an <em>implicit intent</em>), the system compares the Intent 674 object to the <em>intent filters</em> of available activities. If more 675 than one activity can handle the action and data, the system 676 displays an activity chooser for the user to choose from. 677 </p> 678 679 <p> 680 This example of touching the mailto: link is shown in the following 681 figure. If the device has two email applications set up, when a user 682 touches a mailto: email address on a web page, the result is an 683 Intent object which displays a dialog box with a choice between the 684 two activities to compose an email (Gmail and Email). 685 </p> 686 687 <p> 688 <img src={@docRoot}images/activity_task_design/IntentsDiagram.png> 689 </p> 690 691 <p> 692 Here are some examples of Intent objects and the activities they resolve to: 693 </p> 694 695 <ul> 696 <li> 697 View the list of contacts - resolves to a contact list viewer activity 698 </li> 699 700 <li> 701 View a particular contact - resolves to a contact viewer activity 702 </li> 703 704 <li> 705 Edit a particular contact - resolves to a contact editor activity 706 </li> 707 708 <li> 709 Send to a particular email - resolves to an email activity 710 </li> 711 712 <li> 713 Dial a phone number - resolves to a phone dialer activity 714 </li> 715 716 <li> 717 View the list of images - resolves to an image list viewer activity 718 </li> 719 720 <li> 721 View a particular image - resolves to an image viewer activity 722 </li> 723 724 <li> 725 Crop a particular image - resolves to an image cropper activity 726 </li> 727 </ul> 728 729 <p> 730 Notice that an Intent object specifies two things, an action and data: 731 </p> 732 733 <ul> 734 <li> 735 A generic action to be performed. In these examples: view, edit, dial or crop 736 </li> 737 738 <li> 739 The specific data to be acted on. In these examples: the list of contacts, a particular contact, a phone number, the list of images, or a particular image 740 </li> 741 </ul> 742 743 <p> 744 Note that any user action to start an activity from the 745 application launcher at Home is an explicit intent to a specific 746 activity. Likewise, some activities launch private activities 747 within their application as explicit intents so no other activity 748 can access them. 749 </p> 750 751 <p> 752 For more about intents, see <a 753 href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. 754 </p> 755 756 757 <h3 id=switching_between_tasks>Switching Between Tasks</h3> 758 759 <p> 760 This scenario shows how the user can switch between two tasks. In 761 this example, the user writes a text message, attaches a picture, 762 but before they are done they glance at their calendar. They then 763 return to where they left off, attaching the picture and sending the 764 message. 765 </p> 766 767 <ol> 768 <li> 769 <b>Start first task.</b> You want to send a text message and attach a photo. You would choose: 770 771 <p> 772 Home > Messaging > New message > <em>Menu</em> > Attach 773 > Pictures. This last step launches the picture gallery 774 for picking a photo. Notice that picture gallery is an 775 activity in a separate application. 776 </p> 777 778 779 <table> 780 <tbody> 781 <tr> 782 <td valign=top style="border: none !important;"> 783 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching1a.png> 784 </td> 785 <td valign=top style="border: none !important;"> 786 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching1b.png> 787 </td> 788 <td valign=top style="border: none !important;"> 789 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching1c.png> 790 </td> 791 </tr> 792 </tbody> 793 </table> 794 795 <p> 796 At this point, before you have picked a picture, you decide 797 to stop and glance at your calendar, which is a separate 798 task. Because the current activity has no button to go 799 directly to the Calendar, you need to start from Home. 800 </p> 801 802 </li> 803 <li> 804 <b>Start second task.</b> You choose Home > Calendar to 805 look at a calendar event. Calendar launches from Home as a new 806 task because the application launcher creates a new task for 807 each application it launches. 808 809 <p> 810 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching2.png> 811 </p> 812 </li> 813 814 <li> 815 <b>Switch to first task and complete it.</b> When done looking 816 at the Calendar, you can return to attaching the picture by 817 starting the root activity again for that task: choose Home 818 > Messaging, which takes you not to Messaging, but directly 819 to the Picture gallery, where you left off. You can then pick 820 a photo, which is added to the message, you send the message 821 and you're done with the first task. 822 823 <table> 824 <tbody> 825 <tr> 826 827 <td valign=top style="border: none !important;"> 828 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching3a.png> 829 </td> 830 831 <td valign=top style="border: none !important;"> 832 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching3b.png> 833 </td> 834 835 <td valign=top style="border: none !important;"> 836 <img src={@docRoot}images/activity_task_design/HomeTaskSwitching3c.png> 837 </td> 838 839 </tr> 840 </tbody> 841 </table> 842 </li> 843 </ol> 844 845 846 <h2 id="tips">Design Tips</h2> 847 848 <p> 849 The following are tips and guidelines for application designers and developers. 850 </p> 851 852 <h3 id=activity_not_reused_tip>When writing an activity that won't be re-used, don't specify intent filters — use explicit intents</h3> 853 854 <p> 855 If you're writing an activity that you don't want other activities 856 to use, be sure not to add any intent filters to that activity. This 857 applies to an activity that will be launched only from the 858 application launcher or from other activities inside your 859 application. Instead, just create intents specifying the explicit 860 component to launch — that is, explicit intents. In this case, 861 there's just no need for intent filters. Intent filters are 862 published to all other applications, so if you make an intent 863 filter, what you're doing is publishing access to your activity, 864 which means you can cause unintentional security holes. 865 </p> 866 867 <!-- 868 <h3 id="others_to_reuse_tip">When writing an activity for others to re-use, don't define your own URI schemes</h3> 869 870 <p> 871 If publishing to others, don't define your own URI schemes in an 872 Intent type. Schemes (such as http: and mailto:) are an Internet 873 standard with a universal namespace outside of just Android, so you 874 aren't allowed to just make up your own. Instead, you should just 875 define your own actions. The action namespace is designed to not 876 have conflicts. Typically, your activity has one scheme with many 877 different actions. 878 </p> 879 880 <p> 881 Example: You want to show the user a bar code for some text. The 882 wrong way to do this is for the intent filter protocol to be 883 <action android:name="android.intent.action.VIEW" /> and 884 <data android:scheme="barcode" />. Do not do this. 885 </p> 886 887 <p> 888 Instead you should define <action 889 android:name="com.example.action.SHOW_BARCODE" /> and have the 890 invoker supply the data as an extra field in the Intent object. 891 </p> 892 893 <p> 894 Be aware this intent filter protocol 895 ("com.example.action.SHOW_BARCODE", in this example) is a public API 896 that you can't change once it's defined. You must support it in the 897 future because others are going to be relying on it. If you want to 898 add new features that are incompatible with the current protocol, 899 just define a new protocol and continue to support the old one. 900 </p> 901 --> 902 903 <h3 id="reusing_tip"> When reusing an activity owned by others, handle the case where no activity matches</h3> 904 905 <p> 906 Your applications can re-use activities made available from other 907 applications. In doing so, you cannot presume your intent will always 908 be resolved to a matching external activity — you must handle the case 909 where no application installed on the device can handle the intent. 910 </p> 911 912 <p> 913 You can either test that an activity matches the intent, which you can do 914 before starting the activity, or catch an exception if starting the 915 activity fails. Both approaches are described in the blog posting 916 <a href="http://android-developers.blogspot.com/2009/01/can-i-use-this-intent.html">Can 917 I use this Intent?</a>. 918 </p> 919 920 <p> 921 To test whether an intent can be resolved, your code can query the package manager. 922 The blog post provides an example in the isIntentAvailable() helper method. 923 You can perform this test when initializing the user interface. 924 For instance, you could disable the user control that initiates 925 the Intent object, or display a message to the user that lets them go 926 to a location, such as Google Play, to download its application. 927 In this way, your code can start the activity (using either startActivity() 928 or startActivityForResult()) only if the intent has tested to resolve 929 to an activity that is actually present. 930 </p> 931 932 <h3 id=activity_launching_tip>Consider how you want your activities to be launched or used by other applications</h3> 933 934 <p> 935 As a designer or developer, it's up to you to determine how users 936 start your application and the activities in it. As an application 937 is a set of activities, the user can start these activities from 938 Home or from another application. 939 </p> 940 941 <ul> 942 <li> 943 <b>Launch your main activity from an icon at Home </b>- If 944 your application can run standalone, it should probably be 945 started by the user touching an icon in <em>application 946 launcher</em> (typically implemented as a sliding drawer on the 947 Home screen), or from a shortcut icon on the Home screen, or 948 from the task switcher. (The mechanism for this is for the 949 activity to have an 950 <a href={@docRoot}guide/components/intents-filters.html>intent filter</a> with action 951 MAIN and 952 category LAUNCHER.) 953 </li> 954 </ul> 955 956 <ul> 957 <li> 958 <b>Launch your activity from within another application</b> - 959 Perhaps your activities are meant for re-use. For example, 960 many applications have data they want to share with other 961 users. Activities that can share data with other users include 962 email, text messaging and uploading to a public website. <p> 963 If one or more of your activities can be an alternative to an 964 existing activity in another application, you can make it 965 available to users at the point they request that 966 activity. For example, if your activity can send data to 967 others (such as by email, text messaging, or uploading), 968 consider setting up that activity to appear as a choice to the 969 user. To give a specific example, Gallery enables a user to 970 view and share pictures. When the user chooses "Share" from 971 the menus, the system compares the "Share" request (an Intent 972 object) to available activities (by looking at their intent 973 filters) and displays choices to share. In this case, it 974 matches Email, Gmail, Messaging and Picasa. If your activity 975 can send a picture or upload it to a website, all it needs to 976 do is make itself available for sharing (by setting its intent 977 filter). 978 </p> 979 <p> 980 Another activity can start your activity either with or without expecting a result back. 981 </p> 982 </li> 983 984 <ul> 985 <li> 986 <b>Start an activity expecting a result</b> - This approach 987 is closed loop, where the activity being started must either 988 return a valid result or be canceled. In the previous 989 examples of sharing a photo from a Gallery, the user ends up 990 back in the Gallery after completing the send or upload 991 procedure. These are examples of starting an activity 992 external to the Gallery. (Such an activity is started with 993 {@link 994 android.app.Activity#startActivityForResult(android.content.Intent, 995 int) startActivityForResult()}.) 996 </li> 997 998 <li> 999 <b>Start an activity not expecting a result</b> - This 1000 approach is open-ended. An example is choosing an house 1001 address in an email message (or web page), where the Maps 1002 activity is started to map the location. No result from maps 1003 is expected to be returned to the email message; the user 1004 can return by pressing the <em>Back</em> button. (Such an activity is 1005 started with {@link 1006 android.content.Context#startActivity(android.content.Intent) 1007 startActivity()}.) 1008 </li> 1009 </ul> 1010 1011 <li> 1012 <b>Launch your activity <em>only</em> from within another 1013 application</b> - The previous cases of sharing by way of 1014 Email, Gmail, Messaging and Picasa (from within Gallery) are 1015 all activities that can also be started from icons in the 1016 application launcher at Home. In contrast, the activities for 1017 cropping a picture and attaching a file cannot be started from 1018 Home, because they do not stand alone and require a 1019 context. 1020 </li> 1021 1022 <p> 1023 In fact, not all applications have icons and can be started from 1024 Home. Take for example a small app that is infrequently used and 1025 replaces existing functionality, that already has a natural entry 1026 point inside an existing application. For example, an Android phone 1027 typically has a built-in ringtone picker that can be selected from 1028 the sound settings of the Settings application. A custom ringtone 1029 picker application that you write could be launched by an intent 1030 identical to the built-in ringtone picker. At the point where the 1031 user chooses "Phone ringtone", they are presented with a dialog 1032 letting them choose between "Android System" and your ringtone 1033 picker (and letting them save their choice) as shown in the 1034 following figure. A ringtone is something you set infrequently, and 1035 already has a well-defined starting point, so probably does not need 1036 an application icon at Home. 1037 </p> 1038 1039 <p> 1040 <img src={@docRoot}images/activity_task_design/ActivityChooser.png> 1041 </p> 1042 1043 <li> 1044 <b>Launch two or more main activities within a single 1045 application from separate icon at Home</b> - As we have 1046 defined it, all the code in a single .apk file is considered 1047 to be one <em>application.</em> You can write an application 1048 that contains two main activities launchable from Home. 1049 </li> 1050 1051 <p> 1052 The Camera.apk application is a good example of an application that 1053 contains two independent main activities — Camera and 1054 Camcorder — that each have their own icons in application 1055 launcher, that can be launched separately, and so appear to the user 1056 as separate applications. They both share use of the same lens, and 1057 both store their images (still and moving) in the Gallery. 1058 </p> 1059 1060 <p> 1061 In order for your application to contain two different, independent 1062 activities launchable from Home, you must define them to be 1063 associated with different tasks. (This means setting the main 1064 activity for each task to a different <!--a href=#affinities 1065 title=affinity-->task affinity<!--/a--> — in this case, 1066 "com.android.camera" and "com.android.videocamera".) 1067 </p> 1068 1069 <p> 1070 Contacts and Dialer are another example of two main activities 1071 launchable from Home that reside in the same application. 1072 </p> 1073 1074 <li> 1075 <b>Making your application available as a widget</b> - An 1076 application can also display a portion of itself as an <a 1077 href={@docRoot}guide/topics/appwidgets/index.html title="app 1078 widget">app widget</a>, embedded in Home or another 1079 application, and receive periodic updates. 1080 </li> 1081 1082 </ul> 1083 1084 1085 <h3 id=activities_added_to_task_tip>Allow your activities to be added to the current task</h3> 1086 1087 <p> 1088 If your activities can be started from another application, allow 1089 them to be added to the current <a href=#tasks title=Tasks>task</a> 1090 (or an existing task it has an affinity with). Having activities 1091 added to a task enables the user to switch between a task that 1092 contains your activities and other tasks. <!--See <a href=#tasks 1093 title=Tasks>Tasks</a> for a fuller explanation.--> Exceptions are 1094 your activities that have only one instance. 1095 </p> 1096 1097 <p> 1098 For this behavior, your activity should have a <!--a 1099 href=launch_modes title="standard or singleTop"-->launch 1100 mode<!--/a--> of standard or singleTop rather than singleTask or 1101 singleInstance. These modes also enable multiple instances of your 1102 activity to be run. 1103 </p> 1104 1105 1106 <h3 id="notifications_get_back_tip">Notifications and App Widgets should provide consistent back behavior</h3> 1107 <p> 1108 Notifications and app widgets are two common ways that a user can launch 1109 your app through something besides its main icon in Launcher. You must 1110 take care when implementing these so that the user has a consistent experience 1111 with the back button, not causing surprises in where they return to or the 1112 state the application ends up in. 1113 </p> 1114 1115 <p> 1116 The 1117 <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#HandlingNotifications">Handling 1118 Notifications</a> section of the developer guide's 1119 <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a> 1120 documentation provides an overview of how to write code to correctly handle 1121 notification. This dicussion applies equally to handling interactions with 1122 app widgets. 1123 </p> 1124 1125 <p> 1126 A notification always starts an activity as a new task (that is, it 1127 puts <font size=1>FLAG_ACTIVITY_NEW_TASK</font> in the intent it 1128 passes to startActivity()). This is done because interruptions to a 1129 task should not become part of that task. 1130 </p> 1131 1132 <h3 id=use_notification_tip>Use the notification system — don't use dialog boxes in place of notifications</h3> 1133 1134 <p> 1135 If your background service needs to notify a user, use the standard 1136 notification system — don't use a dialog or toast to notify 1137 them. A dialog or toast would immediately take focus and interrupt 1138 the user, taking focus away from what they were doing: the user 1139 could be in the middle of typing text the moment the dialog appears 1140 and could accidentally act on the dialog. Users are used to dealing 1141 with notifications and can pull down the notification shade at their 1142 convenience to respond to your message. 1143 </p> 1144 1145 <h3 id=taking_over_back_key>Don't take over the <em>Back</em> button unless you absolutely need 1146 to</h3> 1147 1148 <p> 1149 As a user navigates from one activity to the next, the system adds 1150 them to the activity stack. This forms a navigation history that is 1151 accessible with the <em>Back</em> button. Most activities are relatively limited 1152 in scope, with just one set of data, such as viewing a list of 1153 contacts, composing an email, or taking a photo. But what if your 1154 application is one big activity with several pages of content and 1155 needs finer-grained control of the <em>Back</em> button? Examples of such Google 1156 applications are the Browser, which can have several web pages open 1157 at once, and Maps, which can have several layers of geographic data 1158 to switch between. Both of these applications take control of the 1159 <em>Back</em> button and maintain their own internal back stacks that operate 1160 only when these applications have focus. 1161 </p> 1162 1163 <p> 1164 For example, Maps uses <em>layers</em> to present different 1165 information on a map to the user: displaying the location of a 1166 search result, displaying locations of friends, and displaying a 1167 line for a street path providing direction between points. Maps 1168 stores these layers in its own history so the <em>Back</em> button can return to 1169 a previous layer. 1170 </p> 1171 1172 <p> 1173 Similarly, Browser uses <em>browser windows</em> to present different 1174 web pages to the user. Each window has its own navigation history, 1175 equivalent to tabs in a browser in a desktop operating system (such 1176 as Windows, Macintosh or Linux). For example, if you did a Google 1177 web search in one window of the Android Browser, clicking on a link 1178 in the search results displays a web page in that same window, and 1179 then pressing <em>Back</em> would to the search results page. Pressing 1180 <em>Back</em> goes to a previous window only if the current window was 1181 launched from that previous window. If the user keeps pressing 1182 back, they will eventually leave the browser activity and return 1183 Home. 1184 </p> 1185 1186