1page.title=Overview Screen 2page.tags="recents","overview" 3 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#adding">Adding Tasks to the Overview Screen</a> 12 <ol> 13 <li><a href="#flag-new-doc">Using the Intent flag to add a task</a></li> 14 <li><a href="#attr-doclaunch">Using the Activity attribute to add a task</a></li> 15 </ol> 16 </li> 17 <li><a href="#removing">Removing Tasks</a> 18 <ol> 19 <li><a href="#apptask-remove">Using the AppTask class to remove tasks</a></li> 20 <li><a href="#retain-finished">Retaining finished tasks</a></li> 21 </ol> 22 </li> 23 </ol> 24 25 <h2>Key classes</h2> 26 <ol> 27 <li>{@link android.app.ActivityManager.AppTask}</li> 28 <li>{@link android.content.Intent}</li> 29 </ol> 30 31 <h2>Sample code</h2> 32 <ol> 33 <li><a href="{@docRoot}samples/DocumentCentricApps/index.html">Document-centric Apps</a></li> 34 </ol> 35 36</div> 37</div> 38 39<p>The overview screen (also referred to as the recents screen, recent task list, or recent apps) 40is a system-level UI that lists recently accessed <a href="{@docRoot}guide/components/activities.html"> 41activities</a> and <a href="{@docRoot}guide/components/tasks-and-back-stack.html">tasks</a>. The 42user can navigate through the list and select a task to resume, or the user can remove a task from 43the list by swiping it away. With the Android 5.0 release (API level 21), multiple instances of the 44same activity containing different documents may appear as tasks in the overview screen. For example, 45Google Drive may have a task for each of several Google documents. Each document appears as a 46task in the overview screen.</p> 47 48<img src="{@docRoot}images/components/recents.png" alt="" width="284" /> 49<p class="img-caption"><strong>Figure 1.</strong> The overview screen showing three Google Drive 50documents, each represented as a separate task.</p> 51 52<p>Normally you should allow the system to define how your tasks and 53activities are represented in the overview screen, and you don't need to modify this behavior. 54However, your app can determine how and and when activities appear in the overview screen. The 55{@link android.app.ActivityManager.AppTask} class lets you manage tasks, and the activity flags of 56the {@link android.content.Intent} class let you specify when an activity is added or removed from 57the overview screen. Also, the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"> 58<activity></a></code> attributes let you set the behavior in the manifest.</p> 59 60<h2 id="adding">Adding Tasks to the Overview Screen</h2> 61 62<p>Using the flags of the {@link android.content.Intent} class to add a task affords greater control 63over when and how a document gets opened or reopened in the overview screen. When you use the 64<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 65attributes you can choose between always opening the document in a new task or reusing an 66existing task for the document.</p> 67 68<h3 id="flag-new-doc">Using the Intent flag to add a task</h3> 69 70<p>When you create a new document for your activity, you call the 71{@link android.app.ActivityManager.AppTask#startActivity(android.content.Context, android.content.Intent, android.os.Bundle) startActivity()} 72method of the {@link android.app.ActivityManager.AppTask} class, passing to it the intent that 73launches the activity. To insert a logical break so that the system treats your activity as a new 74task in the overview screen, pass the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag 75in the {@link android.content.Intent#addFlags(int) addFlags()} method of the {@link android.content.Intent} 76that launches the activity.</p> 77 78<p class="note"><strong>Note:</strong> The {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} 79flag replaces the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET} flag, 80which is deprecated as of Android 5.0 (API level 21).</p> 81 82<p>If you set the {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag when you create 83the new document, the system always creates a new task with the target activity as the root. 84This setting allows the same document to be opened in more than one task. The following code demonstrates 85how the main activity does this:</p> 86 87<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> 88DocumentCentricActivity.java</a></p> 89<pre> 90public void createNewDocument(View view) { 91 final Intent newDocumentIntent = newDocumentIntent(); 92 if (useMultipleTasks) { 93 newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_MULTIPLE_TASK); 94 } 95 startActivity(newDocumentIntent); 96 } 97 98 private Intent newDocumentIntent() { 99 boolean useMultipleTasks = mCheckbox.isChecked(); 100 final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class); 101 newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT); 102 newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet()); 103 return newDocumentIntent; 104 } 105 106 private static int incrementAndGet() { 107 Log.d(TAG, "incrementAndGet(): " + mDocumentCounter); 108 return mDocumentCounter++; 109 } 110} 111</pre> 112 113<p class="note"><strong>Note:</strong> Activities launched with the {@code FLAG_ACTIVITY_NEW_DOCUMENT} 114flag must have the {@code android:launchMode="standard"} attribute value (the default) set in the 115manifest.</p> 116 117<p>When the main activity launches a new activity, the system searches through existing tasks for 118one whose intent matches the intent component name and the Intent data for the activity. If the task 119is not found, or the intent contained the {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} 120flag, a new task will be created with the activity as its root. If it finds one, it brings that task 121to the front and passes the new intent to {@link android.app.Activity#onNewIntent onNewIntent()}. 122The new activity gets the intent and creates a new document in the overview screen, as in the 123following example:</p> 124 125<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> 126NewDocumentActivity.java</a></p> 127<pre> 128@Override 129protected void onCreate(Bundle savedInstanceState) { 130 super.onCreate(savedInstanceState); 131 setContentView(R.layout.activity_new_document); 132 mDocumentCount = getIntent() 133 .getIntExtra(DocumentCentricActivity.KEY_EXTRA_NEW_DOCUMENT_COUNTER, 0); 134 mDocumentCounterTextView = (TextView) findViewById( 135 R.id.hello_new_document_text_view); 136 setDocumentCounterText(R.string.hello_new_document_counter); 137} 138 139@Override 140protected void onNewIntent(Intent intent) { 141 super.onNewIntent(intent); 142 /* If FLAG_ACTIVITY_MULTIPLE_TASK has not been used, this activity 143 is reused to create a new document. 144 */ 145 setDocumentCounterText(R.string.reusing_document_counter); 146} 147</pre> 148 149 150<h3 id="#attr-doclaunch">Using the activity attribute to add a task</h3> 151 152<p>An activity can also specify in its manifest that it always launches into a new task by using 153the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 154attribute, <a href="{@docRoot}guide/topics/manifest/activity-element.html#dlmode"> 155{@code android:documentLaunchMode}</a>. This attribute has four values which produce the following 156effects when the user opens a document with the application:</p> 157 158<dl> 159 <dt>"{@code intoExisting}"</dt> 160 <dd>The activity reuses an existing task for the document. This is the same as setting the 161 {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} flag <em>without</em> setting the 162 {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flag, as described in 163 <a href="#flag-new-doc">Using the Intent flag to add a task</a>, above.</dd> 164 165 <dt>"{@code always}"</dt> 166 <dd>The activity creates a new task for the document, even if the document is already opened. Using 167 this value is the same as setting both the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} 168 and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags.</dd> 169 170 <dt>"{@code none”}"</dt> 171 <dd>The activity does not create a new task for the document. The overview screen treats the 172 activity as it would by default: it displays a single task for the app, which 173 resumes from whatever activity the user last invoked.</dd> 174 175 <dt>"{@code never}"</dt> 176 <dd>The activity does not create a new task for the document. Setting this value overrides the 177 behavior of the {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} 178 and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} flags, if either of these are set 179 in the intent, and the overview screen displays a single task for the app, which resumes from 180 whatever activity the user last invoked.</dd> 181</dl> 182 183<p class="note"><strong>Note:</strong> For values other than {@code none} and {@code never} the 184activity must be defined with {@code launchMode="standard"}. If this attribute is not specified, 185{@code documentLaunchMode="none"} is used.</p> 186 187<h2 id="removing">Removing Tasks</h2> 188 189<p>By default a document task is automatically removed from the overview screen when its activity 190finishes. You can override this behavior with the {@link android.app.ActivityManager.AppTask} class, 191with an {@link android.content.Intent} flag, or with an<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"> 192<activity></a></code> attribute.</p> 193 194<p>You can always exclude a task from the overview screen entirely by setting the 195<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 196attribute, <a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude"> 197{@code android:excludeFromRecents}</a> to {@code true}.</p> 198 199<p>You can set the maximum number of tasks that your app can include in the overview screen by setting 200the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 201attribute <a href="{@docRoot}guide/topics/manifest/activity-element.html#maxrecents">{@code android:maxRecents} 202</a> to an integer value. The default is 16. When the maximum number of tasks is reached, the least 203recently used task is removed from the overview screen. The {@code android:maxRecents} maximum value 204is 50 (25 on low memory devices); values less than 1 are not valid.</p> 205 206<h3 id="#apptask-remove">Using the AppTask class to remove tasks</h3> 207 208<p>In the activity that creates a new task in the overview screen, you can 209specify when to remove the task and finish all activities associated with it by calling 210the {@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()} method.</p> 211 212<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> 213NewDocumentActivity.java</a></p> 214<pre> 215public void onRemoveFromRecents(View view) { 216 // The document is no longer needed; remove its task. 217 finishAndRemoveTask(); 218} 219</pre> 220 221<p class="note"><strong>Note:</strong> Using the 222{@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()} method 223overrides the use of the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} tag, 224discussed below.</p> 225 226<h3 id="#retain-finished">Retaining finished tasks</h3> 227 228<p>If you want to retain a task in the overview screen, even if its activity has finished, pass 229the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} flag in the 230{@link android.content.Intent#addFlags(int) addFlags()} method of the Intent that launches the activity.</p> 231 232<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> 233DocumentCentricActivity.java</a></p> 234<pre> 235private Intent newDocumentIntent() { 236 final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class); 237 newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT | 238 android.content.Intent.FLAG_ACTIVITY_RETAIN_IN_RECENTS); 239 newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet()); 240 return newDocumentIntent; 241} 242</pre> 243 244<p>To achieve the same effect, set the 245<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 246attribute <a href="{@docRoot}guide/topics/manifest/activity-element.html#autoremrecents"> 247{@code android:autoRemoveFromRecents}</a> to {@code false}. The default value is {@code true} 248for document activities, and {@code false} for regular activities. Using this attribute overrides 249the {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} flag, discussed previously.</p> 250 251 252 253 254 255 256 257