am a9d9fa72: Merge "docs: switch from caps to initial-case for device button names" into ics-mr1

<p>You can enable items from the options menu to appear directly in the action bar as "action

items". You can also add navigation features to the action bar, such as tabs or a drop-down list,

and use the application icon to supplement the system's BACK behavior with the option to navigate to

and use the application icon to supplement the system's <em>Back</em> button behavior with the option to

navigate to

your application's "home" activity or "up" the application's structural hierarchy.</p>

<p>This guide provides some tips for using the action bar in ways that support both tablets and

developer guide, you can use the application icon in the action bar to facilitate user navigation

when appropriate—either as a method to get back to the "home" activity (similar to clicking

the logo on a web site) or as a way to navigate up the application's structural hierarchy. Although

it might seem similar to the standard BACK navigation in some cases, the up navigation option

it might seem similar to the standard <em>Back</em> navigation in some cases, the up navigation

option

provides a more predictable navigation method for situations in which the user may have entered

from an external location, such as a notification, app widget, or a different application.</p>

      <li><a href=#activities_added_to_task_tip>Allow activities to add to current task</a></li>

      <li><a href=#notifications_get_back_tip>Notifications and App Widgets should provide consistent back behavior</li>

      <li><a href=#use_notification_tip>Use the notification system</a></li>

      <li><a href=#taking_over_back_key>Don't take over BACK key unless you absolutely need to</a></li>

      <li><a href=#taking_over_back_key>Don't take over <em>Back</em> button unless you absolutely

need to</a></li>

    </ol>

  </li>

</ol>

  Android system keeps a linear navigation history of activities the

  user has visited. This is the <em>activity stack</em>, 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

  to the activity stack, so that pressing <em>Back</em> displays the previous

  activity on the stack. However, the user cannot use the <em>Back</em> button 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 

  <a href=#tasks title=task>task</a> (as long as that task was started

  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

  to be able go to a subsequent screen B and then use the <em>Back</em> button 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 

  <a href="#taking_over_back_key">takes control of the BACK key</a> and manages the navigation

  <a href="#taking_over_back_key">takes control of the <em>Back</em> button</a> and manages the

navigation

itself.

</p>

  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

  task. Once inside a task, the <em>Back</em> button goes to previous activities in

  that task. The activity stack is made up of one or more tasks.

</p>

  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

  task. In these cases, the <em>Back</em> button will return to the previous

  activity in a different task (Email), because it was not started from

  Home.

</p>

<p>

  The following examples illustrate basic principles for applications,

  activities, the activity stack, the BACK key, tasks and intents.  It

  activities, the activity stack, the <em>Back</em> button, 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

  <img src={@docRoot}images/activity_task_design/HomeTaskBasics1a.png>

</p>

<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with BACK and HOME keys</h3>

<h3 id=navigating_away_from_an_activity>Navigating Away from an Activity with <em>Back</em> and

<em>Home</em> buttons</h3>

<p>

  An activity can keep or lose its state depending on how the user

  leaves the activity — by the HOME or BACK key.

  leaves the activity &mdash; by the <em>Home</em> or <em>Back</em> button.

</p>

<p>

  By default, pressing the BACK key finishes (destroys) the current

  By default, pressing the <em>Back</em> button 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

  scrolls down the list (changing its initial state). Pressing <em>Back</em>

  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.

</p>

<p>

  In the above example, pressing BACK goes to Home because it was the

  In the above example, pressing <em>Back</em> 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

  Message from some other activity, then pressing <em>Back</em> would have

  returned there.

</p>

<p>

  By contrast, the next figure shows the user leaving List Messages by

  pressing HOME instead of BACK — the List Messages activity is

  pressing <em>Home</em> instead of <em>Back</em> &mdash; 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

<p>

  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

  destroyed when <em>Back</em> is pressed. When the user starts playing music in

  the Music application and then presses <em>Back</em>, 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

  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 >

  chooses Contacts, selects the contact for viewing, chooses <em>Menu</em> &gt;

  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

  <b>Gallery Re-Uses Messaging for Sharing a Picture</b> - 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

  starts Gallery, picks a picture to view, chooses <em>Menu</em> &gt; 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

  Gallery, they must press the <em>Back</em> button. (The user can back up through

  each activity all the way to Home.)

