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