TaskStackBuilder.java revision 0306ebc908d5dcf148aa319a9734b419eacb23b5
1/* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.support.v4.app; 18 19import android.app.Activity; 20import android.app.PendingIntent; 21import android.content.Context; 22import android.content.Intent; 23import android.content.pm.PackageManager.NameNotFoundException; 24import android.os.Build; 25import android.os.Bundle; 26import android.support.v4.content.IntentCompat; 27import android.util.Log; 28 29import java.util.ArrayList; 30import java.util.Iterator; 31 32/** 33 * Utility class for constructing synthetic back stacks for cross-task navigation 34 * on Android 3.0 and newer. 35 * 36 * <p>In API level 11 (Android 3.0/Honeycomb) the recommended conventions for 37 * app navigation using the back key changed. The back key's behavior is local 38 * to the current task and does not capture navigation across different tasks. 39 * Navigating across tasks and easily reaching the previous task is accomplished 40 * through the "recents" UI, accessible through the software-provided Recents key 41 * on the navigation or system bar. On devices with the older hardware button configuration 42 * the recents UI can be accessed with a long press on the Home key.</p> 43 * 44 * <p>When crossing from one task stack to another post-Android 3.0, 45 * the application should synthesize a back stack/history for the new task so that 46 * the user may navigate out of the new task and back to the Launcher by repeated 47 * presses of the back key. Back key presses should not navigate across task stacks.</p> 48 * 49 * <p>TaskStackBuilder provides a backward-compatible way to obey the correct conventions 50 * around cross-task navigation on the device's version of the platform. On devices running 51 * Android 3.0 or newer, calls to the {@link #startActivities()} method or sending the 52 * {@link PendingIntent} generated by {@link #getPendingIntent(int, int)} will construct 53 * the synthetic back stack as prescribed. On devices running older versions of the platform, 54 * these same calls will invoke the topmost activity in the supplied stack, ignoring 55 * the rest of the synthetic stack and allowing the back key to navigate back to the previous 56 * task.</p> 57 * 58 * <div class="special reference"> 59 * <h3>About Navigation</h3> 60 * For more detailed information about tasks, the back stack, and navigation design guidelines, 61 * please read 62 * <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a> 63 * from the developer guide and <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> 64 * from the design guide. 65 * </div> 66 */ 67public class TaskStackBuilder implements Iterable<Intent> { 68 private static final String TAG = "TaskStackBuilder"; 69 70 interface TaskStackBuilderImpl { 71 PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, 72 int flags, Bundle options); 73 } 74 75 static class TaskStackBuilderImplBase implements TaskStackBuilderImpl { 76 public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, 77 int flags, Bundle options) { 78 Intent topIntent = intents[intents.length - 1]; 79 topIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 80 return PendingIntent.getActivity(context, requestCode, topIntent, flags); 81 } 82 } 83 84 static class TaskStackBuilderImplHoneycomb implements TaskStackBuilderImpl { 85 public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, 86 int flags, Bundle options) { 87 intents[0].addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 88 IntentCompat.FLAG_ACTIVITY_CLEAR_TASK); 89 return TaskStackBuilderHoneycomb.getActivitiesPendingIntent(context, requestCode, 90 intents, flags); 91 } 92 } 93 94 static class TaskStackBuilderImplJellybean implements TaskStackBuilderImpl { 95 public PendingIntent getPendingIntent(Context context, Intent[] intents, int requestCode, 96 int flags, Bundle options) { 97 intents[0].addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 98 IntentCompat.FLAG_ACTIVITY_CLEAR_TASK); 99 return TaskStackBuilderJellybean.getActivitiesPendingIntent(context, requestCode, 100 intents, flags, options); 101 } 102 } 103 104 private static final TaskStackBuilderImpl IMPL; 105 106 static { 107 if (Build.VERSION.SDK_INT >= 11) { 108 IMPL = new TaskStackBuilderImplHoneycomb(); 109 } else { 110 IMPL = new TaskStackBuilderImplBase(); 111 } 112 } 113 114 private final ArrayList<Intent> mIntents = new ArrayList<Intent>(); 115 private final Context mSourceContext; 116 117 private TaskStackBuilder(Context a) { 118 mSourceContext = a; 119 } 120 121 /** 122 * Return a new TaskStackBuilder for launching a fresh task stack consisting 123 * of a series of activities. 124 * 125 * @param context The context that will launch the new task stack or generate a PendingIntent 126 * @return A new TaskStackBuilder 127 */ 128 public static TaskStackBuilder create(Context context) { 129 return new TaskStackBuilder(context); 130 } 131 132 /** 133 * Return a new TaskStackBuilder for launching a fresh task stack consisting 134 * of a series of activities. 135 * 136 * @param context The context that will launch the new task stack or generate a PendingIntent 137 * @return A new TaskStackBuilder 138 * 139 * @deprecated use {@link #create(Context)} instead 140 */ 141 public static TaskStackBuilder from(Context context) { 142 return create(context); 143 } 144 145 /** 146 * Add a new Intent to the task stack. The most recently added Intent will invoke 147 * the Activity at the top of the final task stack. 148 * 149 * @param nextIntent Intent for the next Activity in the synthesized task stack 150 * @return This TaskStackBuilder for method chaining 151 */ 152 public TaskStackBuilder addNextIntent(Intent nextIntent) { 153 mIntents.add(nextIntent); 154 return this; 155 } 156 157 /** 158 * Add the activity parent chain as specified by manifest <meta-data> elements 159 * to the task stack builder. 160 * 161 * @param sourceActivity All parents of this activity will be added 162 * @return This TaskStackBuilder for method chaining 163 */ 164 public TaskStackBuilder addParentStack(Activity sourceActivity) { 165 final int insertAt = mIntents.size(); 166 Intent parent = NavUtils.getParentActivityIntent(sourceActivity); 167 while (parent != null) { 168 mIntents.add(insertAt, parent); 169 try { 170 parent = NavUtils.getParentActivityIntent(sourceActivity, parent.getComponent()); 171 } catch (NameNotFoundException e) { 172 Log.e(TAG, "Bad ComponentName while traversing activity parent metadata"); 173 throw new IllegalArgumentException(e); 174 } 175 } 176 return this; 177 } 178 179 /** 180 * Add the activity parent chain as specified by manifest <meta-data> elements 181 * to the task stack builder. 182 * 183 * @param sourceActivityClass All parents of this activity will be added 184 * @return This TaskStackBuilder for method chaining 185 */ 186 public TaskStackBuilder addParentStack(Class<?> sourceActivityClass) { 187 final int insertAt = mIntents.size(); 188 try { 189 Intent parent = NavUtils.getParentActivityIntent(mSourceContext, sourceActivityClass); 190 while (parent != null) { 191 mIntents.add(insertAt, parent); 192 parent = NavUtils.getParentActivityIntent(mSourceContext, parent.getComponent()); 193 } 194 } catch (NameNotFoundException e) { 195 Log.e(TAG, "Bad ComponentName while traversing activity parent metadata"); 196 throw new IllegalArgumentException(e); 197 } 198 return this; 199 } 200 201 /** 202 * @return the number of intents added so far. 203 */ 204 public int getIntentCount() { 205 return mIntents.size(); 206 } 207 208 /** 209 * Get the intent at the specified index. 210 * Useful if you need to modify the flags or extras of an intent that was previously added, 211 * for example with {@link #addParentStack(Activity)}. 212 * 213 * @param index Index from 0-getIntentCount() 214 * @return the intent at position index 215 * 216 * @deprecated Renamed to editIntentAt to better reflect intended usage 217 */ 218 public Intent getIntent(int index) { 219 return editIntentAt(index); 220 } 221 222 /** 223 * Return the intent at the specified index for modification. 224 * Useful if you need to modify the flags or extras of an intent that was previously added, 225 * for example with {@link #addParentStack(Activity)}. 226 * 227 * @param index Index from 0-getIntentCount() 228 * @return the intent at position index 229 */ 230 public Intent editIntentAt(int index) { 231 return mIntents.get(index); 232 } 233 234 /** 235 * @deprecated Use editIntentAt instead 236 */ 237 public Iterator<Intent> iterator() { 238 return mIntents.iterator(); 239 } 240 241 /** 242 * Start the task stack constructed by this builder. The Context used to obtain 243 * this builder must be an Activity. 244 * 245 * <p>On devices that do not support API level 11 or higher the topmost activity 246 * will be started as a new task. On devices that do support API level 11 or higher 247 * the new task stack will be created in its entirety.</p> 248 */ 249 public void startActivities() { 250 startActivities(null); 251 } 252 253 /** 254 * Start the task stack constructed by this builder. The Context used to obtain 255 * this builder must be an Activity. 256 * 257 * <p>On devices that do not support API level 11 or higher the topmost activity 258 * will be started as a new task. On devices that do support API level 11 or higher 259 * the new task stack will be created in its entirety.</p> 260 * 261 * @param options Additional options for how the Activity should be started. 262 * See {@link android.content.Context#startActivity(Intent, Bundle) 263 */ 264 public void startActivities(Bundle options) { 265 if (mIntents.isEmpty()) { 266 throw new IllegalStateException( 267 "No intents added to TaskStackBuilder; cannot startActivities"); 268 } 269 270 Intent[] intents = mIntents.toArray(new Intent[mIntents.size()]); 271 intents[0].addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 272 IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | 273 IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); 274 if (!ActivityCompat.startActivities((Activity) mSourceContext, intents, options)) { 275 Intent topIntent = intents[intents.length - 1]; 276 topIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); 277 mSourceContext.startActivity(topIntent); 278 } 279 } 280 281 /** 282 * Obtain a {@link PendingIntent} for launching the task constructed by this builder so far. 283 * 284 * @param requestCode Private request code for the sender 285 * @param flags May be {@link PendingIntent#FLAG_ONE_SHOT}, 286 * {@link PendingIntent#FLAG_NO_CREATE}, {@link PendingIntent#FLAG_CANCEL_CURRENT}, 287 * {@link PendingIntent#FLAG_UPDATE_CURRENT}, or any of the flags supported by 288 * {@link Intent#fillIn(Intent, int)} to control which unspecified parts of the 289 * intent that can be supplied when the actual send happens. 290 * @return The obtained PendingIntent 291 */ 292 public PendingIntent getPendingIntent(int requestCode, int flags) { 293 return getPendingIntent(requestCode, flags, null); 294 } 295 296 /** 297 * Obtain a {@link PendingIntent} for launching the task constructed by this builder so far. 298 * 299 * @param requestCode Private request code for the sender 300 * @param flags May be {@link PendingIntent#FLAG_ONE_SHOT}, 301 * {@link PendingIntent#FLAG_NO_CREATE}, {@link PendingIntent#FLAG_CANCEL_CURRENT}, 302 * {@link PendingIntent#FLAG_UPDATE_CURRENT}, or any of the flags supported by 303 * {@link Intent#fillIn(Intent, int)} to control which unspecified parts of the 304 * intent that can be supplied when the actual send happens. 305 * @param options Additional options for how the Activity should be started. 306 * See {@link android.content.Context#startActivity(Intent, Bundle) 307 * @return The obtained PendingIntent 308 */ 309 public PendingIntent getPendingIntent(int requestCode, int flags, Bundle options) { 310 if (mIntents.isEmpty()) { 311 throw new IllegalStateException( 312 "No intents added to TaskStackBuilder; cannot getPendingIntent"); 313 } 314 315 Intent[] intents = mIntents.toArray(new Intent[mIntents.size()]); 316 intents[0].addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 317 IntentCompat.FLAG_ACTIVITY_CLEAR_TASK | 318 IntentCompat.FLAG_ACTIVITY_TASK_ON_HOME); 319 return IMPL.getPendingIntent(mSourceContext, intents, requestCode, flags, options); 320 } 321 322 /** 323 * Return an array containing the intents added to this builder. The intent at the 324 * root of the task stack will appear as the first item in the array and the 325 * intent at the top of the stack will appear as the last item. 326 * 327 * @return An array containing the intents added to this builder. 328 */ 329 public Intent[] getIntents() { 330 return mIntents.toArray(new Intent[mIntents.size()]); 331 } 332} 333