Added in API level 11
Deprecated in API level 28

ListFragment


open class ListFragment : Fragment
kotlin.Any
   ↳ android.app.Fragment
   ↳ android.app.ListFragment

A fragment that displays a list of items by binding to a data source such as an array or Cursor, and exposes event handlers when the user selects an item.

ListFragment hosts a ListView object that can be bound to different data sources, typically either an array or a Cursor holding query results. Binding, screen layout, and row layout are discussed in the following sections.

Screen Layout

ListFragment has a default layout that consists of a single list view. However, if you desire, you can customize the fragment layout by returning your own view hierarchy from onCreateView. To do this, your view hierarchy must contain a ListView object with the id "@android:id/list" (or android.R.id#list if it's in code)

Optionally, your view hierarchy can contain another view object of any type to display when the list view is empty. This "empty list" notifier must have an id "android:empty". Note that when an empty view is present, the list view will be hidden when there is no data to display.

The following code demonstrates an (ugly) custom list layout. It has a list with a green background, and an alternate red "no data" message.

<?xml version="1.0" encoding="utf-8"?>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
          android:orientation="vertical"
          android:layout_width="match_parent"
          android:layout_height="match_parent"
          android:paddingLeft="8dp"
          android:paddingRight="8dp">
 
      <ListView android:id="@id/android:list"
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:background="#00FF00"
                android:layout_weight="1"
                android:drawSelectorOnTop="false"/>
 
      <TextView android:id="@id/android:empty"
                android:layout_width="match_parent"
                android:layout_height="match_parent"
                android:background="#FF0000"
                android:text="No data"/>
  </LinearLayout>
  

Row Layout

You can specify the layout of individual rows in the list. You do this by specifying a layout resource in the ListAdapter object hosted by the fragment (the ListAdapter binds the ListView to the data; more on this later).

A ListAdapter constructor takes a parameter that specifies a layout resource for each row. It also has two additional parameters that let you specify which data field to associate with which object in the row layout resource. These two parameters are typically parallel arrays.

Android provides some standard row layout resources. These are in the android.R.layout class, and have names such as simple_list_item_1, simple_list_item_2, and two_line_list_item. The following layout XML is the source for the resource two_line_list_item, which displays two data fields,one above the other, for each list row.

<?xml version="1.0" encoding="utf-8"?>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:orientation="vertical">
 
      <TextView android:id="@+id/text1"
          android:textSize="16sp"
          android:textStyle="bold"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"/>
 
      <TextView android:id="@+id/text2"
          android:textSize="16sp"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"/>
  </LinearLayout>
  

You must identify the data bound to each TextView object in this layout. The syntax for this is discussed in the next section.

Binding to Data

You bind the ListFragment's ListView object to data using a class that implements the ListAdapter interface. Android provides two standard list adapters: SimpleAdapter for static data (Maps), and SimpleCursorAdapter for Cursor query results.

You must use ListFragment.setListAdapter() to associate the list with an adapter. Do not directly call ListView.setAdapter() or else important initialization will be skipped.

Summary

Inherited constants
Public constructors

Public methods
open ListAdapter!

Get the ListAdapter associated with this fragment's ListView.

open ListView!

Get the fragment's list view widget.

open Long

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

open Int

Get the position of the currently selected list item.

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

Provide default implementation to return a simple list view.

open Unit

Detach from list view.

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

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

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

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

open Unit

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

open Unit

Provide the cursor for the list view.

open Unit

Control whether the list is being displayed.

open Unit

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

open Unit
setSelection(position: Int)

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

Inherited functions

Public constructors

ListFragment

Added in API level 11
ListFragment()

Public methods

getListAdapter

Added in API level 11
open fun getListAdapter(): ListAdapter!

Deprecated: Deprecated in Java.

Get the ListAdapter associated with this fragment's ListView.

getListView

Added in API level 11
open fun getListView(): ListView!

Deprecated: Deprecated in Java.

Get the fragment's list view widget.

getSelectedItemId

Added in API level 11
open fun getSelectedItemId(): Long

Deprecated: Deprecated in Java.

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

getSelectedItemPosition

Added in API level 11
open fun getSelectedItemPosition(): Int

Deprecated: Deprecated in Java.

Get the position of the currently selected list item.

onCreateView

Added in API level 11
open fun onCreateView(
    inflater: LayoutInflater!,
    container: ViewGroup?,
    savedInstanceState: Bundle!
): View?

Deprecated: Deprecated in Java.

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 android.R.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.

Parameters
inflater LayoutInflater!: The LayoutInflater object that can be used to inflate any views in the fragment,
container ViewGroup?: If non-null, this is the parent view that the fragment's UI should be attached to. The fragment should not add the view itself, but this can be used to generate the LayoutParams of the view.
savedInstanceState Bundle!: If non-null, this fragment is being re-constructed from a previous saved state as given here.
Return
View? Return the View for the fragment's UI, or null.

onDestroyView

Added in API level 11
open fun onDestroyView(): Unit

Deprecated: Deprecated in Java.

Detach from list view.

onListItemClick

Added in API level 11
open fun onListItemClick(
    l: ListView!,
    v: View!,
    position: Int,
    id: Long
): Unit

Deprecated: Deprecated in Java.

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

Added in API level 13
Deprecated in API level 28
open fun onViewCreated(
    view: View!,
    savedInstanceState: Bundle?
): Unit

Deprecated: Deprecated in Java.

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

Parameters
view View!: The View returned by onCreateView(android.view.LayoutInflater,android.view.ViewGroup,android.os.Bundle).
savedInstanceState Bundle?: If non-null, this fragment is being re-constructed from a previous saved state as given here.

setEmptyText

Added in API level 11
open fun setEmptyText(text: CharSequence!): Unit

Deprecated: Deprecated in Java.

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

Added in API level 11
open fun setListAdapter(adapter: ListAdapter!): Unit

Deprecated: Deprecated in Java.

Provide the cursor for the list view.

setListShown

Added in API level 11
open fun setListShown(shown: Boolean): Unit

Deprecated: Deprecated in Java.

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(android.widget.ListAdapter). 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

Added in API level 11
open fun setListShownNoAnimation(shown: Boolean): Unit

Deprecated: Deprecated in Java.

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

setSelection

Added in API level 11
open fun setSelection(position: Int): Unit

Deprecated: Deprecated in Java.

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

Parameters
position Int: