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

Merge "Improve DocCentric documentation."

Browse Source
This commit is contained in:
Craig Mautner
2014-05-24 00:46:51 +00:00
committed by Android (Google) Code Review
parent b861179fca 2d74ce309f
commit dbcd3aa22a
2 changed files with 53 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
core/java/android/content/Intent.java
View File

@@ -3739,32 +3739,27 @@ public class Intent implements Parcelable, Cloneable {
*/
public static final int FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET = 0x00080000;
/**
* This flag is used to break out "documents" into separate tasks that can
* be reached via the Recents mechanism. Such a document is any kind of
* item for which an application may want to maintain multiple simultaneous
* instances. Examples might be text files, web pages, spreadsheets, or
* emails. Each such document will be in a separate task in the Recents list.
* This flag is used to open a document into a new task rooted at the activity launched
* by this Intent. Through the use of this flag, or its equivalent attribute,
* {@link android.R.attr#documentLaunchMode} multiple instances of the same activity
* containing different douments will appear in the recent tasks list.
*
* <p>When set, the activity specified by this Intent will launch into a
* separate task rooted at that activity. The activity launched must be
* defined with {@link android.R.attr#launchMode} <code>standard</code>
* or <code>singleTop</code>.
* <p>The use of the activity attribute form of this,
* {@link android.R.attr#documentLaunchMode}, is
* preferred over the Intent flag described here. The attribute form allows the
* Activity to specify multiple document behavior for all launchers of the Activity
* whereas using this flag requires each Intent that launches the Activity to specify it.
*
* <p>If FLAG_ACTIVITY_NEW_DOCUMENT is used without
* {@link #FLAG_ACTIVITY_MULTIPLE_TASK} then the activity manager will
* search for an existing task with a matching target activity and Intent
* data URI and relaunch that task, first finishing all activities down to
* the root activity and then calling the root activity's
* {@link android.app.Activity#onNewIntent(Intent)} method. If no existing
* task's root activity matches the Intent's data URI then a new task will
* be launched with the target activity as root.
* <p>FLAG_ACTIVITY_NEW_DOCUMENT may be used in conjunction with {@link
* #FLAG_ACTIVITY_MULTIPLE_TASK}. When used alone it is the
* equivalent of the Activity manifest specifying {@link
* android.R.attr#documentLaunchMode}="intoExisting". When used with
* FLAG_ACTIVITY_MULTIPLE_TASK it is the equivalent of the Activity manifest specifying
* {@link android.R.attr#documentLaunchMode}="always".
*
* <p>When paired with {@link #FLAG_ACTIVITY_MULTIPLE_TASK} this will
* always create a new task. Thus the same document may be made to appear
* more than one time in Recents.
*
* <p>This is equivalent to the attribute {@link android.R.attr#documentLaunchMode}.
* Refer to {@link android.R.attr#documentLaunchMode} for more information.
*
* @see android.R.attr#documentLaunchMode
* @see #FLAG_ACTIVITY_MULTIPLE_TASK
*/
public static final int FLAG_ACTIVITY_NEW_DOCUMENT =

56
core/res/res/values/attrs_manifest.xml
View File

@@ -885,41 +885,57 @@
be passed a persistable Bundle in their Intent.extras. -->
<attr name="persistable" format="boolean" />
<!-- Specify whether this activity should always be launched in doc-centric mode. For
values other than <code>none</code> the activity must be defined with
{@link android.R.attr#launchMode} <code>standard</code> or <code>singleTop</code>.
This attribute can be overridden by {@link
android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}.
<!-- This attribute specifies that an activity shall become the root activity of a
new task each time it is launched. Using this attribute permits the user to
have multiple documents from the same applications appear in the recent tasks list.
<p>If this attribute is not specified, <code>none</code> will be used.
Note that this launch behavior can be changed in some ways at runtime
through the {@link android.content.Intent} flags
{@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}. -->
<p>Such a document is any kind of item for which an application may want to
maintain multiple simultaneous instances. Examples might be text files, web
pages, spreadsheets, or emails. Each such document will be in a separate
task in the recent taskss list.
<p>This attribute is equivalent to adding the flag {@link
android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} to every Intent used to launch
the activity.
<p>The documentLaunchMode attribute may be assigned one of three values, "none",
"intoExisting" and "always", described in detail below. For values other than
<code>none</code> the activity must be defined with
{@link android.R.attr#launchMode} <code>standard</code> or <code>singleTop</code>.
If this attribute is not specified, <code>none</code> will be used.
Note that <code>none</code> can be overridden at run time if the Intent used
to launch it contains the flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}.
Similarly <code>intoExisting</code> will be overridden by the flag
{@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} combined with
{@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}. -->
<attr name="documentLaunchMode">
<!-- The default mode, which will create a new task only when
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK
Intent.FLAG_ACTIVITY_NEW_TASK} is set. -->
<enum name="none" value="0" />
<!-- All tasks will be searched for a matching Intent. If one is found
That task will cleared and restarted with the root activity receiving a call
<!-- All tasks will be searched for one whose base Intent's ComponentName and
data URI match those of the launching Intent. If such a task is found
that task will be cleared and restarted with the root activity receiving a call
to {@link android.app.Activity#onNewIntent Activity.onNewIntent}. If no
such task is found a new task will be created.
This is the equivalent of with {@link
<p>This is the equivalent of launching an activity with {@link
android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT Intent.FLAG_ACTIVITY_NEW_DOCUMENT}
without {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK
Intent.FLAG_ACTIVITY_MULTIPLE_TASK}. -->
set and without {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK
Intent.FLAG_ACTIVITY_MULTIPLE_TASK} set. -->
<enum name="intoExisting" value="1" />
<!-- A new task rooted at this activity will be created.
This is the equivalent of with {@link
<!-- A new task rooted at this activity will be created. This will happen whether or
not there is an existing task whose ComponentName and data URI match
that of the launcing intent This is the equivalent of launching an activity
with {@link
android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT Intent.FLAG_ACTIVITY_NEW_DOCUMENT}
paired with {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK
Intent.FLAG_ACTIVITY_MULTIPLE_TASK}. -->
and {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK
Intent.FLAG_ACTIVITY_MULTIPLE_TASK} both set. -->
<enum name="always" value="2" />
</attr>
<!-- Tasks launched by activities with this attribute will remain in the recent task
<!-- Tasks launched by activities with this attribute will remain in the recent tasks
list until the last activity in the task is completed. When that happens the task
will be automatically removed from the recent task list.
will be automatically removed from the recent tasks list.
This attribute is the equivalent of {@link
android.content.Intent#FLAG_ACTIVITY_AUTO_REMOVE_FROM_RECENTS