FragmentTransaction.java revision ac5fe7c617c66850fff75a9fce9979c6e5674b0f
1/* 2 * Copyright 2018 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 androidx.fragment.app; 18 19import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP; 20 21import android.os.Bundle; 22import androidx.annotation.AnimRes; 23import androidx.annotation.AnimatorRes; 24import androidx.annotation.IdRes; 25import androidx.annotation.IntDef; 26import androidx.annotation.Nullable; 27import androidx.annotation.RestrictTo; 28import androidx.annotation.StringRes; 29import androidx.annotation.StyleRes; 30import android.view.View; 31 32import java.lang.annotation.Retention; 33import java.lang.annotation.RetentionPolicy; 34 35/** 36 * Static library support version of the framework's {@link android.app.FragmentTransaction}. 37 * Used to write apps that run on platforms prior to Android 3.0. When running 38 * on Android 3.0 or above, this implementation is still used; it does not try 39 * to switch to the framework's implementation. See the framework SDK 40 * documentation for a class overview. 41 */ 42public abstract class FragmentTransaction { 43 /** 44 * Calls {@link #add(int, Fragment, String)} with a 0 containerViewId. 45 */ 46 public abstract FragmentTransaction add(Fragment fragment, String tag); 47 48 /** 49 * Calls {@link #add(int, Fragment, String)} with a null tag. 50 */ 51 public abstract FragmentTransaction add(@IdRes int containerViewId, Fragment fragment); 52 53 /** 54 * Add a fragment to the activity state. This fragment may optionally 55 * also have its view (if {@link Fragment#onCreateView Fragment.onCreateView} 56 * returns non-null) into a container view of the activity. 57 * 58 * @param containerViewId Optional identifier of the container this fragment is 59 * to be placed in. If 0, it will not be placed in a container. 60 * @param fragment The fragment to be added. This fragment must not already 61 * be added to the activity. 62 * @param tag Optional tag name for the fragment, to later retrieve the 63 * fragment with {@link FragmentManager#findFragmentByTag(String) 64 * FragmentManager.findFragmentByTag(String)}. 65 * 66 * @return Returns the same FragmentTransaction instance. 67 */ 68 public abstract FragmentTransaction add(@IdRes int containerViewId, Fragment fragment, 69 @Nullable String tag); 70 71 /** 72 * Calls {@link #replace(int, Fragment, String)} with a null tag. 73 */ 74 public abstract FragmentTransaction replace(@IdRes int containerViewId, Fragment fragment); 75 76 /** 77 * Replace an existing fragment that was added to a container. This is 78 * essentially the same as calling {@link #remove(Fragment)} for all 79 * currently added fragments that were added with the same containerViewId 80 * and then {@link #add(int, Fragment, String)} with the same arguments 81 * given here. 82 * 83 * @param containerViewId Identifier of the container whose fragment(s) are 84 * to be replaced. 85 * @param fragment The new fragment to place in the container. 86 * @param tag Optional tag name for the fragment, to later retrieve the 87 * fragment with {@link FragmentManager#findFragmentByTag(String) 88 * FragmentManager.findFragmentByTag(String)}. 89 * 90 * @return Returns the same FragmentTransaction instance. 91 */ 92 public abstract FragmentTransaction replace(@IdRes int containerViewId, Fragment fragment, 93 @Nullable String tag); 94 95 /** 96 * Remove an existing fragment. If it was added to a container, its view 97 * is also removed from that container. 98 * 99 * @param fragment The fragment to be removed. 100 * 101 * @return Returns the same FragmentTransaction instance. 102 */ 103 public abstract FragmentTransaction remove(Fragment fragment); 104 105 /** 106 * Hides an existing fragment. This is only relevant for fragments whose 107 * views have been added to a container, as this will cause the view to 108 * be hidden. 109 * 110 * @param fragment The fragment to be hidden. 111 * 112 * @return Returns the same FragmentTransaction instance. 113 */ 114 public abstract FragmentTransaction hide(Fragment fragment); 115 116 /** 117 * Shows a previously hidden fragment. This is only relevant for fragments whose 118 * views have been added to a container, as this will cause the view to 119 * be shown. 120 * 121 * @param fragment The fragment to be shown. 122 * 123 * @return Returns the same FragmentTransaction instance. 124 */ 125 public abstract FragmentTransaction show(Fragment fragment); 126 127 /** 128 * Detach the given fragment from the UI. This is the same state as 129 * when it is put on the back stack: the fragment is removed from 130 * the UI, however its state is still being actively managed by the 131 * fragment manager. When going into this state its view hierarchy 132 * is destroyed. 133 * 134 * @param fragment The fragment to be detached. 135 * 136 * @return Returns the same FragmentTransaction instance. 137 */ 138 public abstract FragmentTransaction detach(Fragment fragment); 139 140 /** 141 * Re-attach a fragment after it had previously been detached from 142 * the UI with {@link #detach(Fragment)}. This 143 * causes its view hierarchy to be re-created, attached to the UI, 144 * and displayed. 145 * 146 * @param fragment The fragment to be attached. 147 * 148 * @return Returns the same FragmentTransaction instance. 149 */ 150 public abstract FragmentTransaction attach(Fragment fragment); 151 152 /** 153 * Set a currently active fragment in this FragmentManager as the primary navigation fragment. 154 * 155 * <p>The primary navigation fragment's 156 * {@link Fragment#getChildFragmentManager() child FragmentManager} will be called first 157 * to process delegated navigation actions such as {@link FragmentManager#popBackStack()} 158 * if no ID or transaction name is provided to pop to. Navigation operations outside of the 159 * fragment system may choose to delegate those actions to the primary navigation fragment 160 * as returned by {@link FragmentManager#getPrimaryNavigationFragment()}.</p> 161 * 162 * <p>The fragment provided must currently be added to the FragmentManager to be set as 163 * a primary navigation fragment, or previously added as part of this transaction.</p> 164 * 165 * @param fragment the fragment to set as the primary navigation fragment 166 * @return the same FragmentTransaction instance 167 */ 168 public abstract FragmentTransaction setPrimaryNavigationFragment(Fragment fragment); 169 170 /** 171 * @return <code>true</code> if this transaction contains no operations, 172 * <code>false</code> otherwise. 173 */ 174 public abstract boolean isEmpty(); 175 176 /** 177 * Bit mask that is set for all enter transitions. 178 */ 179 public static final int TRANSIT_ENTER_MASK = 0x1000; 180 181 /** 182 * Bit mask that is set for all exit transitions. 183 */ 184 public static final int TRANSIT_EXIT_MASK = 0x2000; 185 186 /** @hide */ 187 @RestrictTo(LIBRARY_GROUP) 188 @IntDef({TRANSIT_NONE, TRANSIT_FRAGMENT_OPEN, TRANSIT_FRAGMENT_CLOSE, TRANSIT_FRAGMENT_FADE}) 189 @Retention(RetentionPolicy.SOURCE) 190 private @interface Transit {} 191 192 /** Not set up for a transition. */ 193 public static final int TRANSIT_UNSET = -1; 194 /** No animation for transition. */ 195 public static final int TRANSIT_NONE = 0; 196 /** Fragment is being added onto the stack */ 197 public static final int TRANSIT_FRAGMENT_OPEN = 1 | TRANSIT_ENTER_MASK; 198 /** Fragment is being removed from the stack */ 199 public static final int TRANSIT_FRAGMENT_CLOSE = 2 | TRANSIT_EXIT_MASK; 200 /** Fragment should simply fade in or out; that is, no strong navigation associated 201 * with it except that it is appearing or disappearing for some reason. */ 202 public static final int TRANSIT_FRAGMENT_FADE = 3 | TRANSIT_ENTER_MASK; 203 204 /** 205 * Set specific animation resources to run for the fragments that are 206 * entering and exiting in this transaction. These animations will not be 207 * played when popping the back stack. 208 * 209 * @param enter An animation or animator resource ID used for the enter animation on the 210 * view of the fragment being added or attached. 211 * @param exit An animation or animator resource ID used for the exit animation on the 212 * view of the fragment being removed or detached. 213 */ 214 public abstract FragmentTransaction setCustomAnimations(@AnimatorRes @AnimRes int enter, 215 @AnimatorRes @AnimRes int exit); 216 217 /** 218 * Set specific animation resources to run for the fragments that are 219 * entering and exiting in this transaction. The <code>popEnter</code> 220 * and <code>popExit</code> animations will be played for enter/exit 221 * operations specifically when popping the back stack. 222 * 223 * @param enter An animation or animator resource ID used for the enter animation on the 224 * view of the fragment being added or attached. 225 * @param exit An animation or animator resource ID used for the exit animation on the 226 * view of the fragment being removed or detached. 227 * @param popEnter An animation or animator resource ID used for the enter animation on the 228 * view of the fragment being readded or reattached caused by 229 * {@link FragmentManager#popBackStack()} or similar methods. 230 * @param popExit An animation or animator resource ID used for the enter animation on the 231 * view of the fragment being removed or detached caused by 232 * {@link FragmentManager#popBackStack()} or similar methods. 233 */ 234 public abstract FragmentTransaction setCustomAnimations(@AnimatorRes @AnimRes int enter, 235 @AnimatorRes @AnimRes int exit, @AnimatorRes @AnimRes int popEnter, 236 @AnimatorRes @AnimRes int popExit); 237 238 /** 239 * Used with custom Transitions to map a View from a removed or hidden 240 * Fragment to a View from a shown or added Fragment. 241 * <var>sharedElement</var> must have a unique transitionName in the View hierarchy. 242 * 243 * @param sharedElement A View in a disappearing Fragment to match with a View in an 244 * appearing Fragment. 245 * @param name The transitionName for a View in an appearing Fragment to match to the shared 246 * element. 247 * @see Fragment#setSharedElementReturnTransition(Object) 248 * @see Fragment#setSharedElementEnterTransition(Object) 249 */ 250 public abstract FragmentTransaction addSharedElement(View sharedElement, String name); 251 252 /** 253 * Select a standard transition animation for this transaction. May be 254 * one of {@link #TRANSIT_NONE}, {@link #TRANSIT_FRAGMENT_OPEN}, 255 * {@link #TRANSIT_FRAGMENT_CLOSE}, or {@link #TRANSIT_FRAGMENT_FADE}. 256 */ 257 public abstract FragmentTransaction setTransition(@Transit int transit); 258 259 /** 260 * Set a custom style resource that will be used for resolving transit 261 * animations. 262 */ 263 public abstract FragmentTransaction setTransitionStyle(@StyleRes int styleRes); 264 265 /** 266 * Add this transaction to the back stack. This means that the transaction 267 * will be remembered after it is committed, and will reverse its operation 268 * when later popped off the stack. 269 * 270 * @param name An optional name for this back stack state, or null. 271 */ 272 public abstract FragmentTransaction addToBackStack(@Nullable String name); 273 274 /** 275 * Returns true if this FragmentTransaction is allowed to be added to the back 276 * stack. If this method would return false, {@link #addToBackStack(String)} 277 * will throw {@link IllegalStateException}. 278 * 279 * @return True if {@link #addToBackStack(String)} is permitted on this transaction. 280 */ 281 public abstract boolean isAddToBackStackAllowed(); 282 283 /** 284 * Disallow calls to {@link #addToBackStack(String)}. Any future calls to 285 * addToBackStack will throw {@link IllegalStateException}. If addToBackStack 286 * has already been called, this method will throw IllegalStateException. 287 */ 288 public abstract FragmentTransaction disallowAddToBackStack(); 289 290 /** 291 * Set the full title to show as a bread crumb when this transaction 292 * is on the back stack. 293 * 294 * @param res A string resource containing the title. 295 */ 296 public abstract FragmentTransaction setBreadCrumbTitle(@StringRes int res); 297 298 /** 299 * Like {@link #setBreadCrumbTitle(int)} but taking a raw string; this 300 * method is <em>not</em> recommended, as the string can not be changed 301 * later if the locale changes. 302 */ 303 public abstract FragmentTransaction setBreadCrumbTitle(CharSequence text); 304 305 /** 306 * Set the short title to show as a bread crumb when this transaction 307 * is on the back stack. 308 * 309 * @param res A string resource containing the title. 310 */ 311 public abstract FragmentTransaction setBreadCrumbShortTitle(@StringRes int res); 312 313 /** 314 * Like {@link #setBreadCrumbShortTitle(int)} but taking a raw string; this 315 * method is <em>not</em> recommended, as the string can not be changed 316 * later if the locale changes. 317 */ 318 public abstract FragmentTransaction setBreadCrumbShortTitle(CharSequence text); 319 320 /** 321 * Sets whether or not to allow optimizing operations within and across 322 * transactions. This will remove redundant operations, eliminating 323 * operations that cancel. For example, if two transactions are executed 324 * together, one that adds a fragment A and the next replaces it with fragment B, 325 * the operations will cancel and only fragment B will be added. That means that 326 * fragment A may not go through the creation/destruction lifecycle. 327 * <p> 328 * The side effect of removing redundant operations is that fragments may have state changes 329 * out of the expected order. For example, one transaction adds fragment A, 330 * a second adds fragment B, then a third removes fragment A. Without removing the redundant 331 * operations, fragment B could expect that while it is being created, fragment A will also 332 * exist because fragment A will be removed after fragment B was added. 333 * With removing redundant operations, fragment B cannot expect fragment A to exist when 334 * it has been created because fragment A's add/remove will be optimized out. 335 * <p> 336 * It can also reorder the state changes of Fragments to allow for better Transitions. 337 * Added Fragments may have {@link Fragment#onCreate(Bundle)} called before replaced 338 * Fragments have {@link Fragment#onDestroy()} called. 339 * <p> 340 * {@link Fragment#postponeEnterTransition()} requires {@code setReorderingAllowed(true)}. 341 * <p> 342 * The default is {@code false}. 343 * 344 * @param reorderingAllowed {@code true} to enable optimizing out redundant operations 345 * or {@code false} to disable optimizing out redundant 346 * operations on this transaction. 347 */ 348 public abstract FragmentTransaction setReorderingAllowed(boolean reorderingAllowed); 349 350 /** 351 * @deprecated This has been renamed {@link #setReorderingAllowed(boolean)}. 352 */ 353 @Deprecated 354 public abstract FragmentTransaction setAllowOptimization(boolean allowOptimization); 355 356 /** 357 * Add a Runnable to this transaction that will be run after this transaction has 358 * been committed. If fragment transactions are {@link #setReorderingAllowed(boolean) optimized} 359 * this may be after other subsequent fragment operations have also taken place, or operations 360 * in this transaction may have been optimized out due to the presence of a subsequent 361 * fragment transaction in the batch. 362 * 363 * <p>If a transaction is committed using {@link #commitAllowingStateLoss()} this runnable 364 * may be executed when the FragmentManager is in a state where new transactions may not 365 * be committed without allowing state loss.</p> 366 * 367 * <p><code>runOnCommit</code> may not be used with transactions 368 * {@link #addToBackStack(String) added to the back stack} as Runnables cannot be persisted 369 * with back stack state. {@link IllegalStateException} will be thrown if 370 * {@link #addToBackStack(String)} has been previously called for this transaction 371 * or if it is called after a call to <code>runOnCommit</code>.</p> 372 * 373 * @param runnable Runnable to add 374 * @return this FragmentTransaction 375 * @throws IllegalStateException if {@link #addToBackStack(String)} has been called 376 */ 377 public abstract FragmentTransaction runOnCommit(Runnable runnable); 378 379 /** 380 * Schedules a commit of this transaction. The commit does 381 * not happen immediately; it will be scheduled as work on the main thread 382 * to be done the next time that thread is ready. 383 * 384 * <p class="note">A transaction can only be committed with this method 385 * prior to its containing activity saving its state. If the commit is 386 * attempted after that point, an exception will be thrown. This is 387 * because the state after the commit can be lost if the activity needs to 388 * be restored from its state. See {@link #commitAllowingStateLoss()} for 389 * situations where it may be okay to lose the commit.</p> 390 * 391 * @return Returns the identifier of this transaction's back stack entry, 392 * if {@link #addToBackStack(String)} had been called. Otherwise, returns 393 * a negative number. 394 */ 395 public abstract int commit(); 396 397 /** 398 * Like {@link #commit} but allows the commit to be executed after an 399 * activity's state is saved. This is dangerous because the commit can 400 * be lost if the activity needs to later be restored from its state, so 401 * this should only be used for cases where it is okay for the UI state 402 * to change unexpectedly on the user. 403 */ 404 public abstract int commitAllowingStateLoss(); 405 406 /** 407 * Commits this transaction synchronously. Any added fragments will be 408 * initialized and brought completely to the lifecycle state of their host 409 * and any removed fragments will be torn down accordingly before this 410 * call returns. Committing a transaction in this way allows fragments 411 * to be added as dedicated, encapsulated components that monitor the 412 * lifecycle state of their host while providing firmer ordering guarantees 413 * around when those fragments are fully initialized and ready. Fragments 414 * that manage views will have those views created and attached. 415 * 416 * <p>Calling <code>commitNow</code> is preferable to calling 417 * {@link #commit()} followed by {@link FragmentManager#executePendingTransactions()} 418 * as the latter will have the side effect of attempting to commit <em>all</em> 419 * currently pending transactions whether that is the desired behavior 420 * or not.</p> 421 * 422 * <p>Transactions committed in this way may not be added to the 423 * FragmentManager's back stack, as doing so would break other expected 424 * ordering guarantees for other asynchronously committed transactions. 425 * This method will throw {@link IllegalStateException} if the transaction 426 * previously requested to be added to the back stack with 427 * {@link #addToBackStack(String)}.</p> 428 * 429 * <p class="note">A transaction can only be committed with this method 430 * prior to its containing activity saving its state. If the commit is 431 * attempted after that point, an exception will be thrown. This is 432 * because the state after the commit can be lost if the activity needs to 433 * be restored from its state. See {@link #commitAllowingStateLoss()} for 434 * situations where it may be okay to lose the commit.</p> 435 */ 436 public abstract void commitNow(); 437 438 /** 439 * Like {@link #commitNow} but allows the commit to be executed after an 440 * activity's state is saved. This is dangerous because the commit can 441 * be lost if the activity needs to later be restored from its state, so 442 * this should only be used for cases where it is okay for the UI state 443 * to change unexpectedly on the user. 444 */ 445 public abstract void commitNowAllowingStateLoss(); 446} 447