public final class TaskStackBuilder extends Object implements Iterable<Intent>
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.
Modifier and Type | Class and Description |
---|---|
static interface |
TaskStackBuilder.SupportParentable |
Modifier and Type | Method and Description |
---|---|
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(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.
|
TaskStackBuilder |
addParentStack(ComponentName sourceActivityName)
Add the activity parent chain as specified by manifest <meta-data> elements
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.
|
static TaskStackBuilder |
from(Context context)
Deprecated.
use
create(Context) instead |
Intent |
getIntent(int index)
Deprecated.
Renamed to editIntentAt to better reflect intended usage
|
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. |
Iterator<Intent> |
iterator()
Deprecated.
Use editIntentAt instead
|
void |
startActivities()
Start the task stack constructed by this builder.
|
void |
startActivities(Bundle options)
Start the task stack constructed by this builder.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
forEach, spliterator
public static TaskStackBuilder create(Context context)
context
- The context that will launch the new task stack or generate a PendingIntent@Deprecated public static TaskStackBuilder from(Context context)
create(Context)
insteadcontext
- The context that will launch the new task stack or generate a PendingIntentpublic TaskStackBuilder addNextIntent(Intent nextIntent)
nextIntent
- Intent for the next Activity in the synthesized task stackpublic TaskStackBuilder addNextIntentWithParentStack(Intent nextIntent)
This is equivalent to calling addParentStack
with the resolved ComponentName of nextIntent (if it can be resolved), followed by
addNextIntent
with nextIntent.
nextIntent
- Intent for the topmost Activity in the synthesized task stack.
Its chain of parents as specified in the manifest will be added.public TaskStackBuilder addParentStack(Activity sourceActivity)
sourceActivity
- All parents of this activity will be addedpublic TaskStackBuilder addParentStack(Class<?> sourceActivityClass)
sourceActivityClass
- All parents of this activity will be addedpublic TaskStackBuilder addParentStack(ComponentName sourceActivityName)
sourceActivityName
- Must specify an Activity component. All parents of
this activity will be addedpublic int getIntentCount()
@Deprecated public Intent getIntent(int index)
addParentStack(Activity)
.index
- Index from 0-getIntentCount()public Intent editIntentAt(int index)
addParentStack(Activity)
.index
- Index from 0-getIntentCount()@Deprecated public Iterator<Intent> iterator()
Iterable
T
.public void startActivities()
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.
public void startActivities(Bundle options)
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.
options
- Additional options for how the Activity should be started.
See {@link android.content.Context#startActivity(Intent, Bundle)public PendingIntent getPendingIntent(int requestCode, int flags)
PendingIntent
for launching the task constructed by this builder so far.requestCode
- Private request code for the senderflags
- 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.public PendingIntent getPendingIntent(int requestCode, int flags, Bundle options)
PendingIntent
for launching the task constructed by this builder so far.requestCode
- Private request code for the senderflags
- 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.options
- Additional options for how the Activity should be started.
See {@link android.content.Context#startActivity(Intent, Bundle)public Intent[] getIntents()