androidx.fragment.app

Interfaces

FragmentManager.BackStackEntry

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

FragmentManager.OnBackStackChangedListener

Interface to watch for changes to the back stack.

FragmentOnAttachListener

Listener for receiving a callback immediately following onAttach.

FragmentResultListener

Listener for handling fragment results.

FragmentResultOwner

A class that manages passing data between fragments.

Classes

DialogFragment

A fragment that displays a dialog window, floating in the foreground of its activity's window.

Fragment

Static library support version of the framework's android.app.Fragment.

Fragment.SavedState

State information that has been retrieved from a fragment instance through FragmentManager.saveFragmentInstanceState.

FragmentActivity

Base class for activities that want to use the support-based Fragments.

FragmentContainer

Callbacks to a Fragment's container.

FragmentContainerView

FragmentContainerView is a customized Layout designed specifically for Fragments.

FragmentController

Provides integration points with a FragmentManager for a fragment host.

FragmentFactory

Interface used to control the instantiation of Fragment instances.

FragmentHostCallback

Integration points with the Fragment host.

FragmentManager

Static library support version of the framework's android.app.FragmentManager.

FragmentManager.FragmentLifecycleCallbacks

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

FragmentManagerNonConfig

This class is deprecated.

Have your FragmentHostCallback implement androidx.lifecycle.ViewModelStoreOwner to automatically retain the Fragment's non configuration state.

FragmentPagerAdapter

This class is deprecated.

Switch to androidx.viewpager2.widget.ViewPager2 and use androidx.viewpager2.adapter.FragmentStateAdapter instead.

FragmentStatePagerAdapter

This class is deprecated.

Switch to androidx.viewpager2.widget.ViewPager2 and use androidx.viewpager2.adapter.FragmentStateAdapter instead.

FragmentTabHost

This class is deprecated.

Use TabLayout and ViewPager instead.

FragmentTransaction

Static library support version of the framework's android.app.FragmentTransaction.

ListFragment

Static library support version of the framework's android.app.ListFragment.

Exceptions

Fragment.InstantiationException

Thrown by instantiate when there is an instantiation failure.

Annotations

Extension functions summary

inline Lazy<VM>
@MainThread
<VM : ViewModel> Fragment.activityViewModels(
    noinline extrasProducer: (() -> CreationExtras)?,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)?
)

Returns a property delegate to access parent activity's ViewModel, if factoryProducer is specified then ViewModelProvider.Factory returned by it will be used to create ViewModel first time.

inline FragmentTransaction
<F : Fragment> FragmentTransaction.add(tag: String, args: Bundle?)

Add a fragment to the associated FragmentManager without adding the Fragment to any container view.

inline FragmentTransaction
<F : Fragment> FragmentTransaction.add(
    containerViewId: @IdRes Int,
    tag: String?,
    args: Bundle?
)

Add a fragment to the associated FragmentManager, inflating the Fragment's view into the container view specified by containerViewId, to later retrieve via FragmentManager.findFragmentById.

Unit

Clears the stored result for the given requestKey.

Unit

Clears the stored FragmentResultListener for the given requestKey.

inline Unit
FragmentManager.commit(allowStateLoss: Boolean, body: FragmentTransaction.() -> Unit)

Run body in a FragmentTransaction which is automatically committed if it completes without exception.

inline Unit

Run body in a FragmentTransaction which is automatically committed if it completes without exception.

Lazy<VM>
@MainThread
<VM : ViewModel> Fragment.createViewModelLazy(
    viewModelClass: KClass<VM>,
    storeProducer: () -> ViewModelStore,
    extrasProducer: () -> CreationExtras,
    factoryProducer: (() -> ViewModelProvider.Factory)?
)

Helper method for creation of ViewModelLazy, that resolves null passed as factoryProducer to default factory.

F

Find a Fragment associated with a View.

inline FragmentTransaction
<F : Fragment> FragmentTransaction.replace(
    containerViewId: @IdRes Int,
    tag: String?,
    args: Bundle?
)