</p>

  <ul>

    <li>

      State 2 - The user wants to do something else while they're

      waiting, so they press HOME, which does not interrupt the map's

      waiting, so they press <em>Home</em>, which does not interrupt the map's

      network connection and allows the map to continue loading in the

      background.

        <b>Start first task.</b> You want to send a text message and attach a photo. You would choose:

        <p>

          Home > Messaging > New message > MENU > Attach

          Home &gt; Messaging &gt; New message &gt; <em>Menu</em> &gt; Attach

          > Pictures. This last step launches the picture gallery

          for picking a photo. Notice that picture gallery is an

          activity in a separate application.

          address in an email message (or web page), where the Maps

          activity is started to map the location. No result from maps

          is expected to be returned to the email message; the user

          can return by pressing the BACK key. (Such an activity is

          can return by pressing the <em>Back</em> button. (Such an activity is

          started with {@link

          android.content.Context#startActivity(android.content.Intent)

          startActivity()}.)

  convenience to respond to your message.

</p>

<h3 id=taking_over_back_key>Don't take over the BACK key unless you absolutely need to</h3>

<h3 id=taking_over_back_key>Don't take over the <em>Back</em> button unless you absolutely need

to</h3>

<p>

  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

  accessible with the <em>Back</em> button. 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

  needs finer-grained control of the <em>Back</em> button? 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

  <em>Back</em> button and maintain their own internal back stacks that operate

  only when these applications have focus.

</p>

  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

  stores these layers in its own history so the <em>Back</em> button can return to

  a previous layer.

</p>

  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

  then pressing <em>Back</em> would to the search results page. Pressing

  <em>Back</em> 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.

  <ul>

    <li>The <em>Options menu</em> contains primary functionality that applies

        globally to the current activity or starts a related activity. 

        It is typically invoked by a user pressing a hard button, often labeled MENU.</li>

        It is typically invoked by a user pressing a hard button, often labeled <em>Menu</em>.</li>

    <li>The <em>Context menu</em> contains secondary functionality for the currently

        selected item.  It is typically invoked by a user's touch & hold

        on an item.  Like on the Options menu, the operation can run either

</p>

<p>

  On most devices, a user presses the MENU button to access the Options menu, 

  On most devices, a user presses the <em>Menu</em> button to access the Options menu, 

  as shown in the screenshot below.  To close the menu, the user presses 

  MENU again, or presses the BACK button. 

  In fact, to cancel out of any menu, press the BACK button.  (Pressing the MENU

  <em>Menu</em> again, or presses the <em>Back</em> button. 

  In fact, to cancel out of any menu, press the <em>Back</em> button.  (Pressing the <em>Menu</em>

  button or touching outside the menu also works.)  Note that how to invoke this

  menu may be different on different devices.

</p>

<ul>

  <li>

    <b>Options icon menu</b> - The first press of the MENU button displays a

    <b>Options icon menu</b> - The first press of the <em>Menu</em> button displays a

    non-scrollable grid of icons at the bottom of the screen.  (On the G1

    phone, up to 6 buttons typically appear.)

  </li>

<p>

  On some versions of Android, the user can display keyboard shortcuts in the

  icon menu by long pressing the MENU button — the text in the icon menu

  icon menu by long pressing the <em>Menu</em> button &mdash; the text in the icon menu

  alternates between the command names and their keyboard shortcuts (if any).

</p>

  <a href="#location">location</a>) on the screen, put the command in the

  Context menu for that content.  If the command acts on no specific content

  or location, put it in the Options menu.  This separation of commands

  is enforced by the system in the following way.  When you press the MENU

  is enforced by the system in the following way.  When you press the <em>Menu</em>

  button to display the Options menu, the selected content becomes unselected,

  and so cannot be operated on.  For an explanation

  of why the content becomes unselected, see the article on

<p>

  Before opening a Context menu, it has no visual representation that identifies

  its presence (whereas the Options menu has the MENU button), and so is not

  its presence (whereas the Options menu has the <em>Menu</em> button), and so is not

  particularly discoverable. 

  Therefore, in general, a Context menu should <em>duplicate</em> commands 

  found in the corresponding activity screen.  For example, while it's useful to

<h3 id="a_dialog_should_not_have_an_options_menu">A dialog should not have an Options menu</h3>

<p>

  When a dialog is displayed, pressing the MENU button should do nothing.  This also holds true

  When a dialog is displayed, pressing the <em>Menu</em> button should do nothing.  This also holds

true

  for activities that look like dialogs.  A dialog box is recognizable by being

  smaller than full-screen, having zero to three buttons, is non-scrollable, and 

  possibly a list of selectable items that can include checkboxes or radio buttons.

<h3 id="do_not_substitute_message">If an activity has no Options menu, do not display a message</h3>

<p>

  When the user presses the MENU button, if there is no Options menu, the system

  When the user presses the <em>Menu</em> button, if there is no Options menu, the system

  currently does nothing.  We recommend you do not perform any action (such as

  displaying a message).  It's a better user experience for this behavior to be

  consistent across applications.

activity starts, the previous activity is stopped, but the system preserves the activity

in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and

takes user focus. The back stack abides to the basic "last in, first out" queue mechanism,

so, when the user is done with the current activity and presses the BACK key, it

so, when the user is done with the current activity and presses the <em>Back</em> button, it

is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is

discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks

and Back Stack</a> document.)</p>

<p class="note"><strong>Note:</strong> There's no guarantee that {@link

android.app.Activity#onSaveInstanceState onSaveInstanceState()} will be called before your

activity is destroyed, because there are cases in which it won't be necessary to save the state

(such as when the user leaves your activity using the BACK key, because the user is explicitly

(such as when the user leaves your activity using the <em>Back</em> button, because the user is

explicitly

closing the activity). If the system calls {@link android.app.Activity#onSaveInstanceState

onSaveInstanceState()}, it does so before {@link

android.app.Activity#onStop onStop()} and possibly before {@link android.app.Activity#onPause

fragment transaction, you can also add it to a back stack that's managed by the

activity—each back stack entry in the activity is a record of the fragment transaction that

occurred. The back stack allows the user to reverse a fragment transaction (navigate backwards),

by pressing the BACK button.</p>

by pressing the <em>Back</em> button.</p>

<p>When you add a fragment as a part of your activity layout, it lives in a {@link

android.view.ViewGroup} inside the activity's view hierarchy and the fragment defines its own view

the activity layout) or {@link android.app.FragmentManager#findFragmentByTag

findFragmentByTag()} (for fragments that do or don't provide a UI).</li> 

  <li>Pop fragments off the back stack, with {@link

android.app.FragmentManager#popBackStack()} (simulating a BACK command by the user).</li>

android.app.FragmentManager#popBackStack()} (simulating a <em>Back</em> command by the user).</li>

  <li>Register a listener for changes to the back stack, with {@link

android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li>

</ul>

android.app.FragmentTransaction#commit()}, however, you might want to call {@link

android.app.FragmentTransaction#addToBackStack addToBackStack()}, in order to add the transaction

to a back stack of fragment transactions. This back stack is managed by the activity and allows

the user to return to the previous fragment state, by pressing the BACK key.</p>

the user to return to the previous fragment state, by pressing the <em>Back</em> button.</p>

<p>For example, here's how you can replace one fragment with another, and preserve the previous

state in the back stack:</p>

layout container identified by the {@code R.id.fragment_container} ID. By calling {@link

android.app.FragmentTransaction#addToBackStack addToBackStack()}, the replace transaction is

saved to the back stack so the user can reverse the transaction and bring back the

previous fragment by pressing the BACK key.</p>

previous fragment by pressing the <em>Back</em> button.</p>

<p>If you add multiple changes to the transaction (such as another {@link

android.app.FragmentTransaction#add add()} or {@link android.app.FragmentTransaction#remove

remove()}) and call {@link

android.app.FragmentTransaction#addToBackStack addToBackStack()}, then all changes applied

before you call {@link android.app.FragmentTransaction#commit commit()} are added to the

back stack as a single transaction and the BACK key will reverse them all together.</p>

back stack as a single transaction and the <em>Back</em> button will reverse them all together.</p>

<p>The order in which you add changes to a {@link android.app.FragmentTransaction} doesn't matter,

except:</p>

<p>The most significant difference in lifecycle between an activity and a fragment is how one is

stored in its respective back stack. An activity is placed into a back stack of activities

that's managed by the system when it's stopped, by default (so that the user can navigate back

to it with the BACK key, as discussed in <a

to it with the <em>Back</em> button, as discussed in <a

href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>).

However, a fragment is placed into a back stack managed by the host activity only when you

explicitly request that the instance be saved by calling {@link