| 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 {@link android.widget.ListView 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 {@link #onCreateView}.
To do this, your view hierarchy must contain a ListView object with the
id "@android:id/list" (or {@link 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
{@link 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 {@link android.widget.ListAdapter ListAdapter} interface.
Android provides two standard list adapters:
{@link android.widget.SimpleAdapter SimpleAdapter} for static data (Maps),
and {@link android.widget.SimpleCursorAdapter SimpleCursorAdapter} for Cursor
query results.
You must use
{@link #setListAdapter(ListAdapter) ListFragment.setListAdapter()} to
associate the list with an adapter. Do not directly call
{@link ListView#setAdapter(ListAdapter) ListView.setAdapter()} or else
important initialization will be skipped.
| 