1package android.app; 2 3import android.annotation.AnimatorRes; 4import android.annotation.IdRes; 5import android.annotation.IntDef; 6import android.annotation.Nullable; 7import android.annotation.StringRes; 8import android.annotation.StyleRes; 9import android.view.View; 10 11import java.lang.annotation.Retention; 12import java.lang.annotation.RetentionPolicy; 13 14/** 15 * API for performing a set of Fragment operations. 16 * 17 * <div class="special reference"> 18 * <h3>Developer Guides</h3> 19 * <p>For more information about using fragments, read the 20 * <a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p> 21 * </div> 22 */ 23public abstract class FragmentTransaction { 24 /** 25 * Calls {@link #add(int, Fragment, String)} with a 0 containerViewId. 26 */ 27 public abstract FragmentTransaction add(Fragment fragment, String tag); 28 29 /** 30 * Calls {@link #add(int, Fragment, String)} with a null tag. 31 */ 32 public abstract FragmentTransaction add(@IdRes int containerViewId, Fragment fragment); 33 34 /** 35 * Add a fragment to the activity state. This fragment may optionally 36 * also have its view (if {@link Fragment#onCreateView Fragment.onCreateView} 37 * returns non-null) inserted into a container view of the activity. 38 * 39 * @param containerViewId Optional identifier of the container this fragment is 40 * to be placed in. If 0, it will not be placed in a container. 41 * @param fragment The fragment to be added. This fragment must not already 42 * be added to the activity. 43 * @param tag Optional tag name for the fragment, to later retrieve the 44 * fragment with {@link FragmentManager#findFragmentByTag(String) 45 * FragmentManager.findFragmentByTag(String)}. 46 * 47 * @return Returns the same FragmentTransaction instance. 48 */ 49 public abstract FragmentTransaction add(@IdRes int containerViewId, Fragment fragment, 50 String tag); 51 52 /** 53 * Calls {@link #replace(int, Fragment, String)} with a null tag. 54 */ 55 public abstract FragmentTransaction replace(@IdRes int containerViewId, Fragment fragment); 56 57 /** 58 * Replace an existing fragment that was added to a container. This is 59 * essentially the same as calling {@link #remove(Fragment)} for all 60 * currently added fragments that were added with the same containerViewId 61 * and then {@link #add(int, Fragment, String)} with the same arguments 62 * given here. 63 * 64 * @param containerViewId Identifier of the container whose fragment(s) are 65 * to be replaced. 66 * @param fragment The new fragment to place in the container. 67 * @param tag Optional tag name for the fragment, to later retrieve the 68 * fragment with {@link FragmentManager#findFragmentByTag(String) 69 * FragmentManager.findFragmentByTag(String)}. 70 * 71 * @return Returns the same FragmentTransaction instance. 72 */ 73 public abstract FragmentTransaction replace(@IdRes int containerViewId, Fragment fragment, 74 String tag); 75 76 /** 77 * Remove an existing fragment. If it was added to a container, its view 78 * is also removed from that container. 79 * 80 * @param fragment The fragment to be removed. 81 * 82 * @return Returns the same FragmentTransaction instance. 83 */ 84 public abstract FragmentTransaction remove(Fragment fragment); 85 86 /** 87 * Hides an existing fragment. This is only relevant for fragments whose 88 * views have been added to a container, as this will cause the view to 89 * be hidden. 90 * 91 * @param fragment The fragment to be hidden. 92 * 93 * @return Returns the same FragmentTransaction instance. 94 */ 95 public abstract FragmentTransaction hide(Fragment fragment); 96 97 /** 98 * Shows a previously hidden fragment. This is only relevant for fragments whose 99 * views have been added to a container, as this will cause the view to 100 * be shown. 101 * 102 * @param fragment The fragment to be shown. 103 * 104 * @return Returns the same FragmentTransaction instance. 105 */ 106 public abstract FragmentTransaction show(Fragment fragment); 107 108 /** 109 * Detach the given fragment from the UI. This is the same state as 110 * when it is put on the back stack: the fragment is removed from 111 * the UI, however its state is still being actively managed by the 112 * fragment manager. When going into this state its view hierarchy 113 * is destroyed. 114 * 115 * @param fragment The fragment to be detached. 116 * 117 * @return Returns the same FragmentTransaction instance. 118 */ 119 public abstract FragmentTransaction detach(Fragment fragment); 120 121 /** 122 * Re-attach a fragment after it had previously been detached from 123 * the UI with {@link #detach(Fragment)}. This 124 * causes its view hierarchy to be re-created, attached to the UI, 125 * and displayed. 126 * 127 * @param fragment The fragment to be attached. 128 * 129 * @return Returns the same FragmentTransaction instance. 130 */ 131 public abstract FragmentTransaction attach(Fragment fragment); 132 133 /** 134 * @return <code>true</code> if this transaction contains no operations, 135 * <code>false</code> otherwise. 136 */ 137 public abstract boolean isEmpty(); 138 139 /** 140 * Bit mask that is set for all enter transitions. 141 */ 142 public static final int TRANSIT_ENTER_MASK = 0x1000; 143 144 /** 145 * Bit mask that is set for all exit transitions. 146 */ 147 public static final int TRANSIT_EXIT_MASK = 0x2000; 148 149 /** Not set up for a transition. */ 150 public static final int TRANSIT_UNSET = -1; 151 /** No animation for transition. */ 152 public static final int TRANSIT_NONE = 0; 153 /** Fragment is being added onto the stack */ 154 public static final int TRANSIT_FRAGMENT_OPEN = 1 | TRANSIT_ENTER_MASK; 155 /** Fragment is being removed from the stack */ 156 public static final int TRANSIT_FRAGMENT_CLOSE = 2 | TRANSIT_EXIT_MASK; 157 /** Fragment should simply fade in or out; that is, no strong navigation associated 158 * with it except that it is appearing or disappearing for some reason. */ 159 public static final int TRANSIT_FRAGMENT_FADE = 3 | TRANSIT_ENTER_MASK; 160 161 /** @hide */ 162 @IntDef({TRANSIT_NONE, TRANSIT_FRAGMENT_OPEN, TRANSIT_FRAGMENT_CLOSE, TRANSIT_FRAGMENT_FADE}) 163 @Retention(RetentionPolicy.SOURCE) 164 public @interface Transit {} 165 166 /** 167 * Set specific animation resources to run for the fragments that are 168 * entering and exiting in this transaction. These animations will not be 169 * played when popping the back stack. 170 */ 171 public abstract FragmentTransaction setCustomAnimations(@AnimatorRes int enter, 172 @AnimatorRes int exit); 173 174 /** 175 * Set specific animation resources to run for the fragments that are 176 * entering and exiting in this transaction. The <code>popEnter</code> 177 * and <code>popExit</code> animations will be played for enter/exit 178 * operations specifically when popping the back stack. 179 */ 180 public abstract FragmentTransaction setCustomAnimations(@AnimatorRes int enter, 181 @AnimatorRes int exit, @AnimatorRes int popEnter, @AnimatorRes int popExit); 182 183 /** 184 * Select a standard transition animation for this transaction. May be 185 * one of {@link #TRANSIT_NONE}, {@link #TRANSIT_FRAGMENT_OPEN}, 186 * {@link #TRANSIT_FRAGMENT_CLOSE}, or {@link #TRANSIT_FRAGMENT_FADE}. 187 */ 188 public abstract FragmentTransaction setTransition(@Transit int transit); 189 190 /** 191 * Used with to map a View from a removed or hidden Fragment to a View from a shown 192 * or added Fragment. 193 * @param sharedElement A View in a disappearing Fragment to match with a View in an 194 * appearing Fragment. 195 * @param name The transitionName for a View in an appearing Fragment to match to the shared 196 * element. 197 */ 198 public abstract FragmentTransaction addSharedElement(View sharedElement, String name); 199 200 /** 201 * Set a custom style resource that will be used for resolving transit 202 * animations. 203 */ 204 public abstract FragmentTransaction setTransitionStyle(@StyleRes int styleRes); 205 206 /** 207 * Add this transaction to the back stack. This means that the transaction 208 * will be remembered after it is committed, and will reverse its operation 209 * when later popped off the stack. 210 * 211 * @param name An optional name for this back stack state, or null. 212 */ 213 public abstract FragmentTransaction addToBackStack(@Nullable String name); 214 215 /** 216 * Returns true if this FragmentTransaction is allowed to be added to the back 217 * stack. If this method would return false, {@link #addToBackStack(String)} 218 * will throw {@link IllegalStateException}. 219 * 220 * @return True if {@link #addToBackStack(String)} is permitted on this transaction. 221 */ 222 public abstract boolean isAddToBackStackAllowed(); 223 224 /** 225 * Disallow calls to {@link #addToBackStack(String)}. Any future calls to 226 * addToBackStack will throw {@link IllegalStateException}. If addToBackStack 227 * has already been called, this method will throw IllegalStateException. 228 */ 229 public abstract FragmentTransaction disallowAddToBackStack(); 230 231 /** 232 * Set the full title to show as a bread crumb when this transaction 233 * is on the back stack, as used by {@link FragmentBreadCrumbs}. 234 * 235 * @param res A string resource containing the title. 236 */ 237 public abstract FragmentTransaction setBreadCrumbTitle(@StringRes int res); 238 239 /** 240 * Like {@link #setBreadCrumbTitle(int)} but taking a raw string; this 241 * method is <em>not</em> recommended, as the string can not be changed 242 * later if the locale changes. 243 */ 244 public abstract FragmentTransaction setBreadCrumbTitle(CharSequence text); 245 246 /** 247 * Set the short title to show as a bread crumb when this transaction 248 * is on the back stack, as used by {@link FragmentBreadCrumbs}. 249 * 250 * @param res A string resource containing the title. 251 */ 252 public abstract FragmentTransaction setBreadCrumbShortTitle(@StringRes int res); 253 254 /** 255 * Like {@link #setBreadCrumbShortTitle(int)} but taking a raw string; this 256 * method is <em>not</em> recommended, as the string can not be changed 257 * later if the locale changes. 258 */ 259 public abstract FragmentTransaction setBreadCrumbShortTitle(CharSequence text); 260 261 /** 262 * Schedules a commit of this transaction. The commit does 263 * not happen immediately; it will be scheduled as work on the main thread 264 * to be done the next time that thread is ready. 265 * 266 * <p class="note">A transaction can only be committed with this method 267 * prior to its containing activity saving its state. If the commit is 268 * attempted after that point, an exception will be thrown. This is 269 * because the state after the commit can be lost if the activity needs to 270 * be restored from its state. See {@link #commitAllowingStateLoss()} for 271 * situations where it may be okay to lose the commit.</p> 272 * 273 * @return Returns the identifier of this transaction's back stack entry, 274 * if {@link #addToBackStack(String)} had been called. Otherwise, returns 275 * a negative number. 276 */ 277 public abstract int commit(); 278 279 /** 280 * Like {@link #commit} but allows the commit to be executed after an 281 * activity's state is saved. This is dangerous because the commit can 282 * be lost if the activity needs to later be restored from its state, so 283 * this should only be used for cases where it is okay for the UI state 284 * to change unexpectedly on the user. 285 */ 286 public abstract int commitAllowingStateLoss(); 287 288 /** 289 * Commits this transaction synchronously. Any added fragments will be 290 * initialized and brought completely to the lifecycle state of their host 291 * and any removed fragments will be torn down accordingly before this 292 * call returns. Committing a transaction in this way allows fragments 293 * to be added as dedicated, encapsulated components that monitor the 294 * lifecycle state of their host while providing firmer ordering guarantees 295 * around when those fragments are fully initialized and ready. Fragments 296 * that manage views will have those views created and attached. 297 * 298 * <p>Calling <code>commitNow</code> is preferable to calling 299 * {@link #commit()} followed by {@link FragmentManager#executePendingTransactions()} 300 * as the latter will have the side effect of attempting to commit <em>all</em> 301 * currently pending transactions whether that is the desired behavior 302 * or not.</p> 303 * 304 * <p>Transactions committed in this way may not be added to the 305 * FragmentManager's back stack, as doing so would break other expected 306 * ordering guarantees for other asynchronously committed transactions. 307 * This method will throw {@link IllegalStateException} if the transaction 308 * previously requested to be added to the back stack with 309 * {@link #addToBackStack(String)}.</p> 310 * 311 * <p class="note">A transaction can only be committed with this method 312 * prior to its containing activity saving its state. If the commit is 313 * attempted after that point, an exception will be thrown. This is 314 * because the state after the commit can be lost if the activity needs to 315 * be restored from its state. See {@link #commitAllowingStateLoss()} for 316 * situations where it may be okay to lose the commit.</p> 317 */ 318 public abstract void commitNow(); 319 320 /** 321 * Like {@link #commitNow} but allows the commit to be executed after an 322 * activity's state is saved. This is dangerous because the commit can 323 * be lost if the activity needs to later be restored from its state, so 324 * this should only be used for cases where it is okay for the UI state 325 * to change unexpectedly on the user. 326 */ 327 public abstract void commitNowAllowingStateLoss(); 328} 329