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

ListFragment

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

class ListFragment : Fragment

Any
   ↳ Fragment
     ↳ ListFragment

Static library support version of the framework's android.app.ListFragment. 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.

Summary

Public constructors

Public functions

ListAdapter?

Get the ListAdapter associated with this fragment's ListView.

ListView

Get the fragment's list view widget.

Long

Get the cursor row ID of the currently selected list item.

Int

Get the position of the currently selected list item.

View?
onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
)

Provide default implementation to return a simple list view.

Unit

Detach from list view.

Unit
onListItemClick(l: ListView, v: View, position: Int, id: Long)

This method will be called when an item in the list is selected.

Unit
onViewCreated(view: View, savedInstanceState: Bundle?)

Attach to list view once the view hierarchy has been created.

ListAdapter

Get the ListAdapter associated with this fragment's ListView.

Unit

The default content for a ListFragment has a TextView that can be shown when the list is empty.

Unit
setListAdapter(adapter: ListAdapter?)

Provide the cursor for the list view.

Unit

Control whether the list is being displayed.

Unit

Like setListShown, but no animation is used when transitioning from the previous state.

Unit
setSelection(position: Int)

Set the currently selected list item to the specified position with the adapter's data

Inherited functions

From class Fragment
Unit
dump(
    prefix: String,
    fd: FileDescriptor?,
    writer: PrintWriter,
    args: Array<String>?
)

Print the Fragments's state into the given stream.

Boolean
equals(o: Any?)

Subclasses can not override equals().

FragmentActivity?

Return the FragmentActivity this fragment is currently associated with.

Boolean

Returns whether the the exit transition and enter transition overlap or not.

Boolean

Returns whether the the return transition and reenter transition overlap or not.

Bundle?

Return the arguments supplied when the fragment was instantiated, if any.

FragmentManager

Return a private FragmentManager for placing and managing Fragments inside of this Fragment.

Context?

Return the Context this fragment is currently associated with.

Factory

The Fragment's arguments when this is first called will be used as the defaults to any androidx.lifecycle.SavedStateHandle passed to a view model created using this factory.

Any?

Returns the Transition that will be used to move Views into the initial scene.

Any?

Returns the Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack.

FragmentManager?

This function is deprecated.

This has been removed in favor of getParentFragmentManager() which throws an IllegalStateException if the FragmentManager is null.

Any?

Return the host object of this fragment.

Int

Return the identifier this fragment is known by.

LayoutInflater

Returns the cached LayoutInflater used to inflate Views of this Fragment.

Lifecycle

Overriding this method is no longer supported and this method will be made final in a future version of Fragment.

LoaderManager

This function is deprecated.

Use LoaderManager.getInstance(this).

Fragment?

Returns the parent Fragment containing this Fragment.

FragmentManager

Return the FragmentManager for interacting with fragments associated with this fragment's activity.

Any?

Returns the Transition that will be used to move Views in to the scene when returning due to popping a back stack.

Resources

Return requireActivity().getResources().

Boolean

This function is deprecated.

Instead of retaining the Fragment itself, use a non-retained Fragment and keep retained state in a ViewModel attached to that Fragment.

Any?

Returns the Transition that will be used to move Views out of the scene when the Fragment is preparing to be removed, hidden, or detached because of popping the back stack.

SavedStateRegistry
Any?

Returns the Transition that will be used for shared elements transferred into the content Scene.

Any?

Return the Transition that will be used for shared elements transferred back during a pop of the back stack.

String
getString(resId: Int)

Return a localized string from the application's package's default string table.

String
getString(resId: Int, formatArgs: Array<Any>?)

Return a localized formatted string from the application's package's default string table, substituting the format arguments as defined in java.util.Formatter and format.

String?

Get the tag name of the fragment, if specified.

Fragment?

This function is deprecated.

Instead of using a target fragment to pass results, use FragmentManager#setFragmentResult(String, Bundle) to deliver results to FragmentResultListener instances registered by other fragments via FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener).

Int

This function is deprecated.

When using the target fragment replacement of FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener) and FragmentManager#setFragmentResult(String, Bundle), consider using setArguments to pass a {@code requestKey} if you need to support dynamic request keys.

CharSequence
getText(resId: Int)

Return a localized, styled CharSequence from the application's package's default string table.

Boolean

This function is deprecated.

Use FragmentTransaction#setMaxLifecycle(Fragment, Lifecycle.State) instead.

View?

