+ This document describes core principles of the Android application + framework, from a high-level, user-centric perspective useful to + interaction and application designers as well as application + developers. +
+ ++ It illustrates activities and tasks with examples, and describes some + of their underlying principles and mechanisms, such as navigation, + multitasking, activity re-use, intents, and the activity stack. + The document also highlights design decisions that are available to you + and what control they give you over the UI of your application. +
+ ++ This document draws examples from several Android applications, + including default applications (such as Dialer) and Google + applications (such as Maps). You can try out the examples yourself in + the Android emulator or on an Android-powered device. If you are using + a device, note that your device may not offer all of the example + applications used in this document. +
+ ++ Be sure to look at the Design Tips section + for guidelines, tips, and things to avoid. This document is a + complement to Application Fundamentals, + which covers the underlying mechanics for programmers. +
+ ++ Four fundamental concepts in the Android system that are helpful for you to understand are: +
+ ++ An Android application typically consists of one or more + related, loosely bound activities for the user to interact with, typically bundled up + in a single file (with an .apk suffix). Android ships with a rich set + of applications that may include email, calendar, browser, maps, text + messaging, contacts, camera, dialer, music player, settings and + others. +
+ ++ Android has an application launcher available at the Home screen, + typically in a sliding drawer which displays applications as icons, + which the user can pick to start an application. +
+ + ++ Activities are the main building blocks of Android + applications. When you create an application, you can assemble it from + activities that you create and from activities you re-use from other + applications. These activities are bound at runtime, so that newly + installed applications can take advantage of already installed + activities. Once assembled, activities work together to form a + cohesive user interface. An activity has a distinct visual user + interface designed around a single, well-bounded purpose, such as + viewing, editing, dialing the phone, taking a photo, searching, + sending data, starting a voice command, or performing some other type + of user action. Any application that presents anything on the display + must have at least one activity responsible for that display. +
+ ++ When using an Android device, as the user moves through the user + interface they start activities one after the other, totally oblivious + to the underlying behavior — to them the experience should be + seamless, activity after activity, task after + task. +
+ ++ An activity handles a particular type of content (data) and accepts a + set of related user actions. In general, each activity has a + lifecycle that is independent of the other + activities in its application or task — each activity is + launched (started) independently, and the user or system can start, + run, pause, resume, stop and restart it as needed. Because of this + independence, activities can be re-used and replaced by other + activities in a variety of ways. +
+ ++ The Dialer application is an example of an application that consists + basically of four activities: dialer, contacts list, view contact, and + new contact, as shown in the following screenshots: +
+ +
+ 
+
+ Dialer
+
+ |
+
+ 
+
+ Contacts
+
+ |
+
+ 
+
+ View Contact
+
+ |
+
+ 
+
+ New Contact
+
+ |
+
+ Here are other examples of applications and the activities they might contain: +
+ ++ An activity is the most prominent of four components of an + application. The other components are service, content provider and + broadcast receiver. For more details on activities, see Activity in + Application Components. +
+ + ++ As the user moves from activity to activity, across applications, the + Android system keeps a linear navigation history of activities the + user has visited. This is the activity stack, also known as the + back stack. In general, when a user starts a new activity, it is added + to the activity stack, so that pressing BACK displays the previous + activity on the stack. However, the user cannot use the BACK key to go + back further than the last visit to Home. The adding of an activity to + the current stack happens whether or not that activity begins a new + task (as long as that task was started + without going Home), so going back can let the user go back to + activities in previous tasks. The user can get to tasks earlier than + the most recent Home by selecting its root activity from the + application launcher, a shortcut, or the "Recent tasks" screen. +
+ ++ Activities are the only things that can be added to the activity stack + — views, windows, menus, and dialogs cannot. That is, when + designing the navigation, if you have screen A and you want the user + to be able go to a subsequent screen B and then use the BACK key to go + back to screen A, then the screen A needs to be implemented as an + activity. The one exception to this rule is if your application + and manages the navigation itself. +
+ + + ++ A task is the sequence of activities the user follows to + accomplish an objective, regardless of which applications the + activities belong to. Until a new task is explicitly specified (see + "Interrupting the Task"), all activities the user starts are + considered to be part of the current task. It's notable that these + activities can be in any application — that is, all in the same + application or in different ones. That is, a task that starts out in + contacts can continue, by choosing an email address, to an email + activity and then, by attaching a file, to a picture gallery to pick + from. Contacts, email and picture gallery are all separate + applications. +
+ ++ The activity that starts a task is called the root activity. + It is often, but not necessarily, started from the application + launcher, Home screen shortcut or "Recent tasks" switcher (a long + press on Home on some devices). The user can return to a task by + choosing the icon for its root activity the same way they started the + task. Once inside a task, the BACK key goes to previous activities in + that task. The activity stack is made up of one or more tasks. +
+ ++ Here are some examples of tasks: +
+ ++ Interrupting the Task - An important property of a task is that + the user can interrupt what they're doing (their task) to perform a + different task, then are able to return to where they left off to + complete the original task. The idea is that users can run multiple + tasks simultaneously and switch between them. There are two primary + ways to jump off to that other task — in both cases the user + should be able to return to where they were before the interruption: +
+ + ++ Of course, there are exceptions to the rules. Beyond the two ways just + mentioned, there is a third way to start a task, and that is by + starting an activity that defines itself as a new task. Maps and + Browser are two applications that do this. For example, choosing an + address in an email starts the Maps activity as a new task, and + choosing a link in an email starts the Browser activity as a new + task. In these cases, the BACK key will return to the previous + activity in a different task (Email), because it was not started from + Home. +
+ + ++ The following examples illustrate basic principles for applications, + activities, the activity stack, the BACK key, tasks and intents. It + shows how the system responds to user actions such as starting + activities and switching between tasks. With most of these examples + you can follow along, launching activities on your device as + indicated. +
+ + ++ Home is the starting place for most applications. (Some applications + can be launched only from other applications.) When the user touches + an icon in the application launcher (or a shortcut on the Home + screen), the main activity for that application is launched into the + foreground where it has user focus. As shown in the following figure, + the user action of going Home and touching the Email icon launches the + List Messages activity of the Email application. The Home activity + remains stopped in the background, ready to restart when called on by + the user. +
+ +
+ 
+
+ An activity can keep or lose its state depending on how the user + leaves the activity — by the HOME or BACK key. +
+ ++ By default, pressing the BACK key finishes (destroys) the current + activity and displays the previous activity to the user. In the + following figure, the user starts email by touching the Email icon in + the Home screen, which displays a list of email messages. The user + scrolls down the list (changing its initial state). Pressing BACK + destroys the List Messages activity and returns to the previous + activity, which is Home. If the user re-launches Email, it would + re-load the messages and display its initial, non-scrolled state. +
+ +
+ 
+
+ In the above example, pressing BACK goes to Home because it was the + last activity the user was viewing. But if the user had gotten to List + Message from some other activity, then pressing BACK would have + returned there. +
+ ++ By contrast, the next figure shows the user leaving List Messages by + pressing HOME instead of BACK — the List Messages activity is + stopped and moved to the background rather than being + destroyed. Starting Email again from its icon would simply bring the + List Messages activity to the foreground (changing it from stopped to + running) in the same scrolled state the user last left it. +
+ +
+ 
+
+ Exceptions. Some background activities return to their initial + screen (they lose any state, such as scrolling) when they are brought + to the foreground. This is true for Contacts and Gallery. If the user + chooses Home > Contacts then chooses a contact, they are viewing + the details of a contact. If they start again by choosing Home > + Contacts, they are presented with the initial list of contacts rather + than the contact they were last viewing. Contacts is designed this way + because this initial screen is the main entry point for the + application with four tabs for accessing the full range of features. +
+ ++ In addition, not all activities have the behavior that they are + destroyed when BACK is pressed. When the user starts playing music in + the Music application and then presses BACK, the application overrides + the normal back behavior, preventing the player activity from being + destroyed, and continues playing music, even though its activity is no + longer visible — as a visual substitute, the Music application + places a notification in the status bar so the user still has an easy + way to get to the application to stop or control the music. Note that + you can write an activity to stop when its screen is no longer + visible, or to continue running in the background — the latter + was chosen for the music player. +
+ + ++ When activity A starts activity B in a different application, activity + B is said to be re-used. This use case normally takes place + because activity A is lacking a capability and can find it in activity B. +
+ ++ Contacts Re-Uses Gallery to Get a Picture - The Contacts + activity has a field for a picture of a contact, but the Gallery is + normally where pictures are kept. So Contacts can re-use the Gallery + activity to get a picture. This is a good example of re-use of the + Gallery activity. The following figure illustrates the sequence of + activities to do this (up to crop). This is how it's done: The user + chooses Contacts, selects the contact for viewing, chooses MENU > + Edit contact and touches the picture field, which launches the Gallery + activity. The user then chooses the picture they want, crops and saves + it. Saving it causes the picture to be inserted into the picture field + in the contact. +
+ ++ Notice the Gallery returns a picture to the Contacts application that + started it. The next example illustrates re-use of an activity that + does not return a result. Also notice that the following figure is + illustrates the navigation history through the activities, or the + activity stack — the user can back up through each activity all + the way to Home. +
+ ++ When designing an application, it's good to think about how it can + re-use activities in other applications, and how your activities might + be re-used by other applications. If you add an activity with the same + intent filter as an + exisiting activity, then the system presents the user with a choice + between the activities. +
+ +
+ 
+
+ Gallery Re-Uses Messaging for Sharing a Picture - Sharing is + another good example of one application re-using an activity from a + different application. As shown in the following figure, the user + starts Gallery, picks a picture to view, chooses MENU > Share, and + picks "Messaging". This starts the Messaging activity, creates a new + message and attaches the original picture to it. The user then fills + in the "To" field, writes a short message and sends it. User focus + remains in the Messaging program. If the user wants to go back to the + Gallery, they must press the BACK key. (The user can back up through + each activity all the way to Home.) +
+ ++ In contrast to the previous example, this re-use of the Messaging + activity does not return anything to the Gallery activity that started it. +
+ +
+ 
+
+ Both of these examples illustrate tasks — a sequence of + activities that accomplish an objective. Each case uses activities + from two different applications to get the job done. +
+ + ++ This is the use case where activity A replaces activity B in a + different application. This situation normally happens because + activity A is better at doing the job than activity B. In other words, + A and B are equivalent enough that A can replace B. This case stands + in contrast with re-using an activity, where A and B are quite + different activities and supplement each other. +
+ ++ In this example, the user has downloaded a replacement for the Phone + Ringtone activity, called Rings Extended. Now when they go to + Settings, Sound & Display, Phone Ringtone, the system presents + them with a choice between the Android System's ringtone activity and + the new one. This dialog box has an option to remember their choice + "Use by default for this action". When they choose "Rings Extended", + that activity loads, replacing the original Android ringtone activity. +
+ +
+ 
+
+ As previously noted, when an activity has been launched, the user can + go to Home and launch a second activity without destroying the first + activity. This scenario demonstrates launching the Maps application. +
+ ++ Note that when you write an activity, you can make it stop or + continue running when it is moved to the background (see + onStop() in Activity Lifecycle). + For activities that download data from the network, it's recommended + to let them continue downloading so the user can multi-task. +
+ +
+
+
+ 
+
+ The application launcher at Home has launched "View Map" and "Day + View" activities into separate tasks, hence the system is + multitasking — running multiple tasks. +
+ + ++ Every application must have at least one entry point — a way + for the user or system to access activities inside the + application. Each icon in the application launcher at home + represents an entry point. Applications can also from another + application. Each activity is a potential entry point into the + application. +
+ ++ The phone application has two entry points: Contacts and Dialer. A + user entering from Contacts can choose a phone number to launch the + Dialer. As shown in the following figure, a user could choose the + Contacts icon to launch the Contacts activity, then pick a phone + number to launch the Dialer activity and dial the phone. +
+ ++ Once the user is inside the application, they can access other + activities, such as New Contact and Edit Contact, through tabs, menu + items, list items, onscreen buttons, or other user interface + controls. +
+ +
+
+
+ When the user takes an action on some data, such as touching a + mailto:info@example.com link, they are actually initiating an Intent + object which then gets resolved to a particular component (we will + consider only activity components here). So, the result of a user + touching a mailto: link is an Intent object that the system tries to + match to an activity. If that Intent object was written explicitly + naming an activity (an explicit intent), then the system + immediately launches that activity in response to the user + action. However, if that Intent object was written without naming an + activity (an implicit intent), the system compares the Intent + object to the intent filters of available activities. If more + than one activity can handle the action and data, the system + displays an activity chooser for the user to choose from. +
+ ++ This example of touching the mailto: link is shown in the following + figure. If the device has two email applications set up, when a user + touches a mailto: email address on a web page, the result is an + Intent object which displays a dialog box with a choice between the + two activities to compose an email (Gmail and Email). +
+ +
+ 
+
+ Here are some examples of Intent objects and the activities they resolve to: +
+ ++ Notice that an Intent object specifies two things, an action and data: +
+ ++ Note that any user action to start an activity from the + application launcher at Home is an explicit intent to a specific + activity. Likewise, some activities launch private activities + within their application as explicit intents so no other activity + can access them. +
+ ++ For more on intents, see {@link android.content.Intent Intent class} and + intent filters. +
+ + ++ This scenario shows how the user can switch between two tasks. In + this example, the user writes a text message, attaches a picture, + but before they are done they glance at their calendar. They then + return to where they left off, attaching the picture and sending the + message. +
+ ++ Home > Messaging > New message > MENU > Attach + > Pictures. This last step launches the picture gallery + for picking a photo. Notice that picture gallery is an + activity in a separate application. +
+ + +
+ 
+ |
+
+ 
+ |
+
+ 
+ |
+
+ At this point, before you have picked a picture, you decide + to stop and glance at your calendar, which is a separate + task. Because the current activity has no button to go + directly to the Calendar, you need to start from Home. +
+ +
+ 
+
+ 
+ |
+
+
+ 
+ |
+
+
+ 
+ |
+
+
+ The following are tips and guidelines for application designers and developers. +
+ ++ If you're writing an activity that you don't want other activities + to use, be sure not to add any intent filters to that activity. This + applies to an activity that will be launched only from the + application launcher or from other activities inside your + application. Instead, just create intents specifying the explicit + component to launch — that is, explicit intents. In this case, + there's just no need for intent filters. Intent filters are + published to all other applications, so if you make an intent + filter, what you're doing is publishing access to your activity, + which means you can cause unintentional security holes. +
+ + + ++ Your applications can re-use activities made available from other + applications. In doing so, you cannot presume that external activity + will always be present — you must handle the case that the + external activity is not installed. Do this in the way you find most + appropriate, such as dimming the user control that accesses it (such + as a button or menu item), or displaying a message to the user that + sends them to the location to download it, such as the Market. +
+ ++ As a designer or developer, it's up to you to determine how users + start your application and the activities in it. As an application + is a set of activities, the user can start these activities from + Home or from another application. +
+ ++ If one or more of your activities can be an alternative to an + existing activity in another application, you can make it + available to users at the point they request that + activity. For example, if your activity can send data to + others (such as by email, text messaging, or uploading), + consider setting up that activity to appear as a choice to the + user. To give a specific example, Gallery enables a user to + view and share pictures. When the user chooses "Share" from + the menus, the system compares the "Share" request (an Intent + object) to available activities (by looking at their intent + filters) and displays choices to share. In this case, it + matches Email, Gmail, Messaging and Picassa. If your activity + can send a picture or upload it to a website, all it needs to + do is make itself available for sharing (by setting its intent + filter). +
++ Another activity can start your activity either with or without expecting a result back. +
++ In fact, not all applications have icons and can be started from + Home. Take for example a small app that is infrequently used and + replaces existing functionality, that already has a natural entry + point inside an existing application. For example, an Android phone + typically has a built-in ringtone picker that can be selected from + the sound settings of the Settings application. A custom ringtone + picker application that you write could be launched by an intent + identical to the built-in ringtone picker. At the point where the + user chooses "Phone ringtone", they are presented with a dialog + letting them choose between "Android System" and your ringtone + picker (and letting them save their choice) as shown in the + following figure. A ringtone is something you set infrequently, and + already has a well-defined starting point, so probably does not need + an application icon at Home. +
+ +
+ 
+
+ The Camera.apk application is a good example of an application that + contains two independent main activities — Camera and + Camcorder — that each have their own icons in application + launcher, that can be launched separately, and so appear to the user + as separate applications. They both share use of the same lens, and + both store their images (still and moving) in the Gallery. +
+ ++ In order for your application to contain two different, independent + activities launchable from Home, you must define them to be + associated with different tasks. (This means setting the main + activity for each task to a different task affinity — in this case, + "com.android.camera" and "com.android.videocamera".) +
+ ++ Contacts and Dialer are another example of two main activities + launchable from Home that reside in the same application. +
+ ++ If your activities can be started from another application, allow + them to be added to the current task + (or an existing task it has an affinity with). Having activities + added to a task enables the user to switch between a task that + contains your activities and other tasks. Exceptions are + your activities that have only one instance. +
+ ++ For this behavior, your activity should have a launch + mode of standard or singleTop rather than singleTask or + singleInstance. These modes also enable multiple instances of your + activity to be run. +
+ + ++ Applications that are in the background or haven't been run can + send out notifications to the user letting them know about events + of interest. For example, Calendar can send out notifications of + upcoming events, and Email can send out notifications when new + messages arrive. One of the user interface rules is that when the + user is in activity A and gets a notification for activity B and + picks that notification, when they press the BACK key, they should + go back to activity A. +
+ ++ The following scenario shows how the activity stack should work + when the user responds to a notification. +
+ ++This behavior doesn't necessarily happen by default. +
+ ++Notifications generally happen primarily in one of two ways: +
+ ++ Because of the way tasks work, if the taskAffinity of the + dedicated activity is kept as its default, then pressing the + BACK key (in step 6, above) would go to Calendar, rather + than Gmail. The reason is that, by default, all activities + in a given application have the same task + affinity. Therefore, the task affinity of the dedicated + activity matches the Calendar task, which is already running + in step 1. This means in step 4, choosing the notification + brings the existing Calendar event (in step 1) forward and + starts the dedicated activity on top of it. This is not + what you want to have happen. Setting the dedicated + activity's taskAffinity to empty string fixes this. +
++ There are other ways to handle notifications, such as bringing the + activity to the foreground set to display specific data, such as the + ongoing text message thread of a particular person. +
+ ++ A notification always starts an activity as a new task (that is, it + puts FLAG_ACTIVITY_NEW_TASK in the intent it + passes to startActivity()). This is done because interruptions to a + task should not become part of that task. +
+ ++ If your background service needs to notify a user, use the standard + notification system — don't use a dialog or toast to notify + them. A dialog or toast would immediately take focus and interrupt + the user, taking focus away from what they were doing: the user + could be in the middle of typing text the moment the dialog appears + and could accidentally act on the dialog. Users are used to dealing + with notifications and can pull down the notification shade at their + convenience to respond to your message. +
+ ++ As a user navigates from one activity to the next, the system adds + them to the activity stack. This forms a navigation history that is + accessible with the BACK key. Most activities are relatively limited + in scope, with just one set of data, such as viewing a list of + contacts, composing an email, or taking a photo. But what if your + application is one big activity with several pages of content and + needs finer-grained control of the BACK key? Examples of such Google + applications are the Browser, which can have several web pages open + at once, and Maps, which can have several layers of geographic data + to switch between. Both of these applications take control of the + BACK key and maintain their own internal back stacks that operate + only when these applications have focus. +
+ ++ For example, Maps uses layers to present different + information on a map to the user: displaying the location of a + search result, displaying locations of friends, and displaying a + line for a street path providing direction between points. Maps + stores these layers in its own history so the BACK key can return to + a previous layer. +
+ ++ Similarly, Browser uses browser windows to present different + web pages to the user. Each window has its own navigation history, + equivalent to tabs in a browser in a desktop operating system (such + as Windows, Macintosh or Linux). For example, if you did a Google + web search in one window of the Android Browser, clicking on a link + in the search results displays a web page in that same window, and + then pressing BACK would to the search results page. Pressing + BACK goes to a previous window only if the current window was + launched from that previous window. If the user keeps pressing + back, they will eventually leave the browser activity and return + Home. +
+ diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd index 61e310a8ea67b..0b9d2754d21a3 100644 --- a/docs/html/guide/practices/ui_guidelines/index.jd +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -22,12 +22,24 @@ The Icon Templates Pack is an archive of Photoshop and Illustrator templates and filters that make it much simpler to create conforming icons.