Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 770f57e0: am 321e7645: Merge "docs: Recents screen for tasks and activities" into lmp-dev

Browse Source 
* commit '770f57e06837c8d2b7e42776b569b568d2360057':
  docs: Recents screen for tasks and activities
This commit is contained in:
Joe Fernandez
2014-10-17 18:52:04 +00:00
committed by Android Git Automerger
parent 5380545023 770f57e068
commit 39f69b7984
5 changed files with 431 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
docs/html/guide/components/recents.jd Normal file
View File

@@ -0,0 +1,256 @@
page.title=Overview Screen
page.tags="recents","overview"
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#adding">Adding Tasks to the Overview Screen</a>
<ol>
<li><a href="#flag-new-doc">Using the Intent flag to add a task</a></li>
<li><a href="#attr-doclaunch">Using the Activity attribute to add a task</a></li>
</ol>
</li>
<li><a href="#removing">Removing Tasks</a>
<ol>
<li><a href="#apptask-remove">Using the AppTask class to remove tasks</a></li>
<li><a href="#retain-finished">Retaining finished tasks</a></li>
</ol>
</li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.ActivityManager.AppTask}</li>
<li>{@link android.content.Intent}</li>
</ol>
<h2>Sample code</h2>
<ol>
<li><a href="{@docRoot}samples/activitytasks/index.html">Document-centric Apps</a></li>
</ol>
</div>
</div>
<p>The overview screen (also referred to as the recents screen, recent task list, or recent apps)
is a system-level UI that lists recently accessed <a href="{@docRoot}guide/components/activities.html">
activities</a> and <a href="{@docRoot}guide/components/tasks-and-back-stack.html">tasks</a>. The
user can navigate through the list and select a task to resume, or the user can remove a task from
the list by swiping it away. With the Android 5.0 release (API level 21), multiple instances of the
same activity containing different documents may appear as tasks in the overview screen. For example,
Google Drive may have a task for each of several Google documents. Each document appears as a
task in the overview screen.</p>
<img src="{@docRoot}images/components/recents.png" alt="" width="284" />
<p class="img-caption"><strong>Figure 1.</strong> The overview screen showing three Google Drive
documents, each represented as a separate task.</p>
<p>Normally you should allow the system to define how your tasks and
activities are represented in the overview screen, and you don't need to modify this behavior.
However, your app can determine how and and when activities appear in the overview screen. The
{@link android.app.ActivityManager.AppTask} class lets you manage tasks, and the activity flags of
the {@link android.content.Intent} class let you specify when an activity is added or removed from
the overview screen. Also, the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">
&lt;activity&gt;</a></code> attributes let you set the behavior in the manifest.</p>
<h2 id="adding">Adding Tasks to the Overview Screen</h2>
<p>Using the flags of the {@link android.content.Intent} class to add a task affords greater control
over when and how a document gets opened or reopened in the overview screen. When you use the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
attributes you can choose between always opening the document in a new task or reusing an
existing task for the document.</p>
<h3 id="flag-new-doc">Using the Intent flag to add a task</h3>
<p>When you create a new document for your activity, you call the
{@link android.app.ActivityManager.AppTask#startActivity(android.content.Context, android.content.Intent, android.os.Bundle) startActivity()}
method of the {@link android.app.ActivityManager.AppTask} class, passing to it the intent that
launches the activity. To insert a logical break so that the system treats your activity as a new
task in the overview screen, pass the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag
in the {@link android.content.Intent#addFlags(int) addFlags()} method of the {@link android.content.Intent}
that launches the activity.</p>
<p class="note"><strong>Note:</strong> The {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}
flag replaces the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET} flag,
which is deprecated as of Android 5.0 (API level 21).</p>
<p>If you set the {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag when you create
the new document, the system always creates a new task with the target activity as the root.
This setting allows the same document to be opened in more than one task. The following code demonstrates
how the main activity does this:</p>
<p class="code-caption"><a href="{@docRoot}samples/activitytasks/src/com/example/android/documentcentricrecents/DocumentCentricActivity.html">
DocumentCentricActivity.java</a></p>
<pre>
public void createNewDocument(View view) {
final Intent newDocumentIntent = newDocumentIntent();
if (useMultipleTasks) {
newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_MULTIPLE_TASK);
}
startActivity(newDocumentIntent);
}
private Intent newDocumentIntent() {
boolean useMultipleTasks = mCheckbox.isChecked();
final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class);
newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT);
newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet());
return newDocumentIntent;
}
private static int incrementAndGet() {
Log.d(TAG, "incrementAndGet(): " + mDocumentCounter);
return mDocumentCounter++;
}
}
</pre>
<p class="note"><strong>Note:</strong> Activities launched with the {@code FLAG_ACTIVITY_NEW_DOCUMENT}
flag must have the {@code android:launchMode="standard"} attribute value (the default) set in the
manifest.</p>
<p>When the main activity launches a new activity, the system searches through existing tasks for
one whose intent matches the intent component name and the Intent data for the activity. If the task
is not found, or the intent contained the {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}
flag, a new task will be created with the activity as its root. If it finds one, it brings that task
to the front and passes the new intent to {@link android.app.Activity#onNewIntent onNewIntent()}.
The new activity gets the intent and creates a new document in the overview screen, as in the
following example:</p>
<p class="code-caption"><a href="{@docRoot}samples/activitytasks/src/com/example/android/documentcentricrecents/NewDocumentActivity.html">
NewDocumentActivity.java</a></p>
<pre>
&#64;Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_new_document);
mDocumentCount = getIntent()
.getIntExtra(DocumentCentricActivity.KEY_EXTRA_NEW_DOCUMENT_COUNTER, 0);
mDocumentCounterTextView = (TextView) findViewById(
R.id.hello_new_document_text_view);
setDocumentCounterText(R.string.hello_new_document_counter);
}
&#64;Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
/* If FLAG_ACTIVITY_MULTIPLE_TASK has not been used, this activity
is reused to create a new document.
*/
setDocumentCounterText(R.string.reusing_document_counter);
}
</pre>
<h3 id="#attr-doclaunch">Using the activity attribute to add a task</h3>
<p>An activity can also specify in its manifest that it always launches into a new task by using
the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
attribute, <a href="{@docRoot}guide/topics/manifest/activity-element.html#dlmode">
{@code android:documentLaunchMode}</a>. This attribute has four values which produce the following
effects when the user opens a document with the application:</p>
<dl>
<dt>"{@code intoExisting}"</dt>
<dd>The activity reuses an existing task for the document. This is the same as setting the
{@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag <em>without</em> setting the
{@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag, as described in
<a href="#flag-new-doc">Using the Intent flag to add a task</a>, above.</dd>
<dt>"{@code always}"</dt>
<dd>The activity creates a new task for the document, even if the document is already opened. Using
this value is the same as setting both the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}
and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags.</dd>
<dt>"{@code none”}"</dt>
<dd>The activity does not create a new task for the document. The overview screen treats the
activity as it would by default: it displays a single task for the app, which
resumes from whatever activity the user last invoked.</dd>
<dt>"{@code never}"</dt>
<dd>The activity does not create a new task for the document. Setting this value overrides the
behavior of the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}
and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags, if either of these are set
in the intent, and the overview screen displays a single task for the app, which resumes from
whatever activity the user last invoked.</dd>
</dl>
<p class="note"><strong>Note:</strong> For values other than {@code none} and {@code never} the
activity must be defined with {@code launchMode="standard"}. If this attribute is not specified,
{@code documentLaunchMode="none"} is used.</p>
<h2 id="removing">Removing Tasks</h2>
<p>By default a document task is automatically removed from the overview screen when its activity
finishes. You can override this behavior with the {@link android.app.ActivityManager.AppTask} class,
with an {@link android.content.Intent} flag, or with an<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">
&lt;activity&gt;</a></code> attribute.</p>
<p>You can always exclude a task from the overview screen entirely by setting the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
attribute, <a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude">
{@code android:excludeFromRecents}</a> to {@code true}.</p>
<p>You can set the maximum number of tasks that your app can include in the overview screen by setting
the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
attribute <a href="{@docRoot}guide/topics/manifest/activity-element.html#maxrecents">{@code android:maxRecents}
</a> to an integer value. The default is 16. When the maximum number of tasks is reached, the least
recently used task is removed from the overview screen. The {@code android:maxRecents} maximum value
is 50 (25 on low memory devices); values less than 1 are not valid.</p>
<h3 id="#apptask-remove">Using the AppTask class to remove tasks</h3>
<p>In the activity that creates a new task in the overview screen, you can
specify when to remove the task and finish all activities associated with it by calling
the {@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()} method.</p>
<p class="code-caption"><a href="{@docRoot}samples/activitytasks/index.html">
NewDocumentActivity.java</a></p>
<pre>
public void onRemoveFromRecents(View view) {
// The document is no longer needed; remove its task.
finishAndRemoveTask();
}
</pre>
<p class="note"><strong>Note:</strong> Using the
{@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()} method
overrides the use of the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} tag,
discussed below.</p>
<h3 id="#retain-finished">Retaining finished tasks</h3>
<p>If you want to retain a task in the overview screen, even if its activity has finished, pass
the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} flag in the
{@link android.content.Intent#addFlags(int) addFlags()} method of the Intent that launches the activity.</p>
<p class="code-caption"><a href="{@docRoot}samples/activitytasks/src/com/example/android/documentcentricrecents/DocumentCentricActivity.html">
DocumentCentricActivity.java</a></p>
<pre>
private Intent newDocumentIntent() {
final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class);
newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT |
android.content.Intent.FLAG_ACTIVITY_RETAIN_IN_RECENTS);
newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet());
return newDocumentIntent;
}
</pre>
<p>To achieve the same effect, set the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
attribute <a href="{@docRoot}guide/topics/manifest/activity-element.html#autoremrecents">
{@code android:autoRemoveFromRecents}</a> to {@code false}. The default value is {@code true}
for document activities, and {@code false} for regular activities. Using this attribute overrides
the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} flag, discussed previously.</p>

