{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

FragmentManager

{% setvar page_path %}androidx/fragment/app/FragmentManager.html{% endsetvar %} {% setvar can_switch %}1{% endsetvar %} {% include "reference/_java_switcher2.md" %}

public abstract class FragmentManager implements FragmentResultOwner


Static library support version of the framework's android.app.FragmentManager. 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 FragmentManager documentation for a class overview.

Your activity must derive from FragmentActivity to use this. From such an activity, you can acquire the FragmentManager by calling FragmentActivity#getSupportFragmentManager.

Summary

Nested types

FragmentManager.BackStackEntry

Representation of an entry on the fragment back stack, as created with FragmentTransaction.addToBackStack().

FragmentManager.FragmentLifecycleCallbacks

Callback interface for listening to fragment state changes that happen within a given FragmentManager.

FragmentManager.OnBackStackChangedListener

Interface to watch for changes to the back stack.

Constants

static final @NonNull int

Flag for popBackStack and popBackStack: If set, and the name or ID of a back stack entry has been supplied, then all matching entries will be consumed until one that doesn't match is found or the bottom of the stack is reached.

Public constructors

Public methods

@NonNull void

Add a FragmentOnAttachListener that should receive a call to FragmentOnAttachListener#onAttachFragment(FragmentManager, Fragment) when a new Fragment is attached to this FragmentManager.

@NonNull void

Add a new listener for changes to the fragment back stack.

@NonNull FragmentTransaction

Start a series of edit operations on the Fragments associated with this FragmentManager.

final @NonNull void

Clears the stored result for the given requestKey.

final @NonNull void

Clears the stored FragmentResultListener for the given requestKey.

@NonNull void
dump(
    @NonNull String prefix,
    @Nullable FileDescriptor fd,
    @NonNull PrintWriter writer,
    @Nullable Array<@NonNull String> args
)

Print the FragmentManager's state into the given stream.

static @NonNull void
enableDebugLogging(@NonNull boolean enabled)

This method is deprecated.

FragmentManager now respects Log#isLoggable(String, int) for debug logging, allowing you to use adb shell setprop log.tag.FragmentManager VERBOSE.

static @FragmentStateManagerControl @NonNull void
enableNewStateManager(@NonNull boolean enabled)

Control whether FragmentManager uses the new state manager that is responsible for:

@NonNull boolean

After a FragmentTransaction is committed with FragmentTransaction.commit(), it is scheduled to be executed asynchronously on the process's main thread.

static @NonNull F
<F extends Fragment> findFragment(@NonNull View view)

Find a Fragment associated with the given View.

@Nullable Fragment

Finds a fragment that was identified by the given id either when inflated from XML or as the container ID when added in a transaction.

@Nullable Fragment

Finds a fragment that was identified by the given tag either when inflated from XML or as supplied when added in a transaction.

@NonNull FragmentManager.BackStackEntry

Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack.

@NonNull int

Return the number of entries currently in the back stack.

@Nullable Fragment
getFragment(@NonNull Bundle bundle, @NonNull String key)

Retrieve the current Fragment instance for a reference previously placed with putFragment.

@NonNull FragmentFactory

Gets the current FragmentFactory used to instantiate new Fragment instances.

@NonNull List<@NonNull Fragment>

Get a list of all fragments that are currently added to the FragmentManager.

@Nullable Fragment

Return the currently active primary navigation fragment for this FragmentManager.

@NonNull boolean

Returns true if the final Activity.onDestroy() call has been made on the FragmentManager's Activity, so this instance is now dead.

@NonNull boolean

Returns {@code true} if the FragmentManager's state has already been saved by its host.

@NonNull void

Pop the top state off the back stack.

@NonNull void
popBackStack(@Nullable String name, @NonNull int flags)

Pop the last fragment transition from the manager's fragment back stack.

@NonNull void
popBackStack(@NonNull int id, @NonNull int flags)

Pop all back stack states up to the one with the given identifier.

@NonNull boolean

Like popBackStack, but performs the operation immediately inside of the call.

@NonNull boolean

Like popBackStack, but performs the operation immediately inside of the call.

@NonNull boolean
popBackStackImmediate(@NonNull int id, @NonNull int flags)

Like popBackStack, but performs the operation immediately inside of the call.

@NonNull void
putFragment(
    @NonNull Bundle bundle,
    @NonNull String key,
    @NonNull Fragment fragment
)

Put a reference to a fragment in a Bundle.

@NonNull void

Registers a FragmentLifecycleCallbacks to listen to fragment lifecycle events happening in this FragmentManager.

@NonNull void

Remove a FragmentOnAttachListener that was previously added via addFragmentOnAttachListener.

@NonNull void

Remove a listener that was previously added with addOnBackStackChangedListener.

@Nullable Fragment.SavedState

Save the current instance state of the given Fragment.

@NonNull void

Set a FragmentFactory for this FragmentManager that will be used to create new Fragment instances from this point onward.

final @NonNull void
setFragmentResult(@NonNull String requestKey, @NonNull Bundle result)

Sets the given result for the requestKey.

final @NonNull void
setFragmentResultListener(
    @NonNull String requestKey,
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull FragmentResultListener listener
)

Sets the FragmentResultListener for a given requestKey.

@NonNull String
@NonNull void

Unregisters a previously registered FragmentLifecycleCallbacks.

Constants

POP_BACK_STACK_INCLUSIVE

@NonNull
public static final @NonNull int POP_BACK_STACK_INCLUSIVE

Flag for popBackStack and popBackStack: If set, and the name or ID of a back stack entry has been supplied, then all matching entries will be consumed until one that doesn't match is found or the bottom of the stack is reached. Otherwise, all entries up to but not including that entry will be removed.

Public constructors

FragmentManager

@NonNull
public FragmentManager()

Public methods

addFragmentOnAttachListener

@NonNull
public void addFragmentOnAttachListener(@NonNull FragmentOnAttachListener listener)

Add a FragmentOnAttachListener that should receive a call to FragmentOnAttachListener#onAttachFragment(FragmentManager, Fragment) when a new Fragment is attached to this FragmentManager.

Parameters
@NonNull FragmentOnAttachListener listener

Listener to add

addOnBackStackChangedListener

@NonNull
public void addOnBackStackChangedListener(
    @NonNull FragmentManager.OnBackStackChangedListener listener
)

Add a new listener for changes to the fragment back stack.

beginTransaction

@NonNull
public FragmentTransaction beginTransaction()

Start a series of edit operations on the Fragments associated with this FragmentManager.

Note: A fragment transaction can only be created/committed prior to an activity saving its state. If you try to commit a transaction after FragmentActivity.onSaveInstanceState() (and prior to a following FragmentActivity.onStart or FragmentActivity.onResume(), you will get an error. This is because the framework takes care of saving your current fragments in the state, and if changes are made after the state is saved then they will be lost.

clearFragmentResult

@NonNull
public final void clearFragmentResult(@NonNull String requestKey)

Clears the stored result for the given requestKey. This clears any result that was previously set via setFragmentResult that hasn't yet been delivered to a FragmentResultListener.

Parameters
@NonNull String requestKey

key used to identify the result

clearFragmentResultListener

@NonNull
public final void clearFragmentResultListener(@NonNull String requestKey)

Clears the stored FragmentResultListener for the given requestKey. This clears any FragmentResultListener that was previously set via setFragmentResultListener.

Parameters
@NonNull String requestKey

key used to identify the result

dump

@NonNull
public void dump(
    @NonNull String prefix,
    @Nullable FileDescriptor fd,
    @NonNull PrintWriter writer,
    @Nullable Array<@NonNull String> args
)

Print the FragmentManager's state into the given stream.

Parameters
@NonNull String prefix

Text to print at the front of each line.

@Nullable FileDescriptor fd

The raw file descriptor that the dump is being sent to.

@NonNull PrintWriter writer

A PrintWriter to which the dump is to be set.

@Nullable Array<@NonNull String> args

Additional arguments to the dump request.

enableDebugLogging

@NonNull
public static void enableDebugLogging(@NonNull boolean enabled)

Control whether the framework's internal fragment manager debugging logs are turned on. If enabled, you will see output in logcat as the framework performs fragment operations.

See also
Log

android.util.Log#isLoggable(String, int)

enableNewStateManager

@FragmentStateManagerControl
@NonNull
public static @FragmentStateManagerControl void enableNewStateManager(@NonNull boolean enabled)

Control whether FragmentManager uses the new state manager that is responsible for:

This must only be changed before any fragment transactions are done (i.e., in your Application class or prior to super.onCreate()in every activity with the same value for all activities). Changing it after that point is not supported and can result in fragments not moving to their expected state.

This is enabled by default. Disabling it should only be used in cases where you are debugging a potential regression and as part of filing an issue to verify and fix the regression.

Parameters
@NonNull boolean enabled

Whether the new state manager should be enabled.

executePendingTransactions

@NonNull
public boolean executePendingTransactions()

After a FragmentTransaction is committed with FragmentTransaction.commit(), it is scheduled to be executed asynchronously on the process's main thread. If you want to immediately executing any such pending operations, you can call this function (only from the main thread) to do so. Note that all callbacks and other related behavior will be done from within this call, so be careful about where this is called from.

If you are committing a single transaction that does not modify the fragment back stack, strongly consider using FragmentTransaction#commitNow() instead. This can help avoid unwanted side effects when other code in your app has pending committed transactions that expect different timing.

This also forces the start of any postponed Transactions where Fragment#postponeEnterTransition() has been called.

Returns
boolean

Returns true if there were any pending transactions to be executed.

findFragment

@NonNull
public static F <F extends Fragment> findFragment(@NonNull View view)

Find a Fragment associated with the given View. This method will locate the Fragment associated with this view. This is automatically populated for the View returned by Fragment#onCreateView and its children.

Parameters
@NonNull View view

the view to search from

Returns
F

the locally scoped Fragment to the given view

Throws
java.lang.IllegalStateException

if the given view does not correspond with a Fragment.

findFragmentById

@Nullable
@NonNull
public Fragment findFragmentById(@NonNull int id)

Finds a fragment that was identified by the given id either when inflated from XML or as the container ID when added in a transaction. This first searches through fragments that are currently added to the manager's activity; if no such fragment is found, then all fragments currently on the back stack associated with this ID are searched.

Returns
Fragment

The fragment if found or null otherwise.

findFragmentByTag

@Nullable
@NonNull
public Fragment findFragmentByTag(@Nullable String tag)

Finds a fragment that was identified by the given tag either when inflated from XML or as supplied when added in a transaction. This first searches through fragments that are currently added to the manager's activity; if no such fragment is found, then all fragments currently on the back stack are searched.

If provided a {@code null} tag, this method returns null.

Parameters
@Nullable String tag

the tag used to search for the fragment

Returns
Fragment

The fragment if found or null otherwise.

getBackStackEntryAt

@NonNull
public FragmentManager.BackStackEntry getBackStackEntryAt(@NonNull int index)

Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack.

getBackStackEntryCount

@NonNull
public int getBackStackEntryCount()

Return the number of entries currently in the back stack.

getFragment

@Nullable
@NonNull
public Fragment getFragment(@NonNull Bundle bundle, @NonNull String key)

Retrieve the current Fragment instance for a reference previously placed with putFragment.

Parameters
@NonNull Bundle bundle

The bundle from which to retrieve the fragment reference.

@NonNull String key

The name of the entry in the bundle.

Returns
Fragment

Returns the current Fragment instance that is associated with the given reference.

getFragmentFactory

@NonNull
public FragmentFactory getFragmentFactory()

Gets the current FragmentFactory used to instantiate new Fragment instances.

If no factory has been explicitly set on this FragmentManager via setFragmentFactory, the FragmentFactory of the parent FragmentManager will be returned.

Returns
FragmentFactory

the current FragmentFactory

getFragments

@NonNull
public List<@NonNull FragmentgetFragments()

Get a list of all fragments that are currently added to the FragmentManager. This may include those that are hidden as well as those that are shown. This will not include any fragments only in the back stack, or fragments that are detached or removed.

The order of the fragments in the list is the order in which they were added or attached.

Returns
List<@NonNull Fragment>

A list of all fragments that are added to the FragmentManager.

getPrimaryNavigationFragment

@Nullable
@NonNull
public Fragment getPrimaryNavigationFragment()

Return the currently active primary navigation fragment for this FragmentManager. The primary navigation fragment is set by fragment transactions using FragmentTransaction#setPrimaryNavigationFragment(Fragment).

The primary navigation fragment's child FragmentManager will be called first to process delegated navigation actions such as popBackStack if no ID or transaction name is provided to pop to.

Returns
Fragment

the fragment designated as the primary navigation fragment

isDestroyed

@NonNull
public boolean isDestroyed()

Returns true if the final Activity.onDestroy() call has been made on the FragmentManager's Activity, so this instance is now dead.

isStateSaved

@NonNull
public boolean isStateSaved()

Returns {@code true} if the FragmentManager's state has already been saved by its host. Any operations that would change saved state should not be performed if this method returns true. For example, any popBackStack() method, such as popBackStackImmediate or any FragmentTransaction using FragmentTransaction#commit() instead of FragmentTransaction#commitAllowingStateLoss() will change the state and will result in an error.

Returns
boolean

true if this FragmentManager's state has already been saved by its host

popBackStack

@NonNull
public void popBackStack()

Pop the top state off the back stack. This function is asynchronous -- it enqueues the request to pop, but the action will not be performed until the application returns to its event loop.

popBackStack

@NonNull
public void popBackStack(@Nullable String name, @NonNull int flags)

Pop the last fragment transition from the manager's fragment back stack. This function is asynchronous -- it enqueues the request to pop, but the action will not be performed until the application returns to its event loop.

Parameters
@Nullable String name

If non-null, this is the name of a previous back state to look for; if found, all states up to that state will be popped. The POP_BACK_STACK_INCLUSIVE flag can be used to control whether the named state itself is popped. If null, only the top state is popped.

@NonNull int flags

Either 0 or POP_BACK_STACK_INCLUSIVE.

popBackStack

@NonNull
public void popBackStack(@NonNull int id, @NonNull int flags)

Pop all back stack states up to the one with the given identifier. This function is asynchronous -- it enqueues the request to pop, but the action will not be performed until the application returns to its event loop.

Parameters
@NonNull int id

Identifier of the stated to be popped. If no identifier exists, false is returned. The identifier is the number returned by FragmentTransaction.commit(). The POP_BACK_STACK_INCLUSIVE flag can be used to control whether the named state itself is popped.

@NonNull int flags

Either 0 or POP_BACK_STACK_INCLUSIVE.

popBackStackImmediate

@NonNull
public boolean popBackStackImmediate()

Like popBackStack, but performs the operation immediately inside of the call. This is like calling executePendingTransactions afterwards without forcing the start of postponed Transactions.

Returns
boolean

Returns true if there was something popped, else false.

popBackStackImmediate

@NonNull
public boolean popBackStackImmediate(@Nullable String name, @NonNull int flags)

Like popBackStack, but performs the operation immediately inside of the call. This is like calling executePendingTransactions afterwards without forcing the start of postponed Transactions.

Returns
boolean

Returns true if there was something popped, else false.

popBackStackImmediate

@NonNull
public boolean popBackStackImmediate(@NonNull int id, @NonNull int flags)

Like popBackStack, but performs the operation immediately inside of the call. This is like calling executePendingTransactions afterwards without forcing the start of postponed Transactions.

Returns
boolean

Returns true if there was something popped, else false.

putFragment

@NonNull
public void putFragment(
    @NonNull Bundle bundle,
    @NonNull String key,
    @NonNull Fragment fragment
)

Put a reference to a fragment in a Bundle. This Bundle can be persisted as saved state, and when later restoring getFragment will return the current instance of the same fragment.

Parameters
@NonNull Bundle bundle

The bundle in which to put the fragment reference.

@NonNull String key

The name of the entry in the bundle.

@NonNull Fragment fragment

The Fragment whose reference is to be stored.

registerFragmentLifecycleCallbacks

@NonNull
public void registerFragmentLifecycleCallbacks(
    @NonNull FragmentManager.FragmentLifecycleCallbacks cb,
    @NonNull boolean recursive
)

Registers a FragmentLifecycleCallbacks to listen to fragment lifecycle events happening in this FragmentManager. All registered callbacks will be automatically unregistered when this FragmentManager is destroyed.

Parameters
@NonNull FragmentManager.FragmentLifecycleCallbacks cb

Callbacks to register

@NonNull boolean recursive

true to automatically register this callback for all child FragmentManagers

removeFragmentOnAttachListener

@NonNull
public void removeFragmentOnAttachListener(
    @NonNull FragmentOnAttachListener listener
)

Remove a FragmentOnAttachListener that was previously added via addFragmentOnAttachListener. It will no longer get called when a new Fragment is attached.

Parameters
@NonNull FragmentOnAttachListener listener

Listener to remove

removeOnBackStackChangedListener

@NonNull
public void removeOnBackStackChangedListener(
    @NonNull FragmentManager.OnBackStackChangedListener listener
)

Remove a listener that was previously added with addOnBackStackChangedListener.

saveFragmentInstanceState

@Nullable
@NonNull
public Fragment.SavedState saveFragmentInstanceState(@NonNull Fragment fragment)

Save the current instance state of the given Fragment. This can be used later when creating a new instance of the Fragment and adding it to the fragment manager, to have it create itself to match the current state returned here. Note that there are limits on how this can be used:

Parameters
@NonNull Fragment fragment

The Fragment whose state is to be saved.

Returns
Fragment.SavedState

The generated state. This will be null if there was no interesting state created by the fragment.

setFragmentFactory

@NonNull
public void setFragmentFactory(@NonNull FragmentFactory fragmentFactory)

Set a FragmentFactory for this FragmentManager that will be used to create new Fragment instances from this point onward.

The child FragmentManager of all Fragments in this FragmentManager will also use this factory if one is not explicitly set.

Parameters
@NonNull FragmentFactory fragmentFactory

the factory to use to create new Fragment instances

See also
getFragmentFactory

#getFragmentFactory()

setFragmentResult

@NonNull
public final void setFragmentResult(@NonNull String requestKey, @NonNull Bundle result)

Sets the given result for the requestKey. This result will be delivered to a FragmentResultListener that is called given to setFragmentResultListener with the same requestKey. If no FragmentResultListener with the same key is set or the Lifecycle associated with the listener is not at least STARTED, the result is stored until one becomes available, or clearFragmentResult is called with the same requestKey.

Parameters
@NonNull String requestKey

key used to identify the result

@NonNull Bundle result

the result to be passed to another fragment

setFragmentResultListener

@NonNull
public final void setFragmentResultListener(
    @NonNull String requestKey,
    @NonNull LifecycleOwner lifecycleOwner,
    @NonNull FragmentResultListener listener
)

Sets the FragmentResultListener for a given requestKey. Once the given LifecycleOwner is at least in the STARTED state, any results set by setFragmentResult using the same requestKey will be delivered to the callback. The callback will remain active until the LifecycleOwner reaches the DESTROYED state or clearFragmentResultListener is called with the same requestKey.

Parameters
@NonNull String requestKey

requestKey used to identify the result

@NonNull LifecycleOwner lifecycleOwner

lifecycleOwner for handling the result

@NonNull FragmentResultListener listener

listener for result changes

toString

@NonNull
public String toString()

unregisterFragmentLifecycleCallbacks

@NonNull
public void unregisterFragmentLifecycleCallbacks(
    @NonNull FragmentManager.FragmentLifecycleCallbacks cb
)

Unregisters a previously registered FragmentLifecycleCallbacks. If the callback was not previously registered this call has no effect. All registered callbacks will be automatically unregistered when this FragmentManager is destroyed.

Parameters
@NonNull FragmentManager.FragmentLifecycleCallbacks cb

Callbacks to unregister