Replace an existing fragment that was added to a container.

Unit
Fragment.setFragmentResult(requestKey: String, result: Bundle)

Sets the given result for the requestKey.

Unit
Fragment.setFragmentResultListener(
    requestKey: String,
    listener: (requestKey: String, bundle: Bundle) -> Unit
)

Sets the FragmentResultListener for a given requestKey.

inline Unit
FragmentManager.transaction(
    now: Boolean,
    allowStateLoss: Boolean,
    body: FragmentTransaction.() -> Unit
)

This function is deprecated. Use commit { .. } or commitNow { .. } extensions

inline Lazy<VM>
@MainThread
<VM : ViewModel> Fragment.viewModels(
    noinline ownerProducer: () -> ViewModelStoreOwner,
    noinline extrasProducer: (() -> CreationExtras)?,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)?
)

Returns a property delegate to access ViewModel by default scoped to this Fragment:

Extension functions

activityViewModels

@MainThread
inline fun <VM : ViewModel> Fragment.activityViewModels(
    noinline extrasProducer: (() -> CreationExtras)? = null,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null
): Lazy<VM>

Returns a property delegate to access parent activity's ViewModel, if factoryProducer is specified then ViewModelProvider.Factory returned by it will be used to create ViewModel first time. Otherwise, the activity's default factory will be used.

class MyFragment : Fragment() {
val viewmodel: MyViewModel by activityViewModels()
}

This property can be accessed only after this Fragment is attached i.e., after Fragment.onAttach(), and access prior to that will result in IllegalArgumentException.

inline fun <F : Fragment> FragmentTransaction.add(tag: String, args: Bundle? = null): FragmentTransaction

Add a fragment to the associated FragmentManager without adding the Fragment to any container view.

The new fragment to be added will be created via the FragmentFactory of the FragmentManager.

Parameters
tag: String

Tag name for the fragment, to later retrieve the fragment with FragmentManager.findFragmentByTag.

args: Bundle? = null

Optional arguments to be set on the fragment.

Returns
FragmentTransaction

Returns the same FragmentTransaction instance.

inline fun <F : Fragment> FragmentTransaction.add(
    containerViewId: @IdRes Int,
    tag: String? = null,
    args: Bundle? = null
): FragmentTransaction

Add a fragment to the associated FragmentManager, inflating the Fragment's view into the container view specified by containerViewId, to later retrieve via FragmentManager.findFragmentById.

The new fragment to be added will be created via the FragmentFactory of the FragmentManager.

Parameters
containerViewId: @IdRes Int

Identifier of the container this fragment is to be placed in.

tag: String? = null

Optional tag name for the fragment, to later retrieve the fragment with FragmentManager.findFragmentByTag.

args: Bundle? = null

Optional arguments to be set on the fragment.

Returns
FragmentTransaction

Returns the same FragmentTransaction instance.

clearFragmentResult

fun Fragment.clearFragmentResult(requestKey: String): Unit

Clears the stored result for the given requestKey.

This clears a result that was previously set a call to setFragmentResult.

If this is called with a requestKey that is not associated with any result, this method does nothing.

Parameters
requestKey: String

key used to identify the result

clearFragmentResultListener

fun Fragment.clearFragmentResultListener(requestKey: String): Unit

Clears the stored FragmentResultListener for the given requestKey.

This clears a FragmentResultListener that was previously set a call to setFragmentResultListener.

If this is called with a requestKey that is not associated with any FragmentResultListener, this method does nothing.

Parameters
requestKey: String

key used to identify the result

inline fun FragmentManager.commit(allowStateLoss: Boolean = false, body: FragmentTransaction.() -> Unit): Unit

Run body in a FragmentTransaction which is automatically committed if it completes without exception.

The transaction will be completed by calling FragmentTransaction.commit unless allowStateLoss is set to true in which case FragmentTransaction.commitAllowingStateLoss will be used.