Get the root view for the fragment's layout (the one returned by onCreateView), if provided.

LifecycleOwner

Get a LifecycleOwner that represents the Fragment's View lifecycle.

LiveData<LifecycleOwner>

Retrieve a LiveData which allows you to observe the lifecycle of the Fragment's View.

ViewModelStore

Returns the ViewModelStore associated with this Fragment

Int

Subclasses can not override hashCode().

Fragment
instantiate(context: Context, fname: String)

This function is deprecated.

Use FragmentManager#getFragmentFactory() and FragmentFactory#instantiate(ClassLoader, String)

Fragment
instantiate(context: Context, fname: String, args: Bundle?)

This function is deprecated.

Use FragmentManager#getFragmentFactory() and FragmentFactory#instantiate(ClassLoader, String), manually calling setArguments on the returned Fragment.

Boolean

Return true if the fragment is currently added to its activity.

Boolean

Return true if the fragment has been explicitly detached from the UI.

Boolean

Return true if the fragment has been hidden.

Boolean

Return true if the layout is included as part of an activity view hierarchy via the <fragment> tag.

Boolean

Return true if this fragment is currently being removed from its activity.

Boolean

Return true if the fragment is in the resumed state.

Boolean

Returns true if this fragment is added and its state has already been saved by its host.

Boolean

Return true if the fragment is currently visible to the user.

Unit
onActivityCreated(savedInstanceState: Bundle?)

This function is deprecated.

use onViewCreated for code touching the Fragment's view and onCreate for other initialization.

Unit
onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)

This function is deprecated.

use registerForActivityResult with the appropriate ActivityResultContract and handling the result in the callback.

Unit
onAttach(context: Context)

Called when a fragment is first attached to its context.

Unit
onAttach(activity: Activity)

This function is deprecated.

See onAttach.

Unit
onAttachFragment(childFragment: Fragment)

This function is deprecated.

The responsibility for listening for fragments being attached has been moved to FragmentManager.

Unit
onConfigurationChanged(newConfig: Configuration)
Boolean
onContextItemSelected(item: MenuItem)

This hook is called whenever an item in a context menu is selected.

Unit
onCreate(savedInstanceState: Bundle?)

Called to do initial creation of a fragment.

Animation?
onCreateAnimation(transit: Int, enter: Boolean, nextAnim: Int)

Called when a fragment loads an animation.

Animator?
onCreateAnimator(transit: Int, enter: Boolean, nextAnim: Int)

Called when a fragment loads an animator.

Unit
onCreateContextMenu(menu: ContextMenu, v: View, menuInfo: ContextMenuInfo?)

Called when a context menu for the {@code view} is about to be shown.

Unit
onCreateOptionsMenu(menu: Menu, inflater: MenuInflater)

Initialize the contents of the Fragment host's standard options menu.

Unit

Called when the fragment is no longer in use.

Unit

Called when this fragment's option menu items are no longer being included in the overall options menu.

Unit

Called when the fragment is no longer attached to its activity.

LayoutInflater
onGetLayoutInflater(savedInstanceState: Bundle?)

Returns the LayoutInflater used to inflate Views of this Fragment.

Unit

Called when the hidden state (as returned by isHidden of the fragment has changed.

Unit
onInflate(
    context: Context,
    attrs: AttributeSet,
    savedInstanceState: Bundle?
)

Called when a fragment is being created as part of a view layout inflation, typically from setting the content view of an activity.

Unit
onInflate(
    activity: Activity,
    attrs: AttributeSet,
    savedInstanceState: Bundle?
)

This function is deprecated.

See onInflate.

Unit
Unit
onMultiWindowModeChanged(isInMultiWindowMode: Boolean)

Called when the Fragment's activity changes from fullscreen mode to multi-window mode and visa-versa.

Boolean
onOptionsItemSelected(item: MenuItem)

This hook is called whenever an item in your options menu is selected.

Unit
onOptionsMenuClosed(menu: Menu)

This hook is called whenever the options menu is being closed (either by the user canceling the menu with the back/menu button, or when an item is selected).

Unit

Called when the Fragment is no longer resumed.

Unit
onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean)

Called by the system when the activity changes to and from picture-in-picture mode.

Unit

Prepare the Fragment host's standard options menu to be displayed.

Unit
onPrimaryNavigationFragmentChanged(
    isPrimaryNavigationFragment: Boolean
)

Callback for when the primary navigation state of this Fragment has changed.

Unit
onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<String>,
    grantResults: Array<Int>
)

