{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
abstract class FragmentManager : 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
.
Nested types |
|
---|---|
FragmentManager.BackStackEntry |
Representation of an entry on the fragment back stack, as created with |
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 |
|
---|---|
Int |
Flag for |
Public constructors |
|
---|---|
Public functions |
|
---|---|
Unit |
Add a |
Unit |
Add a new listener for changes to the fragment back stack. |
FragmentTransaction |
Start a series of edit operations on the Fragments associated with this FragmentManager. |
Unit |
clearFragmentResult(requestKey: String) Clears the stored result for the given requestKey. |
Unit |
clearFragmentResultListener(requestKey: String) Clears the stored |
Unit |
dump( Print the FragmentManager's state into the given stream. |
Unit |
This function is deprecated. FragmentManager now respects Log#isLoggable(String, int) for debug logging, allowing you to use |
@FragmentStateManagerControl Unit |
enableNewStateManager(enabled: Boolean) Control whether FragmentManager uses the new state manager that is responsible for: |
Boolean |
After a |
F |
<F : Fragment?> findFragment(view: View) Find a |
Fragment? |
findFragmentById(id: Int) 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. |
Fragment? |
findFragmentByTag(tag: String?) Finds a fragment that was identified by the given tag either when inflated from XML or as supplied when added in a transaction. |
FragmentManager.BackStackEntry |
getBackStackEntryAt(index: Int) Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack. |
Int |
Return the number of entries currently in the back stack. |
Fragment? |
getFragment(bundle: Bundle, key: String) Retrieve the current Fragment instance for a reference previously placed with |
FragmentFactory |
Gets the current |
List<Fragment> |
Get a list of all fragments that are currently added to the FragmentManager. |
Fragment? |
Return the currently active primary navigation fragment for this FragmentManager. |
Boolean |
Returns true if the final Activity.onDestroy() call has been made on the FragmentManager's Activity, so this instance is now dead. |
Boolean |
Returns |
Unit |
Pop the top state off the back stack. |
Unit |
popBackStack(name: String?, flags: Int) Pop the last fragment transition from the manager's fragment back stack. |
Unit |
popBackStack(id: Int, flags: Int) Pop all back stack states up to the one with the given identifier. |
Boolean |
Like |
Boolean |
popBackStackImmediate(name: String?, flags: Int) Like |
Boolean |
popBackStackImmediate(id: Int, flags: Int) Like |
Unit |
putFragment(bundle: Bundle, key: String, fragment: Fragment) Put a reference to a fragment in a Bundle. |
Unit |
registerFragmentLifecycleCallbacks( Registers a |
Unit |
Remove a |
Unit |
Remove a listener that was previously added with |
Fragment.SavedState? |
saveFragmentInstanceState(fragment: Fragment) Save the current instance state of the given Fragment. |
Unit |
setFragmentFactory(fragmentFactory: FragmentFactory) Set a |
Unit |
setFragmentResult(requestKey: String, result: Bundle) Sets the given result for the requestKey. |
Unit |
setFragmentResultListener( Sets the |
String |
toString() |
Unit |
Unregisters a previously registered |
val POP_BACK_STACK_INCLUSIVE: 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. Otherwise, all entries up to but not including that entry will be removed.
fun addFragmentOnAttachListener(listener: FragmentOnAttachListener): Unit
Add a FragmentOnAttachListener
that should receive a call to FragmentOnAttachListener#onAttachFragment(FragmentManager, Fragment)
when a new Fragment is attached to this FragmentManager.
Parameters | |
---|---|
listener: FragmentOnAttachListener |
Listener to add |
fun addOnBackStackChangedListener(
listener: FragmentManager.OnBackStackChangedListener
): Unit
Add a new listener for changes to the fragment back stack.
fun beginTransaction(): FragmentTransaction
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.
fun clearFragmentResult(requestKey: String): Unit
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 | |
---|---|
requestKey: String |
key used to identify the result |
fun clearFragmentResultListener(requestKey: String): Unit
Clears the stored FragmentResultListener
for the given requestKey. This clears any FragmentResultListener
that was previously set via setFragmentResultListener
.
Parameters | |
---|---|
requestKey: String |
key used to identify the result |
fun dump(
prefix: String,
fd: FileDescriptor?,
writer: PrintWriter,
args: Array<String>?
): Unit
Print the FragmentManager's state into the given stream.
Parameters | |
---|---|
prefix: String |
Text to print at the front of each line. |
fd: FileDescriptor? |
The raw file descriptor that the dump is being sent to. |
writer: PrintWriter |
A PrintWriter to which the dump is to be set. |
args: Array<String>? |
Additional arguments to the dump request. |
funenableDebugLogging(enabled: Boolean): Unit
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) |
@FragmentStateManagerControl
fun enableNewStateManager(enabled: Boolean): @FragmentStateManagerControl Unit
Control whether FragmentManager uses the new state manager that is responsible for:
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 | |
---|---|
enabled: Boolean |
Whether the new state manager should be enabled. |
fun executePendingTransactions(): Boolean
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. |
fun <F : Fragment?> findFragment(view: View): F
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 | |
---|---|
view: View |
the view to search from |
Returns | |
---|---|
F |
the locally scoped |
Throws | |
---|---|
java.lang.IllegalStateException |
if the given view does not correspond with a |
fun findFragmentById(id: Int): 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. 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. |
fun findFragmentByTag(tag: String?): Fragment?
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 | |
---|---|
tag: String? |
the tag used to search for the fragment |
Returns | |
---|---|
Fragment? |
The fragment if found or null otherwise. |
fun getBackStackEntryAt(index: Int): FragmentManager.BackStackEntry
Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack.
fun getBackStackEntryCount(): Int
Return the number of entries currently in the back stack.
fun getFragment(bundle: Bundle, key: String): Fragment?
Retrieve the current Fragment instance for a reference previously placed with putFragment
.
Parameters | |
---|---|
bundle: Bundle |
The bundle from which to retrieve the fragment reference. |
key: String |
The name of the entry in the bundle. |
Returns | |
---|---|
Fragment? |
Returns the current Fragment instance that is associated with the given reference. |
fun getFragmentFactory(): FragmentFactory
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 |
fun getFragments(): List<Fragment>
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.
fun getPrimaryNavigationFragment(): Fragment?
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 |
fun isDestroyed(): Boolean
Returns true if the final Activity.onDestroy() call has been made on the FragmentManager's Activity, so this instance is now dead.
fun isStateSaved(): Boolean
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 |
fun popBackStack(): Unit
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.
fun popBackStack(name: String?, flags: Int): Unit
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 | |
---|---|
name: String? |
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 |
flags: Int |
Either 0 or |
fun popBackStack(id: Int, flags: Int): Unit
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 | |
---|---|
id: Int |
Identifier of the stated to be popped. If no identifier exists, false is returned. The identifier is the number returned by |
flags: Int |
Either 0 or |
fun popBackStackImmediate(): Boolean
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. |
fun popBackStackImmediate(name: String?, flags: Int): Boolean
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. |
fun popBackStackImmediate(id: Int, flags: Int): Boolean
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. |
fun putFragment(bundle: Bundle, key: String, fragment: Fragment): Unit
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.
fun registerFragmentLifecycleCallbacks(
cb: FragmentManager.FragmentLifecycleCallbacks,
recursive: Boolean
): Unit
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 | |
---|---|
cb: FragmentManager.FragmentLifecycleCallbacks |
Callbacks to register |
recursive: Boolean |
true to automatically register this callback for all child FragmentManagers |
fun removeFragmentOnAttachListener(listener: FragmentOnAttachListener): Unit
Remove a FragmentOnAttachListener
that was previously added via addFragmentOnAttachListener
. It will no longer get called when a new Fragment is attached.
Parameters | |
---|---|
listener: FragmentOnAttachListener |
Listener to remove |
fun removeOnBackStackChangedListener(
listener: FragmentManager.OnBackStackChangedListener
): Unit
Remove a listener that was previously added with addOnBackStackChangedListener
.
fun saveFragmentInstanceState(fragment: Fragment): Fragment.SavedState?
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:
putFragment
to store a fragment reference because that reference may not be valid when this saved state is later used. Likewise the Fragment's target and result code are not included in this state. Parameters | |
---|---|
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. |
fun setFragmentFactory(fragmentFactory: FragmentFactory): Unit
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 | |
---|---|
fragmentFactory: FragmentFactory |
the factory to use to create new Fragment instances |
See also | |
---|---|
getFragmentFactory |
#getFragmentFactory() |
fun setFragmentResult(requestKey: String, result: Bundle): Unit
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 | |
---|---|
requestKey: String |
key used to identify the result |
result: Bundle |
the result to be passed to another fragment |
fun setFragmentResultListener(
requestKey: String,
lifecycleOwner: LifecycleOwner,
listener: FragmentResultListener
): Unit
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 | |
---|---|
requestKey: String |
requestKey used to identify the result |
lifecycleOwner: LifecycleOwner |
lifecycleOwner for handling the result |
listener: FragmentResultListener |
listener for result changes |
fun unregisterFragmentLifecycleCallbacks(
cb: FragmentManager.FragmentLifecycleCallbacks
): Unit
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 | |
---|---|
cb: FragmentManager.FragmentLifecycleCallbacks |
Callbacks to unregister |