android.support.v4.app
Class TaskStackBuilder

java.lang.Object
  android.support.v4.app.TaskStackBuilder

All Implemented Interfaces:

Iterable<android.content.Intent>

public class TaskStackBuilder
extends Object
implements Iterable<android.content.Intent>

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(int, int) 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 Tasks and Back Stack from the developer guide and Navigation from the design guide.

Method Summary

TaskStackBuilder	addNextIntent(android.content.Intent nextIntent) Add a new Intent to the task stack.
TaskStackBuilder	addParentStack(android.app.Activity sourceActivity) Add the activity parent chain as specified by manifest <meta-data> elements to the task stack builder.
TaskStackBuilder	addParentStack(Class<?> sourceActivityClass) Add the activity parent chain as specified by manifest <meta-data> elements to the task stack builder.
static TaskStackBuilder	from(android.content.Context context) Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.
android.content.Intent	getIntent(int index) Get the intent at the specified index.
int	getIntentCount()
android.app.PendingIntent	getPendingIntent(int requestCode, int flags) Obtain a PendingIntent for launching the task constructed by this builder so far.
Iterator<android.content.Intent>	iterator()
void	startActivities() Start the task stack constructed by this builder.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

from

public static TaskStackBuilder from(android.content.Context context)

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

Parameters:

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

Returns:

A new TaskStackBuilder

addNextIntent

public TaskStackBuilder addNextIntent(android.content.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 for the next Activity in the synthesized task stack

Returns:

This TaskStackBuilder for method chaining

addParentStack

public TaskStackBuilder addParentStack(android.app.Activity sourceActivity)

Add the activity parent chain as specified by manifest <meta-data> elements to the task stack builder.

Parameters:

sourceActivity - All parents of this activity will be added

Returns:

This TaskStackBuilder for method chaining

addParentStack

public TaskStackBuilder addParentStack(Class<?> sourceActivityClass)

Add the activity parent chain as specified by manifest <meta-data> elements to the task stack builder.

Parameters:

sourceActivityClass - All parents of this activity will be added

Returns:

This TaskStackBuilder for method chaining

getIntentCount

public int getIntentCount()

Returns:

the number of intents added so far.

getIntent

public android.content.Intent getIntent(int index)

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

Parameters:

index - Index from 0-getIntentCount()

Returns:

the intent at position index

iterator

public Iterator<android.content.Intent> iterator()

Specified by:

iterator in interface Iterable<android.content.Intent>

startActivities

public void startActivities()

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.

getPendingIntent

public android.app.PendingIntent getPendingIntent(int requestCode,
                                                  int flags)

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

Parameters:

requestCode - Private request code for the sender

flags - 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.

Returns:

The obtained PendingIntent