This function is deprecated.

use registerForActivityResult passing in a RequestMultiplePermissions object for the ActivityResultContract and handling the result in the callback.

Unit

Called when the fragment is visible to the user and actively running.

Unit
onSaveInstanceState(outState: Bundle)

Called to ask the fragment to save its current dynamic state, so it can later be reconstructed in a new instance if its process is restarted.

Unit

Called when the Fragment is visible to the user.

Unit

Called when the Fragment is no longer started.

Unit
onViewStateRestored(savedInstanceState: Bundle?)

Called when all saved state has been restored into the view hierarchy of the fragment.

Unit

Postpone the entering Fragment transition until startPostponedEnterTransition or FragmentManager#executePendingTransactions() has been called.

Unit
postponeEnterTransition(duration: Long, timeUnit: TimeUnit)

Postpone the entering Fragment transition for a given amount of time and then call startPostponedEnterTransition.

ActivityResultLauncher<I>
<I, O> registerForActivityResult(
    contract: ActivityResultContract<I, O>,
    callback: ActivityResultCallback<O>
)

If the host of this fragment is an ActivityResultRegistryOwner the ActivityResultRegistry of the host will be used.

ActivityResultLauncher<I>
<I, O> registerForActivityResult(
    contract: ActivityResultContract<I, O>,
    registry: ActivityResultRegistry,
    callback: ActivityResultCallback<O>
)
Unit

Registers a context menu to be shown for the given view (multiple views can show the context menu).

Unit
requestPermissions(permissions: Array<String>, requestCode: Int)

This function is deprecated.

use registerForActivityResult passing in a RequestMultiplePermissions object for the ActivityResultContract and handling the result in the callback.

FragmentActivity

Return the FragmentActivity this fragment is currently associated with.

Bundle

Return the arguments supplied when the fragment was instantiated.

Context

Return the Context this fragment is currently associated with.

FragmentManager

This function is deprecated.

This has been renamed to getParentFragmentManager() to make it clear that you are accessing the FragmentManager that contains this Fragment and not the FragmentManager associated with child Fragments.

Any

Return the host object of this fragment.

Fragment

Returns the parent Fragment containing this Fragment.

View

Get the root view for the fragment's layout (the one returned by onCreateView).

Unit

Sets whether the the exit transition and enter transition overlap or not.

Unit

Sets whether the the return transition and reenter transition overlap or not.

Unit
setArguments(args: Bundle?)

Supply the construction arguments for this fragment.

Unit
setEnterSharedElementCallback(callback: SharedElementCallback?)

When custom transitions are used with Fragments, the enter transition callback is called when this Fragment is attached or detached when not popping the back stack.

Unit
setEnterTransition(transition: Any?)

Sets the Transition that will be used to move Views into the initial scene.

Unit
setExitSharedElementCallback(callback: SharedElementCallback?)

When custom transitions are used with Fragments, the exit transition callback is called when this Fragment is attached or detached when popping the back stack.

Unit
setExitTransition(transition: Any?)

Sets the Transition that will be used to move Views out of the scene when the fragment is removed, hidden, or detached when not popping the back stack.

Unit

Report that this fragment would like to participate in populating the options menu by receiving a call to onCreateOptionsMenu and related methods.

Unit

Set the initial saved state that this Fragment should restore itself from when first being constructed, as returned by FragmentManager.saveFragmentInstanceState.

Unit
setMenuVisibility(menuVisible: Boolean)

Set a hint for whether this fragment's menu should be visible.

Unit
setReenterTransition(transition: Any?)

Sets the Transition that will be used to move Views in to the scene when returning due to popping a back stack.

Unit

This function is deprecated.

Instead of retaining the Fragment itself, use a non-retained Fragment and keep retained state in a ViewModel attached to that Fragment.

Unit
setReturnTransition(transition: Any?)

Sets the Transition that will be used to move Views out of the scene when the Fragment is preparing to be removed, hidden, or detached because of popping the back stack.

Unit

Sets the Transition that will be used for shared elements transferred into the content Scene.

Unit

Sets the Transition that will be used for shared elements transferred back during a pop of the back stack.

Unit
setTargetFragment(fragment: Fragment?, requestCode: Int)

This function is deprecated.

Instead of using a target fragment to pass results, the fragment requesting a result should use FragmentManager#setFragmentResultListener(String, LifecycleOwner, FragmentResultListener) to register a FragmentResultListener with a {@code * requestKey} using its parent fragment manager.

