TaskStackBuilder

Added in 1.1.0

class TaskStackBuilder : Iterable

Utility class for constructing synthetic back stacks for cross-task navigation on Android 3.0 and newer.

In API level 11 (Android 3.0/Honeycomb) the recommended conventions for app navigation using the back key changed. The back key's behavior is local to the current task and does not capture navigation across different tasks. Navigating across tasks and easily reaching the previous task is accomplished through the "recents" UI, accessible through the software-provided Recents key on the navigation or system bar. On devices with the older hardware button configuration the recents UI can be accessed with a long press on the Home key.

When crossing from one task stack to another post-Android 3.0, the application should synthesize a back stack/history for the new task so that the user may navigate out of the new task and back to the Launcher by repeated presses of the back key. Back key presses should not navigate across task stacks.

TaskStackBuilder provides a backward-compatible way to obey the correct conventions around cross-task navigation on the device's version of the platform. On devices running Android 3.0 or newer, calls to the startActivities method or sending the PendingIntent generated by getPendingIntent will construct the synthetic back stack as prescribed. On devices running older versions of the platform, these same calls will invoke the topmost activity in the supplied stack, ignoring the rest of the synthetic stack and allowing the back key to navigate back to the previous task.

### About Navigation For more detailed information about tasks, the back stack, and navigation design guidelines, please read from the developer guide and from the design guide.

Summary

Nested types

Public functions
TaskStackBuilder
addNextIntent(nextIntent: Intent)

Add a new Intent to the task stack.
TaskStackBuilder

Add a new Intent with the resolved chain of parents for the target activity to the task stack.
TaskStackBuilder
addParentStack(sourceActivity: Activity)

Add the activity parent chain as specified by manifest elements to the task stack builder.
TaskStackBuilder
addParentStack(sourceActivityClass: Class<Any!>)

Add the activity parent chain as specified by manifest elements to the task stack builder.
TaskStackBuilder
addParentStack(sourceActivityName: ComponentName)

Add the activity parent chain as specified by manifest elements to the task stack builder.
java-static TaskStackBuilder
create(context: Context)

Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.
Intent?
editIntentAt(index: Int)

Return the intent at the specified index for modification.
java-static TaskStackBuilder!
from(context: Context!)

This function is deprecated.

use create instead
Intent!
getIntent(index: Int)

This function is deprecated.

Renamed to editIntentAt to better reflect intended usage
Int
Array<Intent!>

Return an array containing the intents added to this builder.
PendingIntent?
getPendingIntent(requestCode: Int, flags: Int)

Obtain a PendingIntent for launching the task constructed by this builder so far.
PendingIntent?
getPendingIntent(requestCode: Int, flags: Int, isMutable: Boolean)

Obtains a PendingIntent with mandatory mutability flag set on supported platform versions.
PendingIntent?
getPendingIntent(requestCode: Int, flags: Int, options: Bundle?)

Obtain a PendingIntent for launching the task constructed by this builder so far.
PendingIntent?
getPendingIntent(
    requestCode: Int,
    flags: Int,
    options: Bundle?,
    isMutable: Boolean
)

Obtains a PendingIntent with mandatory mutability flag set on supported platform versions.
(Mutable)Iterator<Intent!>

This function is deprecated.

Use editIntentAt instead
Unit

Start the task stack constructed by this builder.
Unit

Start the task stack constructed by this builder.

Inherited functions
From java.lang.Iterable
Unit
forEach(action: Consumer<T!>!)
Spliterator<T!>!

Public functions

addNextIntent

Added in 1.1.0
fun addNextIntent(nextIntent: Intent): TaskStackBuilder

Add a new Intent to the task stack. The most recently added Intent will invoke the Activity at the top of the final task stack.

Parameters
nextIntent: Intent

Intent for the next Activity in the synthesized task stack
Returns
TaskStackBuilder

This TaskStackBuilder for method chaining

addNextIntentWithParentStack

Added in 1.1.0
fun addNextIntentWithParentStack(nextIntent: Intent): TaskStackBuilder

Add a new Intent with the resolved chain of parents for the target activity to the task stack.

This is equivalent to calling addParentStack with the resolved ComponentName of nextIntent (if it can be resolved), followed by addNextIntent with nextIntent.

Parameters
nextIntent: Intent

Intent for the topmost Activity in the synthesized task stack. Its chain of parents as specified in the manifest will be added.
Returns
TaskStackBuilder

This TaskStackBuilder for method chaining.

addParentStack

Added in 1.1.0
fun addParentStack(sourceActivity: Activity): TaskStackBuilder

Add the activity parent chain as specified by manifest elements to the task stack builder.

Parameters
sourceActivity: Activity

All parents of this activity will be added
Returns
TaskStackBuilder

This TaskStackBuilder for method chaining

addParentStack

Added in 1.1.0
fun addParentStack(sourceActivityClass: Class<Any!>): TaskStackBuilder

Add the activity parent chain as specified by manifest elements to the task stack builder.

