| /* |
| * Copyright (C) 2012 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.support.v4.app; |
| |
| import android.app.Activity; |
| import android.app.PendingIntent; |
| import android.content.ComponentName; |
| import android.content.Context; |
| import android.content.Intent; |
| import android.content.pm.PackageManager.NameNotFoundException; |
| import android.os.Build; |
| import android.os.Bundle; |
| import android.support.v4.content.ContextCompat; |
| import android.support.v4.content.IntentCompat; |
| import android.util.Log; |
| |
| import java.util.ArrayList; |
| import java.util.Iterator; |
| |
| /** |
| * Utility class for constructing synthetic back stacks for cross-task navigation |
| * on Android 3.0 and newer. |
| * |
| * <p>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.</p> |
| * |
| * <p>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.</p> |
| * |
| * <p>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 {@link #startActivities()} method or sending the |
| * {@link PendingIntent} generated by {@link #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.</p> |
| * |
| * <div class="special reference"> |
| * <h3>About Navigation</h3> |
| * For more detailed information about tasks, the back stack, and navigation design guidelines, |
| * please read |
| * <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> |
| * from the developer guide and <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> |
| * from the design guide. |
| * </div> |
| */ |
| public class TaskStackBuilder implements Iterable<Intent> { |
| private static final String TAG = "TaskStackBuilder"; |
| |
| public interface SupportParentable { |
| Intent getSupportParentActivityIntent(); |
| } |
| |
| interface TaskStackBuilderImpl { |
| PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, |
| int flags, Bundle options); |
| } |
| |
| static class TaskStackBuilderImplBase implements TaskStackBuilderImpl { |
| public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, |
| int flags, Bundle options) { |
| Intent topIntent = new Intent(intents[intents.length - 1]); |
| topIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); |
| return PendingIntent.getActivity(context, requestCode, topIntent, flags); |
| } |
| } |
| |
| static class TaskStackBuilderImplHoneycomb implements TaskStackBuilderImpl { |
| public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, |
| int flags, Bundle options) { |
| intents[0] = new Intent(intents[0]).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | |
| IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | |
| IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); |
| return TaskStackBuilderHoneycomb.getActivitiesPendingIntent(context, requestCode, |
| intents, flags); |
| } |
| } |
| |
| static class TaskStackBuilderImplJellybean implements TaskStackBuilderImpl { |
| public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, |
| int flags, Bundle options) { |
| intents[0] = new Intent(intents[0]).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | |
| IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | |
| IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); |
| return TaskStackBuilderJellybean.getActivitiesPendingIntent(context, requestCode, |
| intents, flags, options); |
| } |
| } |
| |
| private static final TaskStackBuilderImpl IMPL; |
| |
| static { |
| if (Build.VERSION.SDK_INT >= 11) { |
| IMPL = new TaskStackBuilderImplHoneycomb(); |
| } else { |
| IMPL = new TaskStackBuilderImplBase(); |
| } |
| } |
| |
| private final ArrayList<Intent> mIntents = new ArrayList<Intent>(); |
| private final Context mSourceContext; |
| |
| private TaskStackBuilder(Context a) { |
| mSourceContext = a; |
| } |
| |
| /** |
| * 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 |
| */ |
| public static TaskStackBuilder create(Context context) { |
| return new TaskStackBuilder(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 |
| * |
| * @deprecated use {@link #create(Context)} instead |
| */ |
| public static TaskStackBuilder from(Context context) { |
| return create(context); |
| } |
| |
| /** |
| * 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 |
| */ |
| public TaskStackBuilder addNextIntent(Intent nextIntent) { |
| mIntents.add(nextIntent); |
| return this; |
| } |
| |
| /** |
| * Add a new Intent with the resolved chain of parents for the target activity to |
| * the task stack. |
| * |
| * <p>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.</p> |
| * |
| * @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. |
| */ |
| public TaskStackBuilder addNextIntentWithParentStack(Intent nextIntent) { |
| ComponentName target = nextIntent.getComponent(); |
| if (target == null) { |
| target = nextIntent.resolveActivity(mSourceContext.getPackageManager()); |
| } |
| if (target != null) { |
| addParentStack(target); |
| } |
| addNextIntent(nextIntent); |
| return this; |
| } |
| |
| /** |
| * Add the activity parent chain as specified by manifest <meta-data> elements |
| * to the task stack builder. |
| * |
| * @param sourceActivity All parents of this activity will be added |
| * @return This TaskStackBuilder for method chaining |
| */ |
| public TaskStackBuilder addParentStack(Activity sourceActivity) { |
| Intent parent = null; |
| if (sourceActivity instanceof SupportParentable) { |
| parent = ((SupportParentable) sourceActivity).getSupportParentActivityIntent(); |
| } |
| if (parent == null) { |
| parent = NavUtils.getParentActivityIntent(sourceActivity); |
| } |
| |
| 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; |
| } |
| |
| /** |
| * Add the activity parent chain as specified by manifest <meta-data> elements |
| * to the task stack builder. |
| * |
| * @param sourceActivityClass All parents of this activity will be added |
| * @return This TaskStackBuilder for method chaining |
| */ |
| public TaskStackBuilder addParentStack(Class<?> sourceActivityClass) { |
| return addParentStack(new ComponentName(mSourceContext, sourceActivityClass)); |
| } |
| |
| /** |
| * Add the activity parent chain as specified by manifest <meta-data> elements |
| * 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 |
| */ |
| public TaskStackBuilder addParentStack(ComponentName sourceActivityName) { |
| final int insertAt = mIntents.size(); |
| try { |
| Intent parent = NavUtils.getParentActivityIntent(mSourceContext, sourceActivityName); |
| while (parent != null) { |
| mIntents.add(insertAt, parent); |
| parent = NavUtils.getParentActivityIntent(mSourceContext, parent.getComponent()); |
| } |
| } catch (NameNotFoundException e) { |
| Log.e(TAG, "Bad ComponentName while traversing activity parent metadata"); |
| throw new IllegalArgumentException(e); |
| } |
| return this; |
| } |
| |
| /** |
| * @return the number of intents added so far. |
| */ |
| public int getIntentCount() { |
| return mIntents.size(); |
| } |
| |
| /** |
| * 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 {@link #addParentStack(Activity)}. |
| * |
| * @param index Index from 0-getIntentCount() |
| * @return the intent at position index |
| * |
| * @deprecated Renamed to editIntentAt to better reflect intended usage |
| */ |
| public Intent getIntent(int index) { |
| return editIntentAt(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 |
| */ |
| public Intent editIntentAt(int index) { |
| return mIntents.get(index); |
| } |
| |
| /** |
| * @deprecated Use editIntentAt instead |
| */ |
| public Iterator<Intent> iterator() { |
| return mIntents.iterator(); |
| } |
| |
| /** |
| * Start the task stack constructed by this builder. The Context used to obtain |
| * this builder must be an Activity. |
| * |
| * <p>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.</p> |
| */ |
| public void startActivities() { |
| startActivities(null); |
| } |
| |
| /** |
| * Start the task stack constructed by this builder. The Context used to obtain |
| * this builder must be an Activity. |
| * |
| * <p>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.</p> |
| * |
| * @param options Additional options for how the Activity should be started. |
| * See {@link android.content.Context#startActivity(Intent, Bundle) |
| */ |
| public void startActivities(Bundle options) { |
| if (mIntents.isEmpty()) { |
| throw new IllegalStateException( |
| "No intents added to TaskStackBuilder; cannot startActivities"); |
| } |
| |
| Intent[] intents = mIntents.toArray(new Intent[mIntents.size()]); |
| intents[0] = new Intent(intents[0]).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | |
| IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | |
| IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); |
| if (!ContextCompat.startActivities(mSourceContext, intents, options)) { |
| Intent topIntent = new Intent(intents[intents.length - 1]); |
| topIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); |
| mSourceContext.startActivity(topIntent); |
| } |
| } |
| |
| /** |
| * 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 |
| */ |
| public PendingIntent getPendingIntent(int requestCode, int flags) { |
| return getPendingIntent(requestCode, flags, null); |
| } |
| |
| /** |
| * 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) |
| * @return The obtained PendingIntent |
| */ |
| public PendingIntent getPendingIntent(int requestCode, int flags, Bundle options) { |
| if (mIntents.isEmpty()) { |
| throw new IllegalStateException( |
| "No intents added to TaskStackBuilder; cannot getPendingIntent"); |
| } |
| |
| Intent[] intents = mIntents.toArray(new Intent[mIntents.size()]); |
| intents[0] = new Intent(intents[0]).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | |
| IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | |
| IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); |
| // Appropriate flags will be added by the call below. |
| return IMPL.getPendingIntent(mSourceContext, intents, requestCode, flags, options); |
| } |
| |
| /** |
| * 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. |
| */ |
| public Intent[] getIntents() { |
| 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 | |
| IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | |
| IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); |
| for (int i = 1; i < intents.length; i++) { |
| intents[i] = new Intent(mIntents.get(i)); |
| } |
| return intents; |
| } |
| } |