Unit
setUserVisibleHint(isVisibleToUser: Boolean)

This function is deprecated.

If you are manually calling this method, use FragmentTransaction#setMaxLifecycle(Fragment, Lifecycle.State) instead.

Boolean

Gets whether you should show UI with rationale before requesting a permission.

Unit
startActivity(intent: Intent)

Call Activity#startActivity(Intent) from the fragment's containing Activity.

Unit
startActivity(intent: Intent, options: Bundle?)

Call Activity#startActivity(Intent, Bundle) from the fragment's containing Activity.

Unit
startActivityForResult(intent: Intent, requestCode: Int)

This function is deprecated.

use registerForActivityResult passing in a StartActivityForResult object for the ActivityResultContract.

Unit
startActivityForResult(intent: Intent, requestCode: Int, options: Bundle?)

This function is deprecated.

use registerForActivityResult passing in a StartActivityForResult object for the ActivityResultContract.

Unit
startIntentSenderForResult(
    intent: IntentSender,
    requestCode: Int,
    fillInIntent: Intent?,
    flagsMask: Int,
    flagsValues: Int,
    extraFlags: Int,
    options: Bundle?
)

This function is deprecated.

use registerForActivityResult passing in a StartIntentSenderForResult object for the ActivityResultContract.

Unit

Begin postponed transitions after postponeEnterTransition was called.

String
Unit

Prevents a context menu to be shown for the given view.

Public constructors

ListFragment

ListFragment()

Public functions

getListAdapter

fun getListAdapter(): ListAdapter?

Get the ListAdapter associated with this fragment's ListView.

See also
requireListAdapter

#requireListAdapter()

getListView

fun getListView(): ListView

Get the fragment's list view widget.

getSelectedItemId

fun getSelectedItemId(): Long

Get the cursor row ID of the currently selected list item.

getSelectedItemPosition

fun getSelectedItemPosition(): Int

Get the position of the currently selected list item.

onCreateView

fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
): View?

Provide default implementation to return a simple list view. Subclasses can override to replace with their own layout. If doing so, the returned view hierarchy must have a ListView whose id is android.R.id.list and can optionally have a sibling view id android.R.id.empty that is to be shown when the list is empty.

If you are overriding this method with your own custom content, consider including the standard layout list_content in your layout file, so that you continue to retain all of the standard behavior of ListFragment. In particular, this is currently the only way to have the built-in indeterminant progress state be shown.

onDestroyView

fun onDestroyView(): Unit

Detach from list view.

onListItemClick

fun onListItemClick(l: ListView, v: View, position: Int, id: Long): Unit

This method will be called when an item in the list is selected. Subclasses should override. Subclasses can call getListView().getItemAtPosition(position) if they need to access the data associated with the selected item.

Parameters
l: ListView

The ListView where the click happened

v: View

The view that was clicked within the ListView

position: Int

The position of the view in the list

id: Long

The row id of the item that was clicked

onViewCreated

fun onViewCreated(view: View, savedInstanceState: Bundle?): Unit

Attach to list view once the view hierarchy has been created.

requireListAdapter

fun requireListAdapter(): ListAdapter

Get the ListAdapter associated with this fragment's ListView.

Throws
java.lang.IllegalStateException

if no ListAdapter has been set.

See also
getListAdapter

#getListAdapter()

setEmptyText

fun setEmptyText(text: CharSequence?): Unit

The default content for a ListFragment has a TextView that can be shown when the list is empty. If you would like to have it shown, call this method to supply the text it should use.

setListAdapter

fun setListAdapter(adapter: ListAdapter?): Unit

Provide the cursor for the list view.

setListShown

fun setListShown(shown: Boolean): Unit

Control whether the list is being displayed. You can make it not displayed if you are waiting for the initial data to show in it. During this time an indeterminant progress indicator will be shown instead.

Applications do not normally need to use this themselves. The default behavior of ListFragment is to start with the list not being shown, only showing it once an adapter is given with setListAdapter. If the list at that point had not been shown, when it does get shown it will be do without the user ever seeing the hidden state.

Parameters
shown: Boolean

If true, the list view is shown; if false, the progress indicator. The initial value is true.

setListShownNoAnimation

fun setListShownNoAnimation(shown: Boolean): Unit

Like setListShown, but no animation is used when transitioning from the previous state.

setSelection

fun setSelection(position: Int): Unit

Set the currently selected list item to the specified position with the adapter's data

Parameters
position: Int