FileDocCategorySizeDatePackage
TaskStackBuilder.javaAPI DocAndroid 5.1 API12941Thu Mar 12 22:22:10 GMT 2015android.app

TaskStackBuilder

public class TaskStackBuilder extends Object
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.

Fields Summary
private static final String
TAG
private final ArrayList
mIntents
private final android.content.Context
mSourceContext
Constructors Summary
private TaskStackBuilder(android.content.Context a)


       
        mSourceContext = a;
    
Methods Summary
public android.app.TaskStackBuilderaddNextIntent(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.

param
nextIntent Intent for the next Activity in the synthesized task stack
return
This TaskStackBuilder for method chaining

        mIntents.add(nextIntent);
        return this;
    
public android.app.TaskStackBuilderaddNextIntentWithParentStack(android.content.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 {@link #addParentStack(ComponentName) addParentStack} with the resolved ComponentName of nextIntent (if it can be resolved), followed by {@link #addNextIntent(Intent) addNextIntent} with nextIntent.

param
nextIntent Intent for the topmost Activity in the synthesized task stack. Its chain of parents as specified in the manifest will be added.
return
This TaskStackBuilder for method chaining.

        ComponentName target = nextIntent.getComponent();
        if (target == null) {
            target = nextIntent.resolveActivity(mSourceContext.getPackageManager());
        }
        if (target != null) {
            addParentStack(target);
        }
        addNextIntent(nextIntent);
        return this;
    
public android.app.TaskStackBuilderaddParentStack(Activity sourceActivity)
Add the activity parent chain as specified by the {@link Activity#getParentActivityIntent() getParentActivityIntent()} method of the activity specified and the {@link android.R.attr#parentActivityName parentActivityName} attributes of each successive activity (or activity-alias) element in the application's manifest to the task stack builder.

param
sourceActivity All parents of this activity will be added
return
This TaskStackBuilder for method chaining

        final Intent parent = sourceActivity.getParentActivityIntent();
        if (parent != null) {
            // We have the actual parent intent, build the rest from static metadata
            // then add the direct parent intent to the end.
            ComponentName target = parent.getComponent();
            if (target == null) {
                target = parent.resolveActivity(mSourceContext.getPackageManager());
            }
            addParentStack(target);
            addNextIntent(parent);
        }
        return this;
    
public android.app.TaskStackBuilderaddParentStack(java.lang.Class sourceActivityClass)
Add the activity parent chain as specified by the {@link android.R.attr#parentActivityName parentActivityName} attribute of the activity (or activity-alias) element in the application's manifest to the task stack builder.

param
sourceActivityClass All parents of this activity will be added
return
This TaskStackBuilder for method chaining

        return addParentStack(new ComponentName(mSourceContext, sourceActivityClass));
    
public android.app.TaskStackBuilderaddParentStack(android.content.ComponentName sourceActivityName)
Add the activity parent chain as specified by the {@link android.R.attr#parentActivityName parentActivityName} attribute of the activity (or activity-alias) element in the application's manifest to the task stack builder.

param
sourceActivityName Must specify an Activity component. All parents of this activity will be added
return
This TaskStackBuilder for method chaining

        final int insertAt = mIntents.size();
        PackageManager pm = mSourceContext.getPackageManager();
        try {
            ActivityInfo info = pm.getActivityInfo(sourceActivityName, 0);
            String parentActivity = info.parentActivityName;
            while (parentActivity != null) {
                final ComponentName target = new ComponentName(info.packageName, parentActivity);
                info = pm.getActivityInfo(target, 0);
                parentActivity = info.parentActivityName;
                final Intent parent = parentActivity == null && insertAt == 0
                        ? Intent.makeMainActivity(target)
                        : new Intent().setComponent(target);
                mIntents.add(insertAt, parent);
            }
        } catch (NameNotFoundException e) {
            Log.e(TAG, "Bad ComponentName while traversing activity parent metadata");
            throw new IllegalArgumentException(e);
        }
        return this;
    
public static android.app.TaskStackBuildercreate(android.content.Context context)
Return a new TaskStackBuilder for launching a fresh task stack consisting of a series of activities.

param
context The context that will launch the new task stack or generate a PendingIntent
return
A new TaskStackBuilder

        return new TaskStackBuilder(context);
    
public android.content.IntenteditIntentAt(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 {@link #addParentStack(Activity)}.

param
index Index from 0-getIntentCount()
return
the intent at position index

        return mIntents.get(index);
    
public intgetIntentCount()

return
the number of intents added so far.

        return mIntents.size();
    
public android.content.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.

return
An array containing the intents added to this builder.

        Intent[] intents = new Intent[mIntents.size()];
        if (intents.length == 0) return intents;

        intents[0] = new Intent(mIntents.get(0)).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK |
                Intent.FLAG_ACTIVITY_CLEAR_TASK |
                Intent.FLAG_ACTIVITY_TASK_ON_HOME);
        for (int i = 1; i < intents.length; i++) {
            intents[i] = new Intent(mIntents.get(i));
        }
        return intents;
    
public PendingIntentgetPendingIntent(int requestCode, int flags)
Obtain a {@link PendingIntent} for launching the task constructed by this builder so far.

param
requestCode Private request code for the sender
param
flags May be {@link PendingIntent#FLAG_ONE_SHOT}, {@link PendingIntent#FLAG_NO_CREATE}, {@link PendingIntent#FLAG_CANCEL_CURRENT}, {@link PendingIntent#FLAG_UPDATE_CURRENT}, or any of the flags supported by {@link Intent#fillIn(Intent, int)} to control which unspecified parts of the intent that can be supplied when the actual send happens.
return
The obtained PendingIntent

        return getPendingIntent(requestCode, flags, null);
    
public PendingIntentgetPendingIntent(int requestCode, int flags, android.os.Bundle options)
Obtain a {@link PendingIntent} for launching the task constructed by this builder so far.

param
requestCode Private request code for the sender
param
flags May be {@link PendingIntent#FLAG_ONE_SHOT}, {@link PendingIntent#FLAG_NO_CREATE}, {@link PendingIntent#FLAG_CANCEL_CURRENT}, {@link PendingIntent#FLAG_UPDATE_CURRENT}, or any of the flags supported by {@link Intent#fillIn(Intent, int)} to control which unspecified parts of the intent that can be supplied when the actual send happens.
param
options Additional options for how the Activity should be started. See {@link android.content.Context#startActivity(Intent, Bundle) Context.startActivity(Intent, Bundle)} for more details.
return
The obtained PendingIntent

        if (mIntents.isEmpty()) {
            throw new IllegalStateException(
                    "No intents added to TaskStackBuilder; cannot getPendingIntent");
        }

        return PendingIntent.getActivities(mSourceContext, requestCode, getIntents(),
                flags, options);
    
public PendingIntentgetPendingIntent(int requestCode, int flags, android.os.Bundle options, android.os.UserHandle user)

hide

        if (mIntents.isEmpty()) {
            throw new IllegalStateException(
                    "No intents added to TaskStackBuilder; cannot getPendingIntent");
        }

        return PendingIntent.getActivitiesAsUser(mSourceContext, requestCode, getIntents(), flags,
                options, user);
    
public voidstartActivities()
Start the task stack constructed by this builder.

        startActivities(null);
    
public voidstartActivities(android.os.Bundle options, android.os.UserHandle userHandle)
Start the task stack constructed by this builder.

hide

        if (mIntents.isEmpty()) {
            throw new IllegalStateException(
                    "No intents added to TaskStackBuilder; cannot startActivities");
        }

        mSourceContext.startActivitiesAsUser(getIntents(), options, userHandle);
    
public voidstartActivities(android.os.Bundle options)
Start the task stack constructed by this builder.

param
options Additional options for how the Activity should be started. See {@link android.content.Context#startActivity(Intent, Bundle) Context.startActivity(Intent, Bundle)} for more details.

        startActivities(options, new UserHandle(UserHandle.myUserId()));