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