FragmentManager
public
abstract
class
FragmentManager
extends Object
implements
FragmentResultOwner
java.lang.Object | |
↳ | androidx.fragment.app.FragmentManager |
Static library support version of the framework's 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 classes | |
---|---|
interface |
FragmentManager.BackStackEntry
Representation of an entry on the fragment back stack, as created
with |
class |
FragmentManager.FragmentLifecycleCallbacks
Callback interface for listening to fragment state changes that happen within a given FragmentManager. |
interface |
FragmentManager.OnBackStackChangedListener
Interface to watch for changes to the back stack. |
Constants | |
---|---|
int |
POP_BACK_STACK_INCLUSIVE
Flag for |
Public constructors | |
---|---|
FragmentManager()
|
Public methods | |
---|---|
void
|
addFragmentOnAttachListener(FragmentOnAttachListener listener)
Add a |
void
|
addOnBackStackChangedListener(FragmentManager.OnBackStackChangedListener listener)
Add a new listener for changes to the fragment back stack. |
FragmentTransaction
|
beginTransaction()
Start a series of edit operations on the Fragments associated with this FragmentManager. |
final
void
|
clearFragmentResult(String requestKey)
Clears the stored result for the given requestKey. |
final
void
|
clearFragmentResultListener(String requestKey)
Clears the stored |
void
|
dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)
Print the FragmentManager's state into the given stream. |
static
void
|
enableDebugLogging(boolean enabled)
This method is deprecated.
FragmentManager now respects |
static
void
|
enableNewStateManager(boolean enabled)
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).
|
boolean
|
executePendingTransactions()
After a |
static
<F extends Fragment>
F
|
findFragment(View view)
|
Fragment
|
findFragmentById(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. |
Fragment
|
findFragmentByTag(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. |
FragmentManager.BackStackEntry
|
getBackStackEntryAt(int index)
Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack. |
int
|
getBackStackEntryCount()
Return the number of entries currently in the back stack. |
Fragment
|
getFragment(Bundle bundle, String key)
Retrieve the current Fragment instance for a reference previously
placed with |
FragmentFactory
|
getFragmentFactory()
Gets the current |
List<Fragment>
|
getFragments()
Get a list of all fragments that are currently added to the FragmentManager. |
Fragment
|
getPrimaryNavigationFragment()
Return the currently active primary navigation fragment for this FragmentManager. |
boolean
|
isDestroyed()
Returns true if the final |
boolean
|
isStateSaved()
Returns |
void
|
popBackStack()
Pop the top state off the back stack. |
void
|
popBackStack(int id, int flags)
Pop all back stack states up to the one with the given identifier. |
void
|
popBackStack(String name, int flags)
Pop the last fragment transition from the manager's fragment back stack. |
boolean
|
popBackStackImmediate()
Like |
boolean
|
popBackStackImmediate(int id, int flags)
Like |
boolean
|
popBackStackImmediate(String name, int flags)
Like |
void
|
putFragment(Bundle bundle, String key, Fragment fragment)
Put a reference to a fragment in a Bundle. |
void
|
registerFragmentLifecycleCallbacks(FragmentManager.FragmentLifecycleCallbacks cb, boolean recursive)
Registers a |
void
|
removeFragmentOnAttachListener(FragmentOnAttachListener listener)
Remove a |
void
|
removeOnBackStackChangedListener(FragmentManager.OnBackStackChangedListener listener)
Remove a listener that was previously added with
|
Fragment.SavedState
|
saveFragmentInstanceState(Fragment fragment)
Save the current instance state of the given Fragment. |
void
|
setFragmentFactory(FragmentFactory fragmentFactory)
Set a |
final
void
|
setFragmentResult(String requestKey, Bundle result)
Sets the given result for the requestKey. |
final
void
|
setFragmentResultListener(String requestKey, LifecycleOwner lifecycleOwner, FragmentResultListener listener)
Sets the |
String
|
toString()
|
void
|
unregisterFragmentLifecycleCallbacks(FragmentManager.FragmentLifecycleCallbacks cb)
Unregisters a previously registered |
Inherited methods | |
---|---|
Constants
POP_BACK_STACK_INCLUSIVE
public static final int POP_BACK_STACK_INCLUSIVE
Flag for popBackStack(String, int)
and popBackStack(int, int)
: 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.
Constant Value: 1 (0x00000001)
Public constructors
FragmentManager
public FragmentManager ()
Public methods
addFragmentOnAttachListener
public void addFragmentOnAttachListener (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 | |
---|---|
listener |
FragmentOnAttachListener : Listener to add
|
addOnBackStackChangedListener
public void addOnBackStackChangedListener (FragmentManager.OnBackStackChangedListener listener)
Add a new listener for changes to the fragment back stack.
Parameters | |
---|---|
listener |
FragmentManager.OnBackStackChangedListener |
beginTransaction
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.
Returns | |
---|---|
FragmentTransaction |
clearFragmentResult
public final void clearFragmentResult (String requestKey)
Clears the stored result for the given requestKey.
This clears any result that was previously set via
setFragmentResult(String, Bundle)
that hasn't yet been delivered to a
FragmentResultListener
.
Parameters | |
---|---|
requestKey |
String : key used to identify the result
|
clearFragmentResultListener
public final void clearFragmentResultListener (String requestKey)
Clears the stored FragmentResultListener
for the given requestKey.
This clears any FragmentResultListener
that was previously set via
setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)
.
Parameters | |
---|---|
requestKey |
String : key used to identify the result
|
dump
public void dump (String prefix, FileDescriptor fd, PrintWriter writer, String[] args)
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 |
String : Additional arguments to the dump request.
|
enableDebugLogging
public static void enableDebugLogging (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
.
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.
Parameters | |
---|---|
enabled |
boolean |
See also:
enableNewStateManager
public static void enableNewStateManager (boolean enabled)
Control whether FragmentManager uses the new state manager that is responsible for:
- Moving Fragments through their lifecycle methods
- Running animations and transitions
- Handling postponed transactions
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.
|
executePendingTransactions
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
public static F findFragment (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(LayoutInflater, ViewGroup, Bundle)
and its children.
Parameters | |
---|---|
view |
View : the view to search from |
Returns | |
---|---|
F |
the locally scoped Fragment to the given view |
Throws | |
---|---|
IllegalStateException |
if the given view does not correspond with a
Fragment .
|
findFragmentById
public Fragment findFragmentById (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.
Parameters | |
---|---|
id |
int |
Returns | |
---|---|
Fragment |
The fragment if found or null otherwise. |
findFragmentByTag
public Fragment findFragmentByTag (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 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. |
getBackStackEntryAt
public FragmentManager.BackStackEntry getBackStackEntryAt (int index)
Return the BackStackEntry at index index in the back stack; entries start index 0 being the bottom of the stack.
Parameters | |
---|---|
index |
int |
Returns | |
---|---|
FragmentManager.BackStackEntry |
getBackStackEntryCount
public int getBackStackEntryCount ()
Return the number of entries currently in the back stack.
Returns | |
---|---|
int |
getFragment
public Fragment getFragment (Bundle bundle, String key)
Retrieve the current Fragment instance for a reference previously
placed with putFragment(Bundle, String, Fragment)
.
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. |
getFragmentFactory
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(FragmentFactory)
, the FragmentFactory of the
parent FragmentManager
will be returned.
Returns | |
---|---|
FragmentFactory |
the current FragmentFactory |
getFragments
public List<Fragment> getFragments ()
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<Fragment> |
A list of all fragments that are added to the FragmentManager. |
getPrimaryNavigationFragment
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
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.
Returns | |
---|---|
boolean |
isStateSaved
public boolean isStateSaved ()
Returns 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
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
public void popBackStack (int id, 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 | |
---|---|
id |
int : 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. |
flags |
int : Either 0 or POP_BACK_STACK_INCLUSIVE .
|
popBackStack
public void popBackStack (String name, 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 | |
---|---|
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
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. |
flags |
int : Either 0 or POP_BACK_STACK_INCLUSIVE .
|
popBackStackImmediate
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
public boolean popBackStackImmediate (int id, int flags)
Like popBackStack(int, int)
, but performs the operation immediately
inside of the call. This is like calling executePendingTransactions()
afterwards without forcing the start of postponed Transactions.
Parameters | |
---|---|
id |
int |
flags |
int |
Returns | |
---|---|
boolean |
Returns true if there was something popped, else false. |
popBackStackImmediate
public boolean popBackStackImmediate (String name, int flags)
Like popBackStack(String, int)
, but performs the operation immediately
inside of the call. This is like calling executePendingTransactions()
afterwards without forcing the start of postponed Transactions.
Parameters | |
---|---|
name |
String |
flags |
int |
Returns | |
---|---|
boolean |
Returns true if there was something popped, else false. |
putFragment
public void putFragment (Bundle bundle, String key, Fragment fragment)
Put a reference to a fragment in a Bundle. This Bundle can be
persisted as saved state, and when later restoring
getFragment(Bundle, String)
will return the current
instance of the same fragment.
Parameters | |
---|---|
bundle |
Bundle : The bundle in which to put the fragment reference. |
key |
String : The name of the entry in the bundle. |
fragment |
Fragment : The Fragment whose reference is to be stored.
|
registerFragmentLifecycleCallbacks
public void registerFragmentLifecycleCallbacks (FragmentManager.FragmentLifecycleCallbacks cb, boolean recursive)
Registers a FragmentManager.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
|
removeFragmentOnAttachListener
public void removeFragmentOnAttachListener (FragmentOnAttachListener listener)
Remove a FragmentOnAttachListener
that was previously added via
addFragmentOnAttachListener(FragmentOnAttachListener)
. It will no longer
get called when a new Fragment is attached.
Parameters | |
---|---|
listener |
FragmentOnAttachListener : Listener to remove
|
removeOnBackStackChangedListener
public void removeOnBackStackChangedListener (FragmentManager.OnBackStackChangedListener listener)
Remove a listener that was previously added with
addOnBackStackChangedListener(OnBackStackChangedListener)
.
Parameters | |
---|---|
listener |
FragmentManager.OnBackStackChangedListener |
saveFragmentInstanceState
public Fragment.SavedState saveFragmentInstanceState (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:
- The Fragment must currently be attached to the FragmentManager.
- A new Fragment created using this saved state must be the same class type as the Fragment it was created from.
- The saved state can not contain dependencies on other fragments --
that is it can't use
putFragment(Bundle, String, Fragment)
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. |
setFragmentFactory
public void setFragmentFactory (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 | |
---|---|
fragmentFactory |
FragmentFactory : the factory to use to create new Fragment instances |
See also:
setFragmentResult
public final void setFragmentResult (String requestKey, Bundle result)
Sets the given result for the requestKey. This result will be delivered to a
FragmentResultListener
that is called given to
setFragmentResultListener(String, LifecycleOwner, FragmentResultListener)
with
the same requestKey. If no FragmentResultListener
with the same key is set or the
Lifecycle associated with the listener is not at least
Lifecycle.State.STARTED
, the result is stored until one becomes
available, or clearFragmentResult(String)
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
|
setFragmentResultListener
public final void setFragmentResultListener (String requestKey, LifecycleOwner lifecycleOwner, FragmentResultListener listener)
Sets the FragmentResultListener
for a given requestKey. Once the given
LifecycleOwner
is at least in the Lifecycle.State.STARTED
state, any results set by setFragmentResult(String, Bundle)
using the same
requestKey will be delivered to the
callback
. The callback will
remain active until the LifecycleOwner reaches the
Lifecycle.State.DESTROYED
state or
clearFragmentResultListener(String)
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
|
toString
public String toString ()
Returns | |
---|---|
String |
unregisterFragmentLifecycleCallbacks
public void unregisterFragmentLifecycleCallbacks (FragmentManager.FragmentLifecycleCallbacks cb)
Unregisters a previously registered FragmentManager.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
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.