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