Enum LaunchMode

pub enum LaunchMode {
    Standard,
    SingleTop,
    SingleTask,
    SingleInstance,
}

An instruction on how the activity should be launched.

As shown in the enum variant description, the modes fall into two main groups, with "standard" and "singleTop"activities on one side, and “singleTask” and “singleInstance” activities on the other. An activity with the "standard" or “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 startActivity() (unless the Intent object contains a FLAG_ACTIVITY_NEW_TASK instruction, in which case a different task is chosen — see the taskAffinity attribute).

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 "standard" and "singleTop" modes differ from each other in just one respect: Every time there’s a new intent for a "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 "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 onNewIntent() call); a new instance is not created. In other circumstances — for example, if an existing instance of the "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.

Similarly, if you navigate up to an activity on the current stack, the behavior is determined by the parent activity’s launch mode. If the parent activity has launch mode singleTop (or the up intent contains FLAG_ACTIVITY_CLEAR_TOP), the parent is brought to the top of the stack, and its state is preserved. The navigation intent is received by the parent activity’s onNewIntent() method. If the parent activity has launch mode standard (and the up intent does not contain FLAG_ACTIVITY_CLEAR_TOP), the current activity and its parent are both popped off the stack, and a new instance of the parent activity is created to receive the navigation intent.

The “singleTask” and “singleInstance” modes also differ from each other in only one respect: A “singleTask” activity allows other activities to be part of its task. It’s always at the root of its task, but other activities (necessarily “standard” and “singleTop” activities) can be launched into that task. A “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 FLAG_ACTIVITY_NEW_TASK was in the intent.

As shown in the enum variant description, 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 button.

For more information on launch modes and their interaction with Intent flags, see the Tasks and Back Stack document.

Variants

Standard

Default. The system always creates a new instance of the activity in the target task and routes the intent to it.

Use Cases: Normal launches for most activities

Multiple Instances?: Yes

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.

Use Cases: Normal launches for most activities

Multiple Instances?: Conditionally

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.

Use Cases: Specialized launches (not recommended for general use)

Multiple Instances?: No

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.

Use Cases: Specialized launches (not recommended for general use)

Multiple Instances?: No

Trait Implementations

impl Clone for LaunchMode

fn clone(&self) -> LaunchMode

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LaunchMode

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LaunchMode

fn default() -> LaunchMode

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for LaunchMode

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for LaunchMode

fn eq(&self, other: &LaunchMode) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for LaunchMode

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl YaDeserialize for LaunchMode

fn deserialize<R: Read>(reader: &mut Deserializer<R>) -> Result<Self, String>

impl YaSerialize for LaunchMode

fn serialize<W: Write>(&self, writer: &mut Serializer<W>) -> Result<(), String>

fn serialize_attributes( &self, source_attributes: Vec<OwnedAttribute>, source_namespace: Namespace, ) -> Result<(Vec<OwnedAttribute>, Namespace), String>

impl Eq for LaunchMode

impl StructuralPartialEq for LaunchMode