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 activities and tasks. 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.
Figure 1. The overview screen showing three Google Drive documents, each represented as a separate task.
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
<activity> attributes let you set the behavior in the manifest.
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
<activity>
attributes you can choose between always opening the document in a new task or reusing an
existing task for the document.
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.
Note: 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).
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:
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++;
}
}
Note: 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.
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:
@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);
}
@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);
}
An activity can also specify in its manifest that it always launches into a new task by using
the <activity>
attribute,
{@code android:documentLaunchMode}. This attribute has four values which produce the following
effects when the user opens a document with the application:
Note: 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.
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
<activity> attribute.
You can always exclude a task from the overview screen entirely by setting the
<activity>
attribute,
{@code android:excludeFromRecents} to {@code true}.
You can set the maximum number of tasks that your app can include in the overview screen by setting
the <activity>
attribute {@code android:maxRecents}
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.
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.
public void onRemoveFromRecents(View view) {
// The document is no longer needed; remove its task.
finishAndRemoveTask();
}
Note: 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.
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.
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;
}
To achieve the same effect, set the
<activity>
attribute
{@code android:autoRemoveFromRecents} 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.