Added in API level 16

Summary: Methods | Inherited Methods

TaskStackBuilder

---

Kotlin |Java

public class TaskStackBuilder
extends Object

java.lang.Object
↳	android.app.TaskStackBuilder

---

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 way to obey the correct conventions around cross-task navigation.

About Navigation

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

Summary

Public methods
TaskStackBuilder	addNextIntent(Intent nextIntent) Add a new Intent to the task stack.
TaskStackBuilder	addNextIntentWithParentStack(Intent nextIntent) Add a new Intent with the resolved chain of parents for the target activity to the task stack.
TaskStackBuilder	addParentStack(ComponentName sourceActivityName) Add the activity parent chain as specified by the parentActivityName attribute of the activity (or activity-alias) element in the application's manifest to the task stack builder.
TaskStackBuilder	addParentStack(Activity sourceActivity) Add the activity parent chain as specified by the getParentActivityIntent() method of the activity specified and the parentActivityName attributes of each successive activity (or activity-alias) element in the application's manifest to the task stack builder.
TaskStackBuilder	addParentStack(Class<?> sourceActivityClass) Add the activity parent chain as specified by the parentActivityName attribute of the activity (or activity-alias) element in the application's manifest to the task stack builder.
static TaskStackBuilder	create(Context context) Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.
Intent	editIntentAt(int index) Return the intent at the specified index for modification.
int	getIntentCount()
Intent[]	getIntents() Return an array containing the intents added to this builder.
PendingIntent	getPendingIntent(int requestCode, int flags) Obtain a PendingIntent for launching the task constructed by this builder so far.
PendingIntent	getPendingIntent(int requestCode, int flags, Bundle options) Obtain a PendingIntent for launching the task constructed by this builder so far.
void	startActivities() Start the task stack constructed by this builder.
void	startActivities(Bundle options) Start the task stack constructed by this builder.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

addNextIntent

Added in API level 16

public TaskStackBuilder addNextIntent (Intent nextIntent)

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 API level 16

public TaskStackBuilder addNextIntentWithParentStack (Intent nextIntent)

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 API level 16

public TaskStackBuilder addParentStack (ComponentName sourceActivityName)

Add the activity parent chain as specified by the parentActivityName attribute of the activity (or activity-alias) element in the application's manifest 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

addParentStack

Added in API level 16

public TaskStackBuilder addParentStack (Activity sourceActivity)

Add the activity parent chain as specified by the getParentActivityIntent() method of the activity specified and the parentActivityName attributes of each successive activity (or activity-alias) element in the application's manifest 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 API level 16

public TaskStackBuilder addParentStack (Class<?> sourceActivityClass)

Add the activity parent chain as specified by the parentActivityName attribute of the activity (or activity-alias) element in the application's manifest to the task stack builder.

Parameters
sourceActivityClass	Class: All parents of this activity will be added

Returns
TaskStackBuilder	This TaskStackBuilder for method chaining

create

Added in API level 16

public static TaskStackBuilder create (Context context)

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 API level 16

public Intent editIntentAt (int index)

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(android.app.Activity).

Parameters
index	int: Index from 0-getIntentCount()

Returns
Intent	the intent at position index

getIntentCount

Added in API level 16

public int getIntentCount ()

Returns
int	the number of intents added so far.

getIntents

Added in API level 16

public Intent[] getIntents ()

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
Intent[]	An array containing the intents added to this builder. This value cannot be null.

getPendingIntent

Added in API level 16

public PendingIntent getPendingIntent (int requestCode, 
                int flags)

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 PendingIntent#FLAG_ONE_SHOT, PendingIntent#FLAG_NO_CREATE, PendingIntent#FLAG_CANCEL_CURRENT, PendingIntent#FLAG_UPDATE_CURRENT, or any of the flags supported by Intent#fillIn(Intent, int) to control which unspecified parts of the intent that can be supplied when the actual send happens. Value is either 0 or a combination of PendingIntent.FLAG_ONE_SHOT, PendingIntent.FLAG_NO_CREATE, PendingIntent.FLAG_CANCEL_CURRENT, PendingIntent.FLAG_UPDATE_CURRENT, PendingIntent.FLAG_IMMUTABLE, PendingIntent.FLAG_MUTABLE, android.app.PendingIntent.FLAG_MUTABLE_UNAUDITED, PendingIntent.FLAG_ALLOW_UNSAFE_IMPLICIT_INTENT, Intent.FILL_IN_ACTION, Intent.FILL_IN_DATA, Intent.FILL_IN_CATEGORIES, Intent.FILL_IN_COMPONENT, Intent.FILL_IN_PACKAGE, Intent.FILL_IN_SOURCE_BOUNDS, Intent.FILL_IN_SELECTOR, and Intent.FILL_IN_CLIP_DATA

Returns
PendingIntent	The obtained PendingIntent

getPendingIntent

Added in API level 16

public PendingIntent getPendingIntent (int requestCode, 
                int flags, 
                Bundle options)

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 PendingIntent#FLAG_ONE_SHOT, PendingIntent#FLAG_NO_CREATE, PendingIntent#FLAG_CANCEL_CURRENT, PendingIntent#FLAG_UPDATE_CURRENT, or any of the flags supported by Intent#fillIn(Intent, int) to control which unspecified parts of the intent that can be supplied when the actual send happens. Value is either 0 or a combination of PendingIntent.FLAG_ONE_SHOT, PendingIntent.FLAG_NO_CREATE, PendingIntent.FLAG_CANCEL_CURRENT, PendingIntent.FLAG_UPDATE_CURRENT, PendingIntent.FLAG_IMMUTABLE, PendingIntent.FLAG_MUTABLE, android.app.PendingIntent.FLAG_MUTABLE_UNAUDITED, PendingIntent.FLAG_ALLOW_UNSAFE_IMPLICIT_INTENT, Intent.FILL_IN_ACTION, Intent.FILL_IN_DATA, Intent.FILL_IN_CATEGORIES, Intent.FILL_IN_COMPONENT, Intent.FILL_IN_PACKAGE, Intent.FILL_IN_SOURCE_BOUNDS, Intent.FILL_IN_SELECTOR, and Intent.FILL_IN_CLIP_DATA
options	Bundle: Additional options for how the Activity should be started. See Context.startActivity(Intent, Bundle) Context.startActivity(Intent, Bundle)} for more details.

Returns
PendingIntent	The obtained PendingIntent

startActivities

Added in API level 16

public void startActivities ()

Start the task stack constructed by this builder.

startActivities

Added in API level 16

public void startActivities (Bundle options)

Start the task stack constructed by this builder.

Parameters
options	Bundle: Additional options for how the Activity should be started. See Context.startActivity(Intent, Bundle) Context.startActivity(Intent, Bundle)} for more details.