Improve DocCentric documentation. DO NOT MERGE (026596b9) · Commits · e / os / android_frameworks_base

core/java/android/content/Intent.java

+21 −26

Original line number	Diff line number	Diff line
		@@ -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.
		*
		* <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>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>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}.
		*
		* 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>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>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".
		*
		* 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 =

core/res/res/values/attrs_manifest.xml

+36 −20

Original line number	Diff line number	Diff line
		@@ -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
		<!-- 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>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>.
		This attribute can be overridden by {@link
		android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT}.

		<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}. -->
		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