What is the difference between android:launchMode and android:documentLaunchMode attribute?

Question

So I have been reading the docs on Tasks, Back Stack and Overview Screen and there is one thing that immensely confuses me. After having read launchMode here: http://developer.android.com/guide/components/tasks-and-back-stack.html then about documentLaunchMode here: http://developer.android.com/guide/components/recents.html I can't tell how they differ!

Both have been depicted to provide ways to control launch of new Activity in tasks relative to current task(The task of launching activity). So how these 2 modes are different? What does the appending of -document imply?

Here are the docs which directly refers to their use in the manifest file:
LaunchMode: http://developer.android.com/guide/topics/manifest/activity-element.html#lmode
DocumentLaunchMode: http://developer.android.com/guide/topics/manifest/activity-element.html#dlmode

Answer 1

DocumentLaunchMode:

• More associated with recent tasks screen
• Allows multiple documents of the same activity to appear in recent/overview screen

• Possible Values:

  1. "intoExisting" - The activity reuses the existing task for the document (The one that creates it). Using this value is the same as setting the FLAG_ACTIVITY_NEW_DOCUMENT flag, without setting the FLAG_ACTIVITY_MULTIPLE_TASK flag.
  2. "always" - The activity creates a new task for the document, even if the document is already opened. This is the same as setting both the FLAG_ACTIVITY_NEW_DOCUMENT and FLAG_ACTIVITY_MULTIPLE_TASK flags.
  3. "none" - (Default) - The activity does not create a new task for the activity. This creates a new task only when 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.
  4. "never" - This activity is not launched into a new document even if the Intent contains FLAG_ACTIVITY_NEW_DOCUMENT. Setting this overrides the behavior of the FLAG_ACTIVITY_NEW_DOCUMENT and 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.

launchMode:

• More associated with back stack
• Deals with how activities should be launched (created and associated with task)

• Possible Values:

  1. "standard" - (Default) - The system always creates a new instance of the activity in the target task and routes the intent to it.
  2. "singleTop" - If an instance of the activity already exists at the top of the target task, the system routes the intent to that instance through a call to its onNewIntent() method, rather than creating a new instance of the activity.
  3. "singleTask" - The system creates the activity at the root of a new task and routes the intent to it. However, if an instance of the activity already exists, the system routes the intent to existing instance through a call to its onNewIntent() method, rather than creating a new one.
  4. "singleInstance" - Same as "singleTask", except that the system doesn't launch any other activities into the task holding the instance. The activity is always the single and only member of its task.

Logical Relationship: For values other than "none" and "never" (documentLaunchMode) the activity must be defined with launchMode="standard". If this attribute is not specified, documentLaunchMode="none" is used.

Answer 2

Let's take a quick look at the launchMode values:

standard and singleTop both allow multiple instances of an activity to be created, within other tasks.

singleTask and singleInstance both limit an activity to a single instance, as the first activity in its task.

Anything seem to be missing to you? None of these values allow multiple instances of an activity to be created at the top level. Either you launch instances of your activity into other people's tasks, or you limit it to a single instance. None of these values allow multiple tasks to be created to host your activity. This oversight is what documentLaunchMode addresses. The idea is that if your activity has an intent filter that allows it to view documents, that each of those documents -- each data uri -- should be able to get its own instance of your activity in its own task.