summaryrefslogtreecommitdiffstats
path: root/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
diff options
context:
space:
mode:
authorScott Main <smain@google.com>2012-01-31 19:14:35 -0800
committerScott Main <smain@google.com>2012-02-06 14:09:00 -0800
commitcf9fe43ce95ed19e027fe34899be52816cbe7670 (patch)
tree76ec6467aa7a7803b33697fa6e0dc269340f381f /docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
parent0b2701b7344fb7b7b6f9a1c1c99c8ede81b49d2d (diff)
downloadframeworks_base-cf9fe43ce95ed19e027fe34899be52816cbe7670.zip
frameworks_base-cf9fe43ce95ed19e027fe34899be52816cbe7670.tar.gz
frameworks_base-cf9fe43ce95ed19e027fe34899be52816cbe7670.tar.bz2
docs: switch from caps to initial-case for device button names
Change-Id: I2affdf7400fd814e43633806cebebee4c6075b0b
Diffstat (limited to 'docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd')
-rw-r--r--docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd53
1 files changed, 34 insertions, 19 deletions
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 086ba71..465cf54 100644
--- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
+++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd
@@ -74,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 button.</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
@@ -94,22 +94,26 @@ 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
+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&mdash;pushed onto the stack when started by
-the current activity and popped off when the user leaves it using the BACK button. 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 button, 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>
@@ -124,11 +128,13 @@ class="img-caption"><strong>Figure 3.</strong> A single activity is instantiated
</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 button. 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&mdash;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&mdash;two under the current activity. The user presses the HOME button, then
+activities in its stack&mdash;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
@@ -137,7 +143,8 @@ started Task A. Now, Task A comes to the
foreground&mdash;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 button 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.
@@ -150,7 +157,8 @@ users to start a particular activity from more than one activity, a new instance
that activity is created and popped 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 button, 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>
@@ -161,13 +169,15 @@ 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 button 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 button, 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 button, 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>
@@ -256,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 button. 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>
@@ -320,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 button to return to the previous activity. But when an existing instance of
-an activity handles a new intent, the user cannot press the BACK button 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>
@@ -333,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 button 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;
@@ -351,7 +364,7 @@ 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 button always takes the user to the previous activity. However, if you
+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
@@ -454,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 button 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
@@ -556,7 +570,8 @@ 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 button. The task is now sent to the background and is
+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>