public class

HtcListFragment

extends Fragment
java.lang.Object
   ↳ android.app.Fragment
     ↳ com.htc.fragment.app.HtcListFragment

Class Overview

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.

HtcListFragment hosts a HtcListView 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

HtcListFragment 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(LayoutInflater, ViewGroup, Bundle). To do this, your view hierarchy must contain a HtcListView object with the id "@android:id/list" (or 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 HtcListView 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 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 HtcListFragment's HtcListView object to data using a class that implements the ListAdapter interface. Android provides two standard list adapters: android.widget.SimpleAdapter SimpleAdapter for static data (Maps), and SimpleCursorAdapter for Cursor query results.

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

See Also

Summary

[Expand]
Inherited Constants
From interface android.content.ComponentCallbacks2
Public Constructors
HtcListFragment()
Public Methods
ListAdapter getListAdapter()
Get the ListAdapter associated with this activity's HtcListView.
HtcListView getListView()
Get the activity's list view widget.
void onListItemClick(HtcListView l, View v, int position, long id)
This method will be called when an item in the list is selected.
void setListAdapter(ListAdapter adapter)
Provide the cursor for the list view.
void setListShownNoAnimation(boolean shown)
Like #setListShown(boolean), but no animation is used when transitioning from the previous state.
[Expand]
Inherited Methods
From class android.app.Fragment
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2
From interface android.view.View.OnCreateContextMenuListener

Public Constructors

public HtcListFragment ()

Since: API Level 4.0

Public Methods

public ListAdapter getListAdapter ()

Since: API Level 4.0

Get the ListAdapter associated with this activity's HtcListView.

public HtcListView getListView ()

Since: API Level 4.0

Get the activity's list view widget.

public void onListItemClick (HtcListView l, View v, int position, long id)

Since: API Level 4.0

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 The HtcListView where the click happened
v The view that was clicked within the HtcListView
position The position of the view in the list
id The row id of the item that was clicked

public void setListAdapter (ListAdapter adapter)

Since: API Level 4.0

Provide the cursor for the list view.

public void setListShownNoAnimation (boolean shown)

Since: API Level 4.0

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