From 1ba62882e4594ebb3cc4c7a1caa07b55c6caeca6 Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Mon, 23 Aug 2010 12:11:14 -0700 Subject: Doc change: Add table to clarify launch modes and caution against using SingleTask and SingleInstance modes. Change-Id: I9e04c54ed3e4d10afddedd6e6e35761e67652cd8 --- docs/html/guide/topics/fundamentals.jd | 6 +- .../html/guide/topics/manifest/activity-element.jd | 122 +++++++++++++++------ 2 files changed, 91 insertions(+), 37 deletions(-) diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index f780e7c6bfce..6d6abd8b15c9 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -770,9 +770,9 @@ return to what that instance was doing before the new intent arrived.

-For more on launch modes, see the description of the -<activity> -element. +For more on launch modes, see the description of the <activity> +element.

diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index de8ca6d8950b..e030a4c48e5e 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -336,10 +336,10 @@ it can also be set as a raw string.

{@code android:launchMode}
-
An instruction on how the activity should be launched. There are four modes +
An instruction on how the activity should be launched. There are four modes that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) -in {@link android.content.Intent} objects to determine what should happen when -the activity is called upon to handle an intent. They are: +in {@link android.content.Intent} objects to determine what should happen when +the activity is called upon to handle an intent. They are:

"{@code standard}"
"{@code singleTop}" @@ -351,56 +351,110 @@ The default mode is "{@code standard}".

-The modes fall into two main groups, with "{@code standard}" and -"{@code singleTop}" activities on one side, and "{@code singleTask}" and -"{@code singleInstance}" activities on the other. An activity with the -"{@code standard}" or "{@code singleTop}" launch mode can be instantiated -multiple times. The instances can belong to any task and can be located -anywhere in the activity stack. Typically, they're launched into the task -that called +As shown in the table below, the modes fall into two main groups, with +"{@code standard}" and "{@code singleTop}" activities on one side, and +"{@code singleTask}" and "{@code singleInstance}" activities on the other. +An activity with the "{@code standard}" or "{@code singleTop}" launch mode +can be instantiated multiple times. The instances can belong to any task +and can be located anywhere in the activity stack. Typically, they're +launched into the task that called {@link android.content.Context#startActivity startActivity()} -(unless the Intent object contains a -{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} -instruction, in which case a different task is chosen — see the +(unless the Intent object contains a +{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} +instruction, in which case a different task is chosen — see the taskAffinity attribute).

-In contrast, "{@code singleTask}" and "{@code singleInstance}" activities -can only begin a task. They are always at the root of the activity stack. -Moreover, the device can hold only one instance of the activity at a time +In contrast, "singleTask" and "singleInstance" activities +can only begin a task. They are always at the root of the activity stack. +Moreover, the device can hold only one instance of the activity at a time — only one such task.

The "{@code standard}" and "{@code singleTop}" modes differ from each other -in just one respect: Every time there's new intent for a "{@code standard}" -activity, a new instance of the class is created to respond to that intent. +in just one respect: Every time there's a new intent for a "{@code standard}" +activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. -Similarly, a new instance of a "{@code singleTop}" activity may also be -created to handle a new intent. However, if the target task already has an -existing instance of the activity at the top of its stack, that instance -will receive the new intent (in an +Similarly, a new instance of a "{@code singleTop}" activity may also be +created to handle a new intent. However, if the target task already has an +existing instance of the activity at the top of its stack, that instance +will receive the new intent (in an {@link android.app.Activity#onNewIntent onNewIntent()} call); a new instance is not created. -In other circumstances — for example, if an existing instance of the -"{@code singleTop}" activity is in the target task, but not at the top of -the stack, or if it's at the top of a stack, but not in the target task +In other circumstances — for example, if an existing instance of the +"{@code singleTop}" activity is in the target task, but not at the top of +the stack, or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack. -

+

-The "{@code singleTask}" and "{@code singleInstance}" modes also differ from -each other in only one respect: A "{@code singleTask}" activity allows other -activities to be part of its task. It's at the root of the activity stack, -but other activities (necessarily "{@code standard}" and "{@code singleTop}" -activities) can be launched into the same task. A "{@code singleInstance}" -activity, on the other hand, permits no other activities to be part of its -task. It's the only activity in the task. If it starts another activity, -that activity is assigned to a different task — as if {@code +The "{@code singleTask}" and "{@code singleInstance}" modes also differ from +each other in only one respect: A "{@code singleTask}" activity allows other +activities to be part of its task. It's always at the root of its task, but +other activities (necessarily "{@code standard}" and "{@code singleTop}" +activities) can be launched into that task. A "{@code singleInstance}" +activity, on the other hand, permits no other activities to be part of its task. +It's the only activity in the task. If it starts another activity, that +activity is assigned to a different task — as if {@code FLAG_ACTIVITY_NEW_TASK} was in the intent.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Use CasesLaunch ModeMultiple Instances?Comments
Normal launches for most activities"standard"YesDefault. The system always creates a new instance of the activity in the +target task and routes the intent to it.
"singleTop"ConditionallyIf 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 {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a +new instance of the activity.
Specialized launches
+(not recommended for general use)		"singleTask"NoThe 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 {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a +new one.
"singleInstance"NoSame 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.
+ +

As shown in the table above, standard is the default mode and is +appropriate for most types of activities. SingleTop is also a +common and useful launch mode for many types of activities. The other modes +— singleTask and singleInstance — are +not appropriate for most applications, +since they result in an interaction model that is likely to be unfamiliar to +users and is very different from most other applications. + +

Regardless of the launch mode that you choose, make sure to test the usability +of the activity during launch and when navigating back to it from +other activities and tasks using the BACK key.

+

For more information on launch modes and their interaction with Intent flags, see the Activities and -- cgit v1.2.3-59-g8ed1b