diff options
Diffstat (limited to 'docs/html/guide/topics/fundamentals')
4 files changed, 121 insertions, 91 deletions
diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd index cb453da..b79136c 100644 --- a/docs/html/guide/topics/fundamentals/activities.jd +++ b/docs/html/guide/topics/fundamentals/activities.jd @@ -19,9 +19,10 @@ page.title=Activities </li> <li><a href="#StartingAnActivity">Starting an Activity</a> <ol> - <li><a href="#StartingAnActivityForResult">Starting an Activity for a Result</a></li> + <li><a href="#StartingAnActivityForResult">Starting an activity for a result</a></li> </ol> </li> + <li><a href="#ShuttingDown">Shutting Down an Activity</a></li> <li><a href="#Lifecycle">Managing the Activity Lifecycle</a> <ol> <li><a href="#ImplementingLifecycleCallbacks">Implementing the lifecycle callbacks</a></li> @@ -61,8 +62,8 @@ is presented to the user when launching the application for the first time. Each activity can then start another activity in order to perform different actions. Each time a new 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 +takes user focus. The back stack abides to the basic "last in, first out" stack mechanism, +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> @@ -612,17 +613,9 @@ that when an activity is paused or stopped, the state of the activity is retained. This is true because the {@link android.app.Activity} object is still held in memory when it is paused or stopped—all information about its members and current state is still alive. Thus, any changes -the user made within the activity are retained in memory, so that when the activity returns to the +the user made within the activity are retained so that when the activity returns to the foreground (when it "resumes"), those changes are still there.</p> -<div class="figure" style="width:615px"> -<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> -<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user -focus with its state intact: either the activity is stopped, then resumed and the activity state -remains intact (left), or the activity is destroyed, then recreated and the activity must restore -the previous activity state (right).</p> -</div> - <p>However, when the system destroys an activity in order to recover memory, the {@link android.app.Activity} object is destroyed, so the system cannot simply resume it with its state intact. Instead, the system must recreate the {@link android.app.Activity} object if the user @@ -630,26 +623,36 @@ navigates back to it. Yet, the user is unaware that the system destroyed the activity and recreated it and, thus, probably expects the activity to be exactly as it was. In this situation, you can ensure that important information about the activity state is preserved by implementing an additional -callback method that allows you to save information about the state of your activity and then -restore it when the the system recreates the activity.</p> +callback method that allows you to save information about the state of your activity: {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> -<p>The callback method in which you can save information about the current state of your activity is -{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}. The system calls this method -before making the activity vulnerable to being destroyed and passes it -a {@link android.os.Bundle} object. The {@link android.os.Bundle} is where you can store +<p>The system calls {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +before making the activity vulnerable to destruction. The system passes this method +a {@link android.os.Bundle} in which you can save state information about the activity as name-value pairs, using methods such as {@link -android.os.Bundle#putString putString()}. Then, if the system kills your activity's -process and the user navigates back to your activity, the system passes the {@link -android.os.Bundle} to {@link android.app.Activity#onCreate onCreate()} so you can restore the -activity state you saved during {@link android.app.Activity#onSaveInstanceState -onSaveInstanceState()}. If there is no state information to restore, then the {@link -android.os.Bundle} passed to {@link android.app.Activity#onCreate onCreate()} is null.</p> +android.os.Bundle#putString putString()} and {@link +android.os.Bundle#putInt putInt()}. Then, if the system kills your application +process and the user navigates back to your activity, the system recreates the activity and passes +the {@link android.os.Bundle} to both {@link android.app.Activity#onCreate onCreate()} and {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}. Using either of these +methods, you can extract your saved state from the {@link android.os.Bundle} and restore the +activity state. If there is no state information to restore, then the {@link +android.os.Bundle} passed to you is null (which is the case when the activity is created for +the first time).</p> + +<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> The two ways in which an activity returns to user +focus with its state intact: either the activity is destroyed, then recreated and the activity must restore +the previously saved state, or the activity is stopped, then resumed and the activity state +remains intact.</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 -closing the activity). If the method is called, it is always called before {@link +(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 onPause()}.</p> @@ -657,17 +660,17 @@ onPause()}.</p> android.app.Activity#onSaveInstanceState onSaveInstanceState()}, some of the activity state is restored by the {@link android.app.Activity} class's default implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}. Specifically, the default -implementation calls {@link -android.view.View#onSaveInstanceState onSaveInstanceState()} for every {@link android.view.View} -in the layout, which allows each view to provide information about itself +implementation calls the corresponding {@link +android.view.View#onSaveInstanceState onSaveInstanceState()} method for every {@link +android.view.View} in the layout, which allows each view to provide information about itself that should be saved. Almost every widget in the Android framework implements this method as appropriate, such that any visible changes to the UI are automatically saved and restored when your activity is recreated. For example, the {@link android.widget.EditText} widget saves any text entered by the user and the {@link android.widget.CheckBox} widget saves whether it's checked or not. The only work required by you is to provide a unique ID (with the <a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> -attribute) for each widget you want to save its state. If a widget does not have an ID, then it -cannot save its state.</p> +attribute) for each widget you want to save its state. If a widget does not have an ID, then the +system cannot save its state.</p> <div class="sidebox-wrapper"> <div class="sidebox"> @@ -689,7 +692,9 @@ restored, by default).</p> android.app.Activity#onSaveInstanceState onSaveInstanceState()} helps save the state of the UI, if you override the method in order to save additional state information, you should always call the superclass implementation of {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} -before doing any work.</p> +before doing any work. Likewise, you should also call the supercall implementation of {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} if you override it, so the +default implementation can restore view states.</p> <p class="note"><strong>Note:</strong> Because {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} is not guaranteed @@ -701,7 +706,7 @@ to a database) when the user leaves the activity.</p> <p>A good way to test your application's ability to restore its state is to simply rotate the device so that the screen orientation changes. When the screen orientation changes, the system destroys and recreates the activity in order to apply alternative resources that might be available -for the new orientation. For this reason alone, it's very important that your activity +for the new screen configuration. For this reason alone, it's very important that your activity completely restores its state when it is recreated, because users regularly rotate the screen while using applications.</p> @@ -709,22 +714,25 @@ using applications.</p> <h3 id="ConfigurationChanges">Handling configuration changes</h3> <p>Some device configurations can change during runtime (such as screen orientation, keyboard -availability, and language). When such a change occurs, Android restarts the running Activity -({@link android.app.Activity#onDestroy} is called, followed immediately by {@link -android.app.Activity#onCreate onCreate()}). The restart behavior is +availability, and language). When such a change occurs, Android recreates the running activity +(the system calls {@link android.app.Activity#onDestroy}, then immediately calls {@link +android.app.Activity#onCreate onCreate()}). This behavior is designed to help your application adapt to new configurations by automatically reloading your -application with alternative resources that you've provided. If you design your activity to -properly handle this event, it will be more resilient to unexpected events in the activity -lifecycle.</p> +application with alternative resources that you've provided (such as different layouts for +different screen orientations and sizes).</p> + +<p>If you properly design your activity to handle a restart due to a screen orientation change and +restore the activity state as described above, your application will be more resilient to other +unexpected events in the activity lifecycle.</p> -<p>The best way to handle a configuration change, such as a change in the screen orientation, is - to simply preserve the state of your application using {@link +<p>The best way to handle such a restart is + to save and restore the state of your activity using {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} and {@link android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (or {@link android.app.Activity#onCreate onCreate()}), as discussed in the previous section.</p> -<p>For a detailed discussion about configuration changes that happen at runtime and how you should -handle them, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling +<p>For more information about configuration changes that happen at runtime and how you can handle +them, read the guide to <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</p> diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd index d6ba646..e0740aa 100644 --- a/docs/html/guide/topics/fundamentals/fragments.jd +++ b/docs/html/guide/topics/fundamentals/fragments.jd @@ -33,7 +33,7 @@ parent.link=activities.html </li> <li><a href="#Lifecycle">Handling the Fragment Lifecycle</a> <ol> - <li><a href="#CoordinadingWithActivity">Coordinating with the activity lifecycle</a></li> + <li><a href="#CoordinatingWithActivity">Coordinating with the activity lifecycle</a></li> </ol> </li> <li><a href="#Example">Example</a></li> @@ -78,7 +78,7 @@ manipulate each fragment independently, such as add or remove them. When you per 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 @@ -129,7 +129,7 @@ handset design.</p> <p>For example—to continue with the news application example—the application can embed two fragments in <em>Activity A</em>, when running on a tablet-sized device. However, on a -handset-sized screen, there's not be enough room for both fragments, so <em>Activity A</em> includes +handset-sized screen, there's not enough room for both fragments, so <em>Activity A</em> includes only the fragment for the list of articles, and when the user selects an article, it starts <em>Activity B</em>, which includes the second fragment to read the article. Thus, the application supports both tablets and handsets by reusing fragments in different combinations, as illustrated in @@ -143,7 +143,7 @@ href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets an <h2 id="Creating">Creating a Fragment</h2> -<div class="figure" style="width:314px"> +<div class="figure" style="width:327px"> <img src="{@docRoot}images/fragment_lifecycle.png" alt="" /> <p class="img-caption"><strong>Figure 2.</strong> The lifecycle of a fragment (while its activity is running).</p> @@ -398,7 +398,7 @@ android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments 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> @@ -439,7 +439,7 @@ to the activity, you must call {@link android.app.FragmentTransaction#commit()}. 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> @@ -462,14 +462,14 @@ transaction.commit(); 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> @@ -657,7 +657,7 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guides. <h2 id="Lifecycle">Handling the Fragment Lifecycle</h2> -<div class="figure" style="width:403px"> +<div class="figure" style="width:350px"> <img src="{@docRoot}images/activity_fragment_lifecycle.png" alt=""/> <p class="img-caption"><strong>Figure 3.</strong> The activity lifecycle's affect on the fragment lifecycle.</p> @@ -696,7 +696,7 @@ document.</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 diff --git a/docs/html/guide/topics/fundamentals/loaders.jd b/docs/html/guide/topics/fundamentals/loaders.jd index 3aad204..ddd513b 100644 --- a/docs/html/guide/topics/fundamentals/loaders.jd +++ b/docs/html/guide/topics/fundamentals/loaders.jd @@ -491,7 +491,7 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/Load LoaderCursor</a> — A complete version of the snippet shown above.</li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> — An example of how to use throttling to -reduce the number of queries a content provider does then its data changes.</li> +reduce the number of queries a content provider does when its data changes.</li> </ul> <p>For information on downloading and installing the SDK samples, see <a diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd index 216420c..0880614 100644 --- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd +++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd @@ -34,7 +34,9 @@ to perform other tasks without losing their work</li> <h2>See also</h2> <ol> - <li><a><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> + <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: +Navigation</a></li> + <li><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> <li><a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest element</a></li> @@ -72,7 +74,7 @@ order in which each activity is opened.</p> suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the other being a layout to display an item from the list (fragment B). When the user selects an item from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be -desireable for the user to navigate back to reveal fragment B, using the BACK key.</p> +desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p> <p>In order to add fragment B to the back stack so that this is possible, you must call {@link android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment @@ -92,41 +94,47 @@ is created and the "main" activity for that application opens as the root activi <p>When the current activity starts another, the new activity is pushed on the top of the stack and takes focus. The previous activity remains in the stack, but is stopped. When an activity -stops, the system retains the current state of its user interface. When the user presses the BACK -key, the current activity is popped from the top of the stack (the activity is destroyed) and the +stops, the system retains the current state of its user interface. When the user presses the +<em>Back</em> +button, the current activity is popped from the top of the stack (the activity is destroyed) and the previous activity resumes (the previous state of its UI is restored). Activities in the stack are never rearranged, only pushed and popped from the stack—pushed onto the stack when started by -the current activity and popped off when the user leaves it using the BACK key. As such, the back +the current activity and popped off when the user leaves it using the <em>Back</em> button. As such, +the back stack operates as a "last in, first out" object structure. Figure 1 visualizes this behavior with a timeline showing the progress between activities along with the current back stack at each point in time.</p> <img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> <p class="img-caption"><strong>Figure 1.</strong> A representation of how each new activity in a -task adds an item to the back stack. When the user presses the BACK key, the current activity is +task adds an item to the back stack. When the user presses the <em>Back</em> button, the current +activity is destroyed and the previous activity resumes.</p> -<p>If the user continues to press BACK, then each activity in the stack is popped off to reveal the +<p>If the user continues to press <em>Back</em>, then each activity in the stack is popped off to +reveal the previous one, until the user returns to the Home screen (or to whichever activity was running when the task began). When all activities are removed from the stack, the task no longer exists.</p> -<div class="figure" style="width:369px"> +<div class="figure" style="width:287px"> <img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p -class="img-caption"><strong>Figure 2.</strong> Two tasks: Task A is in the background, waiting -to be resumed, while Task B receives user interaction in the foreground.</p> +class="img-caption"><strong>Figure 2.</strong> Two tasks: Task B receives user interaction +in the foreground, while Task A is in the background, waiting to be resumed.</p> </div> -<div class="figure" style="width:178px"> +<div class="figure" style="width:215px"> <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated multiple times.</p> </div> <p>A task is a cohesive unit that can move to the "background" when users begin a new task or go -to the Home screen, via the HOME key. While in the background, all the activities in the task are +to the Home screen, via the <em>Home</em> button. While in the background, all the activities in the +task are stopped, but the back stack for the task remains intact—the task has simply lost focus while another task takes place, as shown in figure 2. A task can then return to the "foreground" so users can pick up where they left off. Suppose, for example, that the current task (Task A) has three -activities in its stack—two under the current activity. The user presses the HOME key, then +activities in its stack—two under the current activity. The user presses the <em>Home</em> +button, then starts a new application from the application launcher. When the Home screen appears, Task A goes into the background. When the new application starts, the system starts a task for that application (Task B) with its own stack of activities. After interacting with @@ -135,7 +143,8 @@ started Task A. Now, Task A comes to the foreground—all three activities in its stack are intact and the activity at the top of the stack resumes. At this point, the user can also switch back to Task B by going Home and selecting the application icon -that started that task (or by touching and holding the HOME key to reveal recent tasks and selecting +that started that task (or by touching and holding the <em>Home</em> button to reveal recent tasks +and selecting one). This is an example of multitasking on Android.</p> <p class="note"><strong>Note:</strong> Multiple tasks can be held in the background at once. @@ -145,10 +154,11 @@ See the following section about <a href="#ActivityState">Activity state</a>.</p> <p>Because the activities in the back stack are never rearranged, if your application allows users to start a particular activity from more than one activity, a new instance of -that activity is created and popped onto the stack (rather than bringing any previous instance of +that activity is created and pushed onto the stack (rather than bringing any previous instance of the activity to the top). As such, one activity in your application might be instantiated multiple times (even from different tasks), as shown in figure 3. As such, if the user navigates backward -using the BACK key, each instance of the activity is revealed in the order they were opened (each +using the <em>Back</em> button, each instance of the activity is revealed in the order they were +opened (each with their own UI state). However, you can modify this behavior if you do not want an activity to be instantiated more than once. How to do so is discussed in the later section about <a href="#ManagingTasks">Managing Tasks</a>.</p> @@ -159,19 +169,28 @@ href="#ManagingTasks">Managing Tasks</a>.</p> <ul> <li>When Activity A starts Activity B, Activity A is stopped, but the system retains its state (such as scroll position and text entered into forms). -If the user presses the BACK key while in Activity B, Activity A resumes with its state +If the user presses the <em>Back</em> button while in Activity B, Activity A resumes with its state restored.</li> - <li>When the user leaves a task by pressing the HOME key, the current activity is stopped and + <li>When the user leaves a task by pressing the <em>Home</em> button, the current activity is +stopped and its task goes into the background. The system retains the state of every activity in the task. If the user later resumes the task by selecting the launcher icon that began the task, the task comes to the foreground and resumes the activity at the top of the stack.</li> - <li>If the user presses the BACK key, the current activity is popped from the stack and + <li>If the user presses the <em>Back</em> button, the current activity is popped from the stack +and destroyed. The previous activity in the stack is resumed. When an activity is destroyed, the system <em>does not</em> retain the activity's state.</li> <li>Activities can be instantiated multiple times, even from other tasks.</li> </ul> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how app navigation works on Android, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + + <h2 id="ActivityState">Saving Activity State</h2> <p>As discussed above, the system's default behavior preserves the state of an activity when it is @@ -247,7 +266,8 @@ flags to define how activities are associated with tasks and how the behave in t <p class="caution"><strong>Caution:</strong> Most applications should not interrupt the default behavior for activities and tasks. If you determine that it's necessary for your activity to modify the default behaviors, use caution and be sure to test the usability of the activity during -launch and when navigating back to it from other activities and tasks with the BACK key. Be sure +launch and when navigating back to it from other activities and tasks with the <em>Back</em> button. +Be sure to test for navigation behaviors that might conflict with the user's expected behavior.</p> @@ -271,7 +291,7 @@ B should associate with current task. If both activities define how Activity B should associate with a task, then Activity A's request (as defined in the intent) is honored over Activity B's request (as defined in its manifest).</p> -<p class="note"><strong>Note:</strong> Some the launch modes available in the manifest +<p class="note"><strong>Note:</strong> Some launch modes available for the manifest file are not available as flags for an intent and, likewise, some launch modes available as flags for an intent cannot be defined in the manifest.</p> @@ -311,8 +331,10 @@ android.app.Activity#onNewIntent onNewIntent()}, because it's at the top of the stack remains A-B-C-D. However, if an intent arrives for an activity of type B, then a new instance of B is added to the stack, even if its launch mode is {@code "singleTop"}.</p> <p class="note"><strong>Note:</strong> When a new instance of an activity is created, -the user can press the BACK key to return to the previous activity. But when an existing instance of -an activity handles a new intent, the user cannot press the BACK key to return to the state of +the user can press the <em>Back</em> button to return to the previous activity. But when an existing +instance of +an activity handles a new intent, the user cannot press the <em>Back</em> button to return to the +state of the activity before the new intent arrived in {@link android.app.Activity#onNewIntent onNewIntent()}.</p> </dd> @@ -324,7 +346,7 @@ intent to the existing instance through a call to its {@link android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a new instance. Only one instance of the activity can exist at a time. <p class="note"><strong>Note:</strong> Although the activity starts in a new task, the -BACK key still returns the user to the previous activity.</p></dd> +<em>Back</em> button still returns the user to the previous activity.</p></dd> <dt>{@code "singleInstance"}.</dt> <dd>Same as {@code "singleTask"}, except that the system doesn't launch any other activities into the task holding the instance. The activity is always the single and only member of its task; @@ -342,19 +364,17 @@ already has a task running in the background, that task is brought forward to ha intent.</p> <p>Regardless of whether an activity starts in a new task or in the same task as the activity that -started it, the BACK key always takes the user to the previous activity. However, if you -start an activity from your task (Task A) that specifies the {@code singleTask} launch mode, then -that activity might have an instance in the background that belongs to a task with its own back -stack (Task B). In this -case, when Task B is brought forward to handle a new intent, the BACK key first navigates -backward through the activities in Task B before returning to -the top-most activity in Task A. Figure 4 visualizes this type of scenario.</p> +started it, the <em>Back</em> button always takes the user to the previous activity. However, if you +start an activity that specifies the {@code singleTask} launch mode, then if an instance of +that activity exists in a background task, that whole task is brought to the foreground. At this +point, the back stack now includes all activities from the task brought forward, at the top of the +stack. Figure 4 illustrates this type of scenario.</p> <img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> <p class="img-caption"><strong>Figure 4.</strong> A representation of how an activity with launch mode "singleTask" is added to the back stack. If the activity is already a part of a -background task with its own back stack (Task B), then the entire back stack also comes -forward, on top of the current task (Task A).</p> +background task with its own back stack, then the entire back stack also comes +forward, on top of the current task.</p> <p>For more information about using launch modes in the manifest file, see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> @@ -447,7 +467,8 @@ flag, the system looks for a different task to house the new activity. Often, it However, it doesn't have to be. If there's already an existing task with the same affinity as the new activity, the activity is launched into that task. If not, it begins a new task.</p> -<p>If this flag causes an activity to begin a new task and the user presses the HOME key to leave +<p>If this flag causes an activity to begin a new task and the user presses the <em>Home</em> button +to leave it, there must be some way for the user to navigate back to the task. Some entities (such as the notification manager) always start activities in an external task, never as part of their own, so they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to {@link @@ -549,9 +570,10 @@ android.content.Intent#ACTION_MAIN} and a {@link android.content.Intent#CATEGORY_LAUNCHER} filter. Imagine, for example, what could happen if the filter is missing: An intent launches a {@code "singleTask"} activity, initiating a new task, and the user spends some time working in -that task. The user then presses the HOME key. The task is now sent to the background and not -visible. Because it is not represented in the application launcher, the user has no way to return to -the task. +that task. The user then presses the <em>Home</em> button. The task is now sent to the background +and is +not visible. Now the user has no way to return to the task, because it is not represented in the +application launcher. </p> <p>For those cases where you don't want the user to be able to return to an activity, set the |