commitNow

@MainThread
inline fun FragmentManager.commitNow(allowStateLoss: Boolean = false, body: FragmentTransaction.() -> Unit): Unit

Run body in a FragmentTransaction which is automatically committed if it completes without exception.

The transaction will be completed by calling FragmentTransaction.commitNow unless allowStateLoss is set to true in which case FragmentTransaction.commitNowAllowingStateLoss will be used.

createViewModelLazy

@MainThread
fun <VM : ViewModel> Fragment.createViewModelLazy(
    viewModelClass: KClass<VM>,
    storeProducer: () -> ViewModelStore,
    extrasProducer: () -> CreationExtras = { defaultViewModelCreationExtras },
    factoryProducer: (() -> ViewModelProvider.Factory)? = null
): Lazy<VM>

Helper method for creation of ViewModelLazy, that resolves null passed as factoryProducer to default factory.

This method also takes an CreationExtras produces that provides default extras to the created view model.

findFragment

fun <F : Fragment> View.findFragment(): F

Find a Fragment associated with a 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.

Calling this on a View that does not have a Fragment set will result in an IllegalStateException

inline fun <F : Fragment> FragmentTransaction.replace(
    containerViewId: @IdRes Int,
    tag: String? = null,
    args: Bundle? = null
): FragmentTransaction

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.

The new fragment to place in the container will be created via the FragmentFactory of the FragmentManager.

Parameters
containerViewId: @IdRes Int

Identifier of the container whose fragment(s) are to be replaced.

tag: String? = null

Optional tag name for the fragment, to later retrieve the fragment with FragmentManager.findFragmentByTag.

args: Bundle? = null

Optional arguments to be set on the fragment.

Returns
FragmentTransaction

Returns the same FragmentTransaction instance.

setFragmentResult

fun Fragment.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 androidx.lifecycle.Lifecycle.State.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.

setFragmentResultListener

fun Fragment.setFragmentResultListener(
    requestKey: String,
    listener: (requestKey: String, bundle: Bundle) -> Unit
): Unit

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

Parameters
requestKey: String

requestKey used to store the result

listener: (requestKey: String, bundle: Bundle) -> Unit

listener for result changes.

transaction

Added in 1.1.0
Deprecated in 1.1.0
inline fun FragmentManager.transaction(
    now: Boolean = false,
    allowStateLoss: Boolean = false,
    body: FragmentTransaction.() -> Unit
): Unit

Run body in a FragmentTransaction which is automatically committed if it completes without exception.

One of four commit functions will be used based on the values of now and allowStateLoss:

|  now  |  allowStateLoss  | Method                         |
| ----- | ---------------- | ------------------------------ |
| false | false            |  commit()                      |
| false | true             |  commitAllowingStateLoss()     |
| true  | false            |  commitNow()                   |
| true  | true             |  commitNowAllowingStateLoss()  |
@MainThread
inline fun <VM : ViewModel> Fragment.viewModels(
    noinline ownerProducer: () -> ViewModelStoreOwner = { this },
    noinline extrasProducer: (() -> CreationExtras)? = null,
    noinline factoryProducer: (() -> ViewModelProvider.Factory)? = null
): Lazy<VM>

Returns a property delegate to access ViewModel by default scoped to this Fragment:

class MyFragment : Fragment() {
val viewmodel: MyViewModel by viewModels()
}

Custom ViewModelProvider.Factory can be defined via factoryProducer parameter, factory returned by it will be used to create ViewModel:

class MyFragment : Fragment() {
val viewmodel: MyViewModel by viewModels { myFactory }
}

Default scope may be overridden with parameter ownerProducer:

class MyFragment : Fragment() {
val viewmodel: MyViewModel by viewModels ({requireParentFragment()})
}

This property can be accessed only after this Fragment is attached i.e., after Fragment.onAttach(), and access prior to that will result in IllegalArgumentException.