{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
public abstract class FragmentTransaction
Static library support version of the framework's android.app.FragmentTransaction. Used to write apps that run on platforms prior to Android 3.0. When running on Android 3.0 or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework SDK documentation for a class overview.
Constants |
|
---|---|
static final @NonNull int |
Bit mask that is set for all enter transitions. |
static final @NonNull int |
Bit mask that is set for all exit transitions. |
static final @NonNull int |
Fragment is being removed from the stack |
static final @NonNull int |
Fragment should simply fade in or out; that is, no strong navigation associated with it except that it is appearing or disappearing for some reason. |
static final @NonNull int |
Fragment is being added onto the stack |
static final @NonNull int |
No animation for transition. |
static final @NonNull int |
Not set up for a transition. |
Public constructors |
|
---|---|
This method is deprecated. You should not instantiate a FragmentTransaction except via |
Public methods |
|
---|---|
final @NonNull FragmentTransaction |
Calls |
@NonNull FragmentTransaction |
Calls |
final @NonNull FragmentTransaction |
add( Calls |
@NonNull FragmentTransaction |
Calls |
final @NonNull FragmentTransaction |
add( Add a fragment to the activity state. |
@NonNull FragmentTransaction |
Add a fragment to the activity state. |
@NonNull FragmentTransaction |
addSharedElement(@NonNull View sharedElement, @NonNull String name) Used with custom Transitions to map a View from a removed or hidden Fragment to a View from a shown or added Fragment. |
@NonNull FragmentTransaction |
addToBackStack(@Nullable String name) Add this transaction to the back stack. |
@NonNull FragmentTransaction |
Re-attach a fragment after it had previously been detached from the UI with |
abstract @NonNull int |
commit() Schedules a commit of this transaction. |
abstract @NonNull int |
Like |
abstract @NonNull void |
Commits this transaction synchronously. |
abstract @NonNull void |
Like |
@NonNull FragmentTransaction |
Detach the given fragment from the UI. |
@NonNull FragmentTransaction |
Disallow calls to |
@NonNull FragmentTransaction |
Hides an existing fragment. |
@NonNull boolean |
Returns true if this FragmentTransaction is allowed to be added to the back stack. |
@NonNull boolean |
isEmpty() |
@NonNull FragmentTransaction |
Remove an existing fragment. |
final @NonNull FragmentTransaction |
replace( Calls |
@NonNull FragmentTransaction |
Calls |
final @NonNull FragmentTransaction |
replace( Replace an existing fragment that was added to a container. |
@NonNull FragmentTransaction |
Replace an existing fragment that was added to a container. |
@NonNull FragmentTransaction |
runOnCommit(@NonNull Runnable runnable) Add a Runnable to this transaction that will be run after this transaction has been committed. |
@NonNull FragmentTransaction |
This method is deprecated. This has been renamed |
@NonNull FragmentTransaction |
This method is deprecated. Store breadcrumb short titles separately from fragment transactions. |
@NonNull FragmentTransaction |
This method is deprecated. Store breadcrumb short titles separately from fragment transactions. |
@NonNull FragmentTransaction |
This method is deprecated. Store breadcrumb titles separately from fragment transactions. |
@NonNull FragmentTransaction |
This method is deprecated. Store breadcrumb titles separately from fragment transactions. |
@NonNull FragmentTransaction |
setCustomAnimations(@NonNull int enter, @NonNull int exit) Set specific animation resources to run for the fragments that are entering and exiting in this transaction. |
@NonNull FragmentTransaction |
setCustomAnimations( Set specific animation resources to run for the fragments that are entering and exiting in this transaction. |
@NonNull FragmentTransaction |
setMaxLifecycle(@NonNull Fragment fragment, @NonNull State state) Set a ceiling for the state of an active fragment in this FragmentManager. |
@NonNull FragmentTransaction |
setPrimaryNavigationFragment(@Nullable Fragment fragment) Set a currently active fragment in this FragmentManager as the primary navigation fragment. |
@NonNull FragmentTransaction |
setReorderingAllowed(@NonNull boolean reorderingAllowed) Sets whether or not to allow optimizing operations within and across transactions. |
@NonNull FragmentTransaction |
setTransition(@NonNull int transition) Select a standard transition animation for this transaction. |
@NonNull FragmentTransaction |
This method is deprecated. The desired functionality never worked correctly. |
@NonNull FragmentTransaction |
Shows a previously hidden fragment. |
@NonNull
public static final @NonNull int TRANSIT_ENTER_MASK
Bit mask that is set for all enter transitions.
@NonNull
public static final @NonNull int TRANSIT_EXIT_MASK
Bit mask that is set for all exit transitions.
@NonNull
public static final @NonNull int TRANSIT_FRAGMENT_CLOSE
Fragment is being removed from the stack
@NonNull
public static final @NonNull int TRANSIT_FRAGMENT_FADE
Fragment should simply fade in or out; that is, no strong navigation associated with it except that it is appearing or disappearing for some reason.
@NonNull
public static final @NonNull int TRANSIT_FRAGMENT_OPEN
Fragment is being added onto the stack
@NonNull
public final FragmentTransaction add(
@NonNull Class<@NonNull Fragment> fragmentClass,
@Nullable Bundle args,
@Nullable String tag
)
Calls add
with a 0 containerViewId.
@NonNull
public FragmentTransaction add(@NonNull Fragment fragment, @Nullable String tag)
Calls add
with a 0 containerViewId.
@NonNull
public final FragmentTransaction add(
@NonNull int containerViewId,
@NonNull Class<@NonNull Fragment> fragmentClass,
@Nullable Bundle args
)
Calls add
with a null tag.
@NonNull
public FragmentTransaction add(@NonNull int containerViewId, @NonNull Fragment fragment)
Calls add
with a null tag.
@NonNull
public final FragmentTransaction add(
@NonNull int containerViewId,
@NonNull Class<@NonNull Fragment> fragmentClass,
@Nullable Bundle args,
@Nullable String tag
)
Add a fragment to the activity state. This fragment may optionally also have its view (if Fragment.onCreateView
returns non-null) into a container view of the activity.
Parameters | |
---|---|
@NonNull int containerViewId |
Optional identifier of the container this fragment is to be placed in. If 0, it will not be placed in a container. |
@NonNull Class<@NonNull Fragment> fragmentClass |
The fragment to be added, created via the |
@Nullable Bundle args |
Optional arguments to be set on the fragment. |
@Nullable String tag |
Optional tag name for the fragment, to later retrieve the fragment with |
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public FragmentTransaction add(
@NonNull int containerViewId,
@NonNull Fragment fragment,
@Nullable String tag
)
Add a fragment to the activity state. This fragment may optionally also have its view (if Fragment.onCreateView
returns non-null) into a container view of the activity.
Parameters | |
---|---|
@NonNull int containerViewId |
Optional identifier of the container this fragment is to be placed in. If 0, it will not be placed in a container. |
@NonNull Fragment fragment |
The fragment to be added. This fragment must not already be added to the activity. |
@Nullable String tag |
Optional tag name for the fragment, to later retrieve the fragment with |
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public FragmentTransaction addSharedElement(@NonNull View sharedElement, @NonNull String name)
Used with custom Transitions to map a View from a removed or hidden Fragment to a View from a shown or added Fragment. sharedElement must have a unique transitionName in the View hierarchy.
Parameters | |
---|---|
@NonNull View sharedElement |
A View in a disappearing Fragment to match with a View in an appearing Fragment. |
@NonNull String name |
The transitionName for a View in an appearing Fragment to match to the shared element. |
See also | |
---|---|
setSharedElementReturnTransition |
androidx.fragment.app.Fragment#setSharedElementReturnTransition(Object) |
setSharedElementEnterTransition |
androidx.fragment.app.Fragment#setSharedElementEnterTransition(Object) |
@NonNull
public FragmentTransaction addToBackStack(@Nullable String name)
Add this transaction to the back stack. This means that the transaction will be remembered after it is committed, and will reverse its operation when later popped off the stack.
setReorderingAllowed
must be set to true
in the same transaction as addToBackStack() to allow the pop of that transaction to be reordered.
@NonNull
public FragmentTransaction attach(@NonNull Fragment fragment)
Re-attach a fragment after it had previously been detached from the UI with detach
. This causes its view hierarchy to be re-created, attached to the UI, and displayed.
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public abstract int commit()
Schedules a commit of this transaction. The commit does not happen immediately; it will be scheduled as work on the main thread to be done the next time that thread is ready.
A transaction can only be committed with this method prior to its containing activity saving its state. If the commit is attempted after that point, an exception will be thrown. This is because the state after the commit can be lost if the activity needs to be restored from its state. See commitAllowingStateLoss
for situations where it may be okay to lose the commit.
Returns | |
---|---|
int |
Returns the identifier of this transaction's back stack entry, if |
@NonNull
public abstract int commitAllowingStateLoss()
Like commit
but allows the commit to be executed after an activity's state is saved. This is dangerous because the commit can be lost if the activity needs to later be restored from its state, so this should only be used for cases where it is okay for the UI state to change unexpectedly on the user.
@NonNull
public abstract void commitNow()
Commits this transaction synchronously. Any added fragments will be initialized and brought completely to the lifecycle state of their host and any removed fragments will be torn down accordingly before this call returns. Committing a transaction in this way allows fragments to be added as dedicated, encapsulated components that monitor the lifecycle state of their host while providing firmer ordering guarantees around when those fragments are fully initialized and ready. Fragments that manage views will have those views created and attached.
Calling commitNow
is preferable to calling commit
followed by FragmentManager#executePendingTransactions()
as the latter will have the side effect of attempting to commit allcurrently pending transactions whether that is the desired behavior or not.
Transactions committed in this way may not be added to the FragmentManager's back stack, as doing so would break other expected ordering guarantees for other asynchronously committed transactions. This method will throw IllegalStateException
if the transaction previously requested to be added to the back stack with addToBackStack
.
A transaction can only be committed with this method prior to its containing activity saving its state. If the commit is attempted after that point, an exception will be thrown. This is because the state after the commit can be lost if the activity needs to be restored from its state. See commitAllowingStateLoss
for situations where it may be okay to lose the commit.
@NonNull
public abstract void commitNowAllowingStateLoss()
Like commitNow
but allows the commit to be executed after an activity's state is saved. This is dangerous because the commit can be lost if the activity needs to later be restored from its state, so this should only be used for cases where it is okay for the UI state to change unexpectedly on the user.
@NonNull
public FragmentTransaction detach(@NonNull Fragment fragment)
Detach the given fragment from the UI. This is the same state as when it is put on the back stack: the fragment is removed from the UI, however its state is still being actively managed by the fragment manager. When going into this state its view hierarchy is destroyed.
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public FragmentTransaction disallowAddToBackStack()
Disallow calls to addToBackStack
. Any future calls to addToBackStack will throw IllegalStateException
. If addToBackStack has already been called, this method will throw IllegalStateException.
@NonNull
public FragmentTransaction hide(@NonNull Fragment fragment)
Hides an existing fragment. This is only relevant for fragments whose views have been added to a container, as this will cause the view to be hidden.
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public boolean isAddToBackStackAllowed()
Returns true if this FragmentTransaction is allowed to be added to the back stack. If this method would return false, addToBackStack
will throw IllegalStateException
.
Returns | |
---|---|
boolean |
True if |
@NonNull
public boolean isEmpty()
Returns | |
---|---|
boolean |
|
@NonNull
public FragmentTransaction remove(@NonNull Fragment fragment)
Remove an existing fragment. If it was added to a container, its view is also removed from that container.
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public final FragmentTransaction replace(
@NonNull int containerViewId,
@NonNull Class<@NonNull Fragment> fragmentClass,
@Nullable Bundle args
)
Calls replace
with a null tag.
@NonNull
public FragmentTransaction replace(@NonNull int containerViewId, @NonNull Fragment fragment)
Calls replace
with a null tag.
@NonNull
public final FragmentTransaction replace(
@NonNull int containerViewId,
@NonNull Class<@NonNull Fragment> fragmentClass,
@Nullable Bundle args,
@Nullable String tag
)
Replace an existing fragment that was added to a container. This is essentially the same as calling remove
for all currently added fragments that were added with the same containerViewId and then add
with the same arguments given here.
Parameters | |
---|---|
@NonNull int containerViewId |
Identifier of the container whose fragment(s) are to be replaced. |
@NonNull Class<@NonNull Fragment> fragmentClass |
The new fragment to place in the container, created via the |
@Nullable Bundle args |
Optional arguments to be set on the fragment. |
@Nullable String tag |
Optional tag name for the fragment, to later retrieve the fragment with |
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public FragmentTransaction replace(
@NonNull int containerViewId,
@NonNull Fragment fragment,
@Nullable String tag
)
Replace an existing fragment that was added to a container. This is essentially the same as calling remove
for all currently added fragments that were added with the same containerViewId and then add
with the same arguments given here.
Parameters | |
---|---|
@NonNull int containerViewId |
Identifier of the container whose fragment(s) are to be replaced. |
@NonNull Fragment fragment |
The new fragment to place in the container. |
@Nullable String tag |
Optional tag name for the fragment, to later retrieve the fragment with |
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |
@NonNull
public FragmentTransaction runOnCommit(@NonNull Runnable runnable)
Add a Runnable to this transaction that will be run after this transaction has been committed. If fragment transactions are optimized
this may be after other subsequent fragment operations have also taken place, or operations in this transaction may have been optimized out due to the presence of a subsequent fragment transaction in the batch.
If a transaction is committed using commitAllowingStateLoss
this runnable may be executed when the FragmentManager is in a state where new transactions may not be committed without allowing state loss.
runOnCommit
may not be used with transactions added to the back stack
as Runnables cannot be persisted with back stack state. IllegalStateException
will be thrown if addToBackStack
has been previously called for this transaction or if it is called after a call to runOnCommit
.
Returns | |
---|---|
FragmentTransaction |
this FragmentTransaction |
Throws | |
---|---|
java.lang.IllegalStateException |
if |
@NonNull
public FragmentTransactionsetAllowOptimization(@NonNull boolean allowOptimization)
@NonNull
public FragmentTransactionsetBreadCrumbShortTitle(@NonNull int res)
Set the short title to show as a bread crumb when this transaction is on the back stack.
Parameters | |
---|---|
@NonNull int res |
A string resource containing the title. |
@NonNull
public FragmentTransactionsetBreadCrumbShortTitle(@Nullable CharSequence text)
Like setBreadCrumbShortTitle
but taking a raw string; this method is not recommended, as the string can not be changed later if the locale changes.
@NonNull
public FragmentTransactionsetBreadCrumbTitle(@NonNull int res)
Set the full title to show as a bread crumb when this transaction is on the back stack.
Parameters | |
---|---|
@NonNull int res |
A string resource containing the title. |
@NonNull
public FragmentTransactionsetBreadCrumbTitle(@Nullable CharSequence text)
Like setBreadCrumbTitle
but taking a raw string; this method is not recommended, as the string can not be changed later if the locale changes.
@NonNull
public FragmentTransaction setCustomAnimations(@NonNull int enter, @NonNull int exit)
Set specific animation resources to run for the fragments that are entering and exiting in this transaction. These animations will not be played when popping the back stack.
This method applies the custom animations to all future fragment operations; previous operations are unaffected. Fragment operations in the same FragmentTransaction
can set different animations by calling this method prior to each operation, e.g:
fragmentManager.beingTransaction() .setCustomAnimations(enter1, exit1) .add(MyFragmentClass, args, tag1) // this fragment gets the first animations .setCustomAnimations(enter2, exit2) .add(MyFragmentClass, args, tag2) // this fragment gets the second animations .commit()
@NonNull
public FragmentTransaction setCustomAnimations(
@NonNull int enter,
@NonNull int exit,
@NonNull int popEnter,
@NonNull int popExit
)
Set specific animation resources to run for the fragments that are entering and exiting in this transaction. The popEnter
and popExit
animations will be played for enter/exit operations specifically when popping the back stack.
This method applies the custom animations to all future fragment operations; previous operations are unaffected. Fragment operations in the same FragmentTransaction
can set different animations by calling this method prior to each operation, e.g:
fragmentManager.beingTransaction() .setCustomAnimations(enter1, exit1, popEnter1, popExit1) .add(MyFragmentClass, args, tag1) // this fragment gets the first animations .setCustomAnimations(enter2, exit2, popEnter2, popExit2) .add(MyFragmentClass, args, tag2) // this fragment gets the second animations .commit()
Parameters | |
---|---|
@NonNull int enter |
An animation or animator resource ID used for the enter animation on the view of the fragment being added or attached. |
@NonNull int exit |
An animation or animator resource ID used for the exit animation on the view of the fragment being removed or detached. |
@NonNull int popEnter |
An animation or animator resource ID used for the enter animation on the view of the fragment being readded or reattached caused by |
@NonNull int popExit |
An animation or animator resource ID used for the enter animation on the view of the fragment being removed or detached caused by |
@NonNull
public FragmentTransaction setMaxLifecycle(@NonNull Fragment fragment, @NonNull State state)
Set a ceiling for the state of an active fragment in this FragmentManager. If fragment is already above the received state, it will be forced down to the correct state.
The fragment provided must currently be added to the FragmentManager to have it's Lifecycle state capped, or previously added as part of this transaction. If the Lifecycle.State#INITIALIZED is passed in as the Lifecycle.State and the provided fragment has already moved beyond Lifecycle.State#INITIALIZED, an IllegalArgumentException
will be thrown.
If the Lifecycle.State#DESTROYED is passed in as the Lifecycle.State an IllegalArgumentException
will be thrown.
Parameters | |
---|---|
@NonNull Fragment fragment |
the fragment to have it's state capped. |
@NonNull State state |
the ceiling state for the fragment. |
Returns | |
---|---|
FragmentTransaction |
the same FragmentTransaction instance |
@NonNull
public FragmentTransaction setPrimaryNavigationFragment(@Nullable Fragment fragment)
Set a currently active fragment in this FragmentManager as the primary navigation fragment.
The primary navigation fragment's child FragmentManager
will be called first to process delegated navigation actions such as FragmentManager#popBackStack()
if no ID or transaction name is provided to pop to. Navigation operations outside of the fragment system may choose to delegate those actions to the primary navigation fragment as returned by FragmentManager#getPrimaryNavigationFragment()
.
The fragment provided must currently be added to the FragmentManager to be set as a primary navigation fragment, or previously added as part of this transaction.
Returns | |
---|---|
FragmentTransaction |
the same FragmentTransaction instance |
@NonNull
public FragmentTransaction setReorderingAllowed(@NonNull boolean reorderingAllowed)
Sets whether or not to allow optimizing operations within and across transactions. This will remove redundant operations, eliminating operations that cancel. For example, if two transactions are executed together, one that adds a fragment A and the next replaces it with fragment B, the operations will cancel and only fragment B will be added. That means that fragment A may not go through the creation/destruction lifecycle.
The side effect of removing redundant operations is that fragments may have state changes out of the expected order. For example, one transaction adds fragment A, a second adds fragment B, then a third removes fragment A. Without removing the redundant operations, fragment B could expect that while it is being created, fragment A will also exist because fragment A will be removed after fragment B was added. With removing redundant operations, fragment B cannot expect fragment A to exist when it has been created because fragment A's add/remove will be optimized out.
It can also reorder the state changes of Fragments to allow for better Transitions. Added Fragments may have Fragment#onCreate(Bundle)
called before replaced Fragments have Fragment#onDestroy()
called.
Fragment#postponeEnterTransition()
requires {@code setReorderingAllowed(true)}
.
The default is {@code false}
.
Parameters | |
---|---|
@NonNull boolean reorderingAllowed |
|
@NonNull
public FragmentTransaction setTransition(@NonNull int transition)
Select a standard transition animation for this transaction. May be one of TRANSIT_NONE
, TRANSIT_FRAGMENT_OPEN
, TRANSIT_FRAGMENT_CLOSE
, or TRANSIT_FRAGMENT_FADE
.
Parameters | |
---|---|
@NonNull int transition |
Value is |
@NonNull
public FragmentTransactionsetTransitionStyle(@NonNull int styleRes)
Set a custom style resource that will be used for resolving transit animations.
@NonNull
public FragmentTransaction show(@NonNull Fragment fragment)
Shows a previously hidden fragment. This is only relevant for fragments whose views have been added to a container, as this will cause the view to be shown.
Returns | |
---|---|
FragmentTransaction |
Returns the same FragmentTransaction instance. |