Parameters
sourceActivityClass: Class<Any!>

All parents of this activity will be added
Returns
TaskStackBuilder

This TaskStackBuilder for method chaining

addParentStack

Added in 1.1.0
fun addParentStack(sourceActivityName: ComponentName): TaskStackBuilder

Add the activity parent chain as specified by manifest elements to the task stack builder.

Parameters
sourceActivityName: ComponentName

Must specify an Activity component. All parents of this activity will be added
Returns
TaskStackBuilder

This TaskStackBuilder for method chaining

create

Added in 1.1.0
java-static fun create(context: Context): TaskStackBuilder

Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.

Parameters
context: Context

The context that will launch the new task stack or generate a PendingIntent
Returns
TaskStackBuilder

A new TaskStackBuilder

editIntentAt

Added in 1.1.0
fun editIntentAt(index: Int): Intent?

Return the intent at the specified index for modification. Useful if you need to modify the flags or extras of an intent that was previously added, for example with addParentStack.

Parameters
index: Int

Index from 0-getIntentCount()
Returns
Intent?

the intent at position index

from

Added in 1.1.0
Deprecated in 1.1.0
java-static fun from(context: Context!): TaskStackBuilder!

Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.

Parameters
context: Context!

The context that will launch the new task stack or generate a PendingIntent
Returns
TaskStackBuilder!

A new TaskStackBuilder

getIntent

Added in 1.1.0
Deprecated in 1.1.0
fun getIntent(index: Int): Intent!

Get the intent at the specified index. Useful if you need to modify the flags or extras of an intent that was previously added, for example with addParentStack.

Parameters
index: Int

Index from 0-getIntentCount()
Returns
Intent!

the intent at position index

getIntentCount

Added in 1.1.0
fun getIntentCount(): Int
Returns
Int

the number of intents added so far.

getIntents

Added in 1.1.0
fun getIntents(): Array<Intent!>

Return an array containing the intents added to this builder. The intent at the root of the task stack will appear as the first item in the array and the intent at the top of the stack will appear as the last item.

Returns
Array<Intent!>

An array containing the intents added to this builder.

getPendingIntent

Added in 1.1.0
fun getPendingIntent(requestCode: Int, flags: Int): PendingIntent?

Obtain a PendingIntent for launching the task constructed by this builder so far.

Parameters
requestCode: Int

Private request code for the sender
flags: Int

May be FLAG_ONE_SHOT, FLAG_NO_CREATE, FLAG_CANCEL_CURRENT, FLAG_UPDATE_CURRENT, or any of the flags supported by fillIn to control which unspecified parts of the intent that can be supplied when the actual send happens.
Returns
PendingIntent?

The obtained PendingIntent. May return null only if FLAG_NO_CREATE has been supplied.

getPendingIntent

fun getPendingIntent(requestCode: Int, flags: Int, isMutable: Boolean): PendingIntent?

Obtains a PendingIntent with mandatory mutability flag set on supported platform versions. The caller provides the flag as combination of all the other values except mutability flag. This method combines mutability flag when necessary. See getPendingIntent.

getPendingIntent

Added in 1.1.0
fun getPendingIntent(requestCode: Int, flags: Int, options: Bundle?): PendingIntent?

Obtain a PendingIntent for launching the task constructed by this builder so far.

Parameters
requestCode: Int

Private request code for the sender
flags: Int

May be FLAG_ONE_SHOT, FLAG_NO_CREATE, FLAG_CANCEL_CURRENT, FLAG_UPDATE_CURRENT, or any of the flags supported by fillIn to control which unspecified parts of the intent that can be supplied when the actual send happens.
options: Bundle?

Additional options for how the Activity should be started. See startActivity
Returns
PendingIntent?

The obtained PendingIntent. May return null only if FLAG_NO_CREATE has been supplied.

getPendingIntent

fun getPendingIntent(
    requestCode: Int,
    flags: Int,
    options: Bundle?,
    isMutable: Boolean
): PendingIntent?

Obtains a PendingIntent with mandatory mutability flag set on supported platform versions. The caller provides the flag as combination of all the other values except mutability flag. This method combines mutability flag when necessary. See getPendingIntent.

iterator

Added in 1.1.0
Deprecated in 1.1.0
fun iterator(): (Mutable)Iterator<Intent!>

startActivities

Added in 1.1.0
fun startActivities(): Unit

Start the task stack constructed by this builder. The Context used to obtain this builder must be an Activity.

On devices that do not support API level 11 or higher the topmost activity will be started as a new task. On devices that do support API level 11 or higher the new task stack will be created in its entirety.

startActivities

Added in 1.1.0
fun startActivities(options: Bundle?): Unit

Start the task stack constructed by this builder. The Context used to obtain this builder must be an Activity.

On devices that do not support API level 11 or higher the topmost activity will be started as a new task. On devices that do support API level 11 or higher the new task stack will be created in its entirety.

Parameters
options: Bundle?

Additional options for how the Activity should be started. See startActivity