152
docs/html/guide/components/tasks-and-back-stack.jd
View File

@@ -21,7 +21,8 @@ parent.link=activities.html
<h2>Articles</h2>
<ol>
<li><a href="http://android-developers.blogspot.com/2010/04/multitasking-android-way.html">Multitasking the Android Way</a></li>
<li><a href="http://android-developers.blogspot.com/2010/04/multitasking-android-way.html">
Multitasking the Android Way</a></li>
</ol>
<h2>See also</h2>
@@ -31,6 +32,7 @@ Navigation</a></li>
<li><a
href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;} manifest
element</a></li>
<li><a href="{@docRoot}guide/components/recents.html">Overview Screen</a></li>
</ol>
</div>
</div>
@@ -39,12 +41,12 @@ element</a></li>
<p>An application usually contains multiple <a
href="{@docRoot}guide/components/activities.html">activities</a>. Each activity
should be designed around a specific kind of action the user can perform and can start other
activities. For example, an email application might have one activity to show a list of new email.
When the user selects an email, a new activity opens to view that email.</p>
activities. For example, an email application might have one activity to show a list of new messages.
When the user selects a message, a new activity opens to view that message.</p>
<p>An activity can even start activities that exist in other applications on the device. For
example, if your application wants to send an email, you can define an intent to perform a "send"
action and include some data, such as an email address and a message. An activity from another
example, if your application wants to send an email message, you can define an intent to perform a
"send" action and include some data, such as an email address and a message. An activity from another
application that declares itself to handle this kind of intent then opens. In this case, the intent
is to send an email, so an email application's "compose" activity starts (if multiple activities
support the same intent, then the system lets the user select which one to use). When the email is
@@ -53,8 +55,8 @@ though the activities may be from different applications, Android maintains this
experience by keeping both activities in the same <em>task</em>.</p>
<p>A task is a collection of activities that users interact with
when performing a certain job. The activities are arranged in a stack (the "back stack"), in the
order in which each activity is opened.</p>
when performing a certain job. The activities are arranged in a stack (the <em>back stack</em>), in
the order in which each activity is opened.</p>
<!-- SAVE FOR WHEN THE FRAGMENT DOC IS ADDED
<div class="sidebox-wrapper">
@@ -134,7 +136,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 selecting the app's task from the <em>recent apps</em> screen).
that started that task (or by selecting the app's task from the
<a href="{@docRoot}guide/components/recents.html">overview screen</a>).
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.
@@ -195,8 +198,8 @@ system memory. When this happens, information about the activity state is lost.
system still
knows that the activity has a place in the back stack, but when the activity is brought to the
top of the stack the system must recreate it (rather than resume it). In order to
avoid losing the user's work, you should proactively retain it by implementing the {@link
android.app.Activity#onSaveInstanceState onSaveInstanceState()} callback
avoid losing the user's work, you should proactively retain it by implementing the
{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} callback
methods in your activity.</p>
<p>For more information about how to save your activity state, see the <a
@@ -218,27 +221,26 @@ instance on top of the back stack); or, you want your back stack to be cleared o
activities except for the root activity when the user leaves the task.</p>
<p>You can do these things and more, with attributes in the
<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
&lt;activity&gt;}</a> manifest element and with flags in the intent that you pass to {@link
android.app.Activity#startActivity startActivity()}.</p>
<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
manifest element and with flags in the intent that you pass to
{@link android.app.Activity#startActivity startActivity()}.</p>
<p>In this regard, the principal <a
href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
attributes you can use are:</p>
<p>In this regard, the principal <a href="{@docRoot}guide/topics/manifest/activity-element.html">
{@code &lt;activity&gt;}</a> attributes you can use are:</p>
<ul class="nolist">
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code
taskAffinity}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code
launchMode}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code
allowTaskReparenting}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code
clearTaskOnLaunch}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code
alwaysRetainTaskState}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code
finishOnTaskLaunch}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">
{@code taskAffinity}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">
{@code launchMode}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">
{@code allowTaskReparenting}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear">
{@code clearTaskOnLaunch}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always">
{@code alwaysRetainTaskState}</a></li>
<li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">
{@code finishOnTaskLaunch}</a></li>
</ul>
<p>And the principal intent flags you can use are:</p>
@@ -250,15 +252,18 @@ finishOnTaskLaunch}</a></li>
</ul>
<p>In the following sections, you'll see how you can use these manifest attributes and intent
flags to define how activities are associated with tasks and how the behave in the back stack.</p>
flags to define how activities are associated with tasks and how they behave in the back stack.</p>
<p>Also, discussed separately are the considerations for how tasks and activites may be represented
and managed in the overview screen. See <a href="{@docRoot}guide/components/recents.html">Overview Screen</a>
for more information. Normally you should allow the system to define how your task and
activities are represented in the overview screen, and you don't need to modify this behavior.</p>
<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 <em>Back</em> button.
Be sure
to test for navigation behaviors that might conflict with the user's expected behavior.</p>
Be sure to test for navigation behaviors that might conflict with the user's expected behavior.</p>
<h3 id="TaskLaunchModes">Defining launch modes</h3>
@@ -389,7 +394,7 @@ default behavior are:</p>
<dt>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</dt>
<dd>Start the activity in a new task. If a task is already running for the activity you are now
starting, that task is brought to the foreground with its last state restored and the activity
receives the new intent in {@link android.app.Activity#onNewIntent onNewIntent()}.
receives the new intent in {@link android.app.Activity#onNewIntent onNewIntent()}.
<p>This produces the same behavior as the {@code "singleTask"} <a
href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> value,
discussed in the previous section.</p></dd>
@@ -408,11 +413,13 @@ through {@link android.app.Activity#onNewIntent onNewIntent()}).
<p>There is no value for the <a
href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a>
attribute that produces this behavior.</p>
<p>{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction with {@code
FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are a way of locating an existing activity
<p>{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction with
{@code FLAG_ACTIVITY_NEW_TASK}.
When used together, these flags are a way of locating an existing activity
in another task and putting it in a position where it can respond to the intent. </p>
<p class="note"><strong>Note:</strong> If the launch mode of the designated activity is {@code
"standard"}, it too is removed from the stack and a new instance is launched in its place to handle
<p class="note"><strong>Note:</strong> If the launch mode of the designated activity is
{@code "standard"},
it too is removed from the stack and a new instance is launched in its place to handle
the incoming intent. That's because a new instance is always created for a new intent when the
launch mode is {@code "standard"}. </p>
</dd>
@@ -439,21 +446,23 @@ element.</p>
<p>The <a
href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a>
attribute takes a string value, which must be unique from the default package name
declared in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code
&lt;manifest&gt;}</a> element, because the system uses that name to identify the default task
declared in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">
{@code &lt;manifest&gt;}
</a> element, because the system uses that name to identify the default task
affinity for the application.</p>
<p>The affinity comes into play in two circumstances:</p>
<ul>
<li>When the intent that launches an activity contains the {@link
android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag.
<li>When the intent that launches an activity contains the
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}
flag.
<p>A new activity is, by default, launched into the task of the activity
that called {@link android.app.Activity#startActivity startActivity()}. It's pushed onto the same
back stack as the caller. However, if the intent passed to {@link
android.app.Activity#startActivity startActivity()} contains the {@link
android.content.Intent#FLAG_ACTIVITY_NEW_TASK}
flag, the system looks for a different task to house the new activity. Often, it's a new task.
back stack as the caller. However, if the intent passed to
{@link android.app.Activity#startActivity startActivity()}
contains the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}
flag, the system looks for a different task to house the new activity. Often, it's a new task.
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>
@@ -461,17 +470,17 @@ new activity, the activity is launched into that task. If not, it begins a new
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
android.app.Activity#startActivity startActivity()}. If you have an activity that can be invoked by
they always put {@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to
{@link android.app.Activity#startActivity startActivity()}.
If you have an activity that can be invoked by
an external entity that might use this flag, take care that the user has a independent way to get
back to the task that's started, such as with a launcher icon (the root activity of the task
has a {@link android.content.Intent#CATEGORY_LAUNCHER} intent filter; see the <a
href="#Starting">Starting a task</a> section below).</p>
</li>
<li>When an activity has its <a
href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">{@code
allowTaskReparenting}</a> attribute set to {@code "true"}.
<li>When an activity has its <a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">
{@code allowTaskReparenting}</a> attribute set to {@code "true"}.
<p>In this case, the activity can move from the task it starts to the task it has an affinity
for, when that task comes to the foreground.</p>
<p>For example, suppose that an activity that reports weather conditions in selected cities is
@@ -511,9 +520,9 @@ The task retains all activities in its stack even after a long period.</dd>
href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code></dt>
<dd>If this attribute is set to {@code "true"} in the root activity of a task,
the stack is cleared down to the root activity whenever the user leaves the task
and returns to it. In other words, it's the opposite of <a
href="{@docRoot}guide/topics/manifest/activity-element.html#always">{@code
alwaysRetainTaskState}</a>. The user always returns to the task in its
and returns to it. In other words, it's the opposite of
<a href="{@docRoot}guide/topics/manifest/activity-element.html#always">
{@code alwaysRetainTaskState}</a>. The user always returns to the task in its
initial state, even after a leaving the task for only a moment.</dd>
<dt><code><a
@@ -534,8 +543,9 @@ leaves and then returns to the task, it is no longer present.</dd>
<h3 id="Starting">Starting a task</h3>
<p>You can set up an activity as the entry point for a task by giving it an intent filter with
{@code "android.intent.action.MAIN"} as the specified action and {@code
"android.intent.category.LAUNCHER"} as the specified category. For example:</p>
{@code "android.intent.action.MAIN"} as the specified action and
{@code "android.intent.category.LAUNCHER"}
as the specified category. For example:</p>
<pre>
&lt;activity ... &gt;
@@ -553,27 +563,25 @@ to return to the task that it creates any time after it has been launched.
</p>
<p>This second ability is important: Users must be able to leave a task and then come back to it
later using this activity launcher. For this reason, the two <a href="#LaunchModes">launch
modes</a> that mark activities as always initiating a task, {@code "singleTask"} and "{@code
"singleInstance"}, should be used only when the activity has an {@link
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 <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>
later using this activity launcher. For this reason, the two <a href="#LaunchModes">launch
modes</a> that mark activities as always initiating a task, {@code "singleTask"} and
{@code "singleInstance"}, should be used only when the activity has an
{@link 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 <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
<code><a
href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> element's
<a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code
finishOnTaskLaunch}</a> to {@code "true"} (see <a
href="#Clearing">Clearing the stack</a>).</p>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element's
<a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code finishOnTaskLaunch}</a>
to {@code "true"} (see <a href="#Clearing">Clearing the stack</a>).</p>
<p>Further information about how tasks and activites are represented and managed in
the overview screen is available in <a href="{@docRoot}guide/components/recents.html">
Overview Screen</a>.</p>
<!--
<h2>Beginner's Path</h2>

3
docs/html/guide/guide_toc.cs
View File

@@ -55,6 +55,9 @@
<li><a href="<?cs var:toroot ?>guide/components/tasks-and-back-stack.html">
<span class="en">Tasks and Back Stack</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/components/recents.html">
<span class="en">Overview Screen</span>
</a></li>
</ul>
</li>
<li class="nav-section">

101
docs/html/guide/topics/manifest/activity-element.jd
View File

@@ -8,11 +8,14 @@ parent.link=manifest-intro.html
<dd><pre class="stx">&lt;activity android:<a href="#embedded">allowEmbedded</a>=["true" | "false"]
android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"]
android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"]
android:<a href="#autoremrecents">autoRemoveFromRecents</a>=["true" | "false"]
android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"]
android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale",
"touchscreen", "keyboard", "keyboardHidden",
"navigation", "screenLayout", "fontScale", "uiMode",
"orientation", "screenSize", "smallestScreenSize"]
android:<a href="#dlmode">documentLaunchMode</a>=["intoExisting", "always",
"none", "never"]
android:<a href="#enabled">enabled</a>=["true" | "false"]
android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"]
android:<a href="#exported">exported</a>=["true" | "false"]
@@ -22,12 +25,14 @@ parent.link=manifest-intro.html
android:<a href="#label">label</a>="<i>string resource</i>"
android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" |
"singleTask" | "singleInstance"]
android:<a href="#maxRecents">maxRecents</a>="<i>integer</i>"
android:<a href="#multi">multiprocess</a>=["true" | "false"]
android:<a href="#nm">name</a>="<i>string</i>"
android:<a href="#nohist">noHistory</a>=["true" | "false"] <!-- ##api level 3## -->
android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 -->
android:<a href="#prmsn">permission</a>="<i>string</i>"
android:<a href="#proc">process</a>="<i>string</i>"
android:<a href="#relinquish">relinquishTaskIdentity</a>=["true" | "false"]
android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" |
"landscape" | "portrait" |
"reverseLandscape" | "reversePortrait" |
@@ -139,6 +144,15 @@ useful, for example, in an application like the web browser where there is
a lot of state (such as multiple open tabs) that users would not like to lose.
</p></dd>
<dt><a name="autoremrecents"></a>{@code android:autoRemoveFromRecents}</dt>
<dd>Whether or not tasks launched by activities with this attribute remains in the
<a href="{@docRoot}guide/components/recents.html">overview screen</a> until the last activity in the
task is completed. If {@code true}, the task is
automatically removed from the overview screen. This overrides the caller's use of
{@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS}. It must be a boolean value, either
"{@code true}" or "{@code false}".</dd>
<dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt>
<dd>Whether or not all activities will be removed from the task, except for
the root activity, whenever it is re-launched from the home screen &mdash;
@@ -177,7 +191,7 @@ as described above.
<dd>Lists configuration changes that the activity will handle itself. When a configuration
change occurs at runtime, the activity is shut down and restarted by default, but declaring a
configuration with this attribute will prevent the activity from being restarted. Instead, the
activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged
activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged(android.content.res.Configuration)
onConfigurationChanged()}</code> method is called.
<p class="note"><strong>Note:</strong> Using this attribute should be
@@ -271,20 +285,67 @@ restart your activity, even when running on an Android 3.2 or higher device).
<p>
All of these configuration changes can impact the resource values seen by the
application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged
application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged(android.content.res.Configuration)
onConfigurationChanged()}</code> is called, it will generally be necessary to again
retrieve all resources (including view layouts, drawables, and so on) to correctly
handle the change.
</p></dd>
<dt><a name="dlmode"></a>{@code android:documentLaunchMode}</dt>
<dd>Specifies how a new instance of an activity should be added to a task each time it is
launched. This attribute permits the user to have multiple documents from the same application
appear in the <a href="{@docRoot}guide/components/recents.html">overview screen</a>.
<p>This attribute has four values which produce the following effects when the user opens a document
with the application:</p>
<table>
<tr>
<th>Value</th>
<th>Description</th>
</tr><tr>
<td>"{@code intoExisting}"</td>
<td>The activity reuses the existing task for the document. Using this value is the same as setting
the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag, <em>without</em> setting the
{@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag, as described in
<a href="{@docRoot}guide/components/recents.html#flag-new-doc">Using the Intent flag to add a task
</a>.</td>
</tr><tr>
<td>"{@code always}"</td>
<td>The activity creates a new task for the document, even if the document is already opened.
This is the same as setting both the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}
and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags.</td>
</tr><tr>
<td>"{@code none}"</td>
<td>The activity does not create a new task for the activity. This is the default value, which
creates a new task only when {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} is set.
The overview screen treats the activity as it would by default: it displays a single task for
the app, which resumes from whatever activity the user last invoked.</td>
</tr><tr>
<td>"{@code never}"</td>
<td>This activity is not launched into a new document even if the Intent contains
{@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}. Setting this overrides the behavior
of the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} and
{@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags, if either of these are set in
the activity, and the overview screen displays a single task for the app, which resumes from
whatever activity the user last invoked.</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> For values other than "{@code none}" and "{@code never}" the
activity must be defined with {@code launchMode="standard"}. If this attribute is not specified,
{@code documentLaunchMode="none"} is used.</p>
</dd>
<dt><a name="enabled"></a>{@code android:enabled}</dt>
<dd>Whether or not the activity can be instantiated by the system &mdash;
"{@code true}" if it can be, and "{@code false}" if not. The default value
{@code "true"} if it can be, and "{@code false}" if not. The default value
is "{@code true}".
<p>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code> element has its own
<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code>
The <code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a>
</code> element has its own<code>
<a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code>
attribute that applies to all application components, including activities. The
<code><a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
and {@code &lt;activity&gt;} attributes must both be "{@code true}" (as they both
@@ -294,10 +355,11 @@ is "{@code false}", it cannot be instantiated.
<dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt>
<dd>Whether or not the task initiated by this activity should be excluded from the list of recently
used applications ("recent apps"). That is, when this activity is the root activity of a new task,
this attribute determines whether the task should not appear in the list of recent apps. Set "{@code
true}" if the task should be <em>excluded</em> from the list; set "{@code false}" if it should be
<em>included</em>. The default value is "{@code false}".
used applications, the <a href="{@docRoot}guide/components/recents.html">
overview screen</a>. That is, when this activity is the root activity of a new
task, this attribute determines whether the task should not appear in the list of recent apps. Set
"{@code true}" if the task should be <em>excluded</em> from the list; set "{@code false}" if it
should be <em>included</em>. The default value is "{@code false}".
</p></dd>
<dt><a name="exported"></a>{@code android:exported}</dt>
@@ -550,6 +612,13 @@ document.
</p>
</dd>
<dt><a name="maxrecents"></a>{@code android:maxRecents}</dt>
<dd>The maximum number of tasks rooted at this activity in the <a href="{@docRoot}guide/components/recents.html">
overview screen</a>. When this number of entries is reached, the system removes the least-recently
used instance from the overview screen. Valid values are 1 through 50 (25 on low memory devices);
zero is invalid. This must be an integer value, such as 50. The default value is 16.
</dd>
<dt><a name="multi"></a>{@code android:multiprocess}</dt>
<dd>Whether an instance of the activity can be launched into the process of the component
that started it &mdash; "{@code true}" if it can be, and "{@code false}" if not.
@@ -685,6 +754,20 @@ resource usage.
attribute can set a different default process name for all components.
</dd>
<dt><a name="relinquish"></a>{@code android:relinquishTaskIdentity}</dt>
<dd>Whether or not the activity relinquishes its task identifiers to an activity above it in the
task stack. A task whose root activity has this attribute set to "{@code true}" replaces the base
Intent with that of the next activity in the task. If the next activity also has this attribute set
to "{@code true}" then it will yield the base Intent to any activity that it launches in the same
task. This continues for each activity until an activity is encountered which has this attribute set
to "{@code false}". The default value is "{@code false}".
<p>This attribute set to "{@code true}" also permits the activity's use of the
{@link android.app.ActivityManager.TaskDescription} to change labels, colors
and icons in the <a href="{@docRoot}guide/components/recents.html">overview screen</a>.</p>
</dd>
<dt><a name="screen"></a>{@code android:screenOrientation}</dt>
<dd>The orientation of the activity's display on the device.

BIN
docs/html/images/components/recents.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 939 KiB