1page.title=List View
2parent.title=Layouts
3parent.link=declaring-layout.html
4@jd:body
5<div id="qv-wrapper">
6<div id="qv">
7<h2>In this document</h2>
8  <ol>
9    <li><a href="#Loader">Using a Loader</a></li>
10    <li><a href="#Example">Example</a></li>
11  </ol>
12  <h2>Key classes</h2>
13  <ol>
14    <li>{@link android.widget.ListView}</li>
15    <li>{@link android.widget.Adapter}</li>
16    <li>{@link android.support.v4.content.CursorLoader}</li>
17  </ol>
18  <h2>See also</h2>
19  <ol>
20    <li><a
21href="{@docRoot}guide/components/loaders.html">Loaders</a></li>
22  </ol>
23</div>
24</div>
25
26<p>{@link android.widget.ListView} is a view group that displays a list of
27scrollable items. The list items are automatically inserted to the list using an {@link
28android.widget.Adapter} that pulls content from a source such as an array or database query and
29converts each item result into a view that's placed into the list.</p>
30
31<p>For an introduction to how you can dynamically insert views using an adapter, read
32<a href="{@docRoot}guide/topics/ui/declaring-layout.html#AdapterViews">Building Layouts with
33  an Adapter</a>.</p>
34
35<img src="{@docRoot}images/ui/listview.png" alt="" />
36
37<h2 id="Loader">Using a Loader</h2>
38
39<p>Using a {@link
40android.support.v4.content.CursorLoader} is the standard way to query a {@link
41android.database.Cursor} as an asynchronous task in order to avoid blocking your app's main thread
42with the query. When the {@link android.support.v4.content.CursorLoader} receives the {@link
43android.database.Cursor} result, the {@link android.support.v4.app.LoaderManager.LoaderCallbacks
44LoaderCallbacks} receives a callback to {@link
45android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()}, which is
46where you update your {@link
47android.widget.Adapter} with the new {@link android.database.Cursor} and the list view then
48displays the results.</p>
49
50<p>Although the {@link android.support.v4.content.CursorLoader} APIs were first introduced in
51Android 3.0 (API level 11), they are also available in the <a
52href="{@docRoot}tools/extras/support-library.html">Support Library</a> so that your app may use them
53while supporting devices running Android 1.6 or higher.</p>
54
55<p>For more information about using a {@link
56android.support.v4.content.Loader} to asynchronously load data, see the <a
57href="{@docRoot}guide/components/loaders.html">Loaders</a> guide.</p>
58
59
60<h2 id="Example">Example</h2>
61
62<p>The following example uses {@link android.app.ListActivity}, which is an activity that includes
63a {@link android.widget.ListView} as its only layout element by default. It performs a query to
64the <a
65href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts
66Provider</a> for a list of names and phone numbers.</p>
67
68<p>The activity implements the {@link android.support.v4.app.LoaderManager.LoaderCallbacks
69LoaderCallbacks} interface in order to use a {@link android.support.v4.content.CursorLoader} that
70dynamically loads the data for the list view.</p>
71
72<pre>
73public class ListViewLoader extends ListActivity
74        implements LoaderManager.LoaderCallbacks&lt;Cursor> {
75
76    // This is the Adapter being used to display the list's data
77    SimpleCursorAdapter mAdapter;
78
79    // These are the Contacts rows that we will retrieve
80    static final String[] PROJECTION = new String[] {ContactsContract.Data._ID,
81            ContactsContract.Data.DISPLAY_NAME};
82
83    // This is the select criteria
84    static final String SELECTION = "((" + 
85            ContactsContract.Data.DISPLAY_NAME + " NOTNULL) AND (" +
86            ContactsContract.Data.DISPLAY_NAME + " != '' ))";
87
88    &#64;Override
89    protected void onCreate(Bundle savedInstanceState) {
90        super.onCreate(savedInstanceState);
91
92        // Create a progress bar to display while the list loads
93        ProgressBar progressBar = new ProgressBar(this);
94        progressBar.setLayoutParams(new LayoutParams(LayoutParams.WRAP_CONTENT,
95                LayoutParams.WRAP_CONTENT, Gravity.CENTER));
96        progressBar.setIndeterminate(true);
97        getListView().setEmptyView(progressBar);
98
99        // Must add the progress bar to the root of the layout
100        ViewGroup root = (ViewGroup) findViewById(android.R.id.content);
101        root.addView(progressBar);
102
103        // For the cursor adapter, specify which columns go into which views
104        String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME};
105        int[] toViews = {android.R.id.text1}; // The TextView in simple_list_item_1
106
107        // Create an empty adapter we will use to display the loaded data.
108        // We pass null for the cursor, then update it in onLoadFinished()
109        mAdapter = new SimpleCursorAdapter(this, 
110                android.R.layout.simple_list_item_1, null,
111                fromColumns, toViews, 0);
112        setListAdapter(mAdapter);
113
114        // Prepare the loader.  Either re-connect with an existing one,
115        // or start a new one.
116        getLoaderManager().initLoader(0, null, this);
117    }
118
119    // Called when a new Loader needs to be created
120    public Loader&lt;Cursor> onCreateLoader(int id, Bundle args) {
121        // Now create and return a CursorLoader that will take care of
122        // creating a Cursor for the data being displayed.
123        return new CursorLoader(this, ContactsContract.Data.CONTENT_URI,
124                PROJECTION, SELECTION, null, null);
125    }
126
127    // Called when a previously created loader has finished loading
128    public void onLoadFinished(Loader&lt;Cursor> loader, Cursor data) {
129        // Swap the new cursor in.  (The framework will take care of closing the
130        // old cursor once we return.)
131        mAdapter.swapCursor(data);
132    }
133
134    // Called when a previously created loader is reset, making the data unavailable
135    public void onLoaderReset(Loader&lt;Cursor> loader) {
136        // This is called when the last Cursor provided to onLoadFinished()
137        // above is about to be closed.  We need to make sure we are no
138        // longer using it.
139        mAdapter.swapCursor(null);
140    }
141
142    &#64;Override 
143    public void onListItemClick(ListView l, View v, int position, long id) {
144        // Do something when a list item is clicked
145    }
146}
147</pre>
148
149<p class="note"><strong>Note:</strong> Because this sample performs a query on the <a
150href="{@docRoot}guide/topics/providers/contacts-provider.html">Contacts
151Provider</a>, if you want to
152try this code, your app must request the {@link android.Manifest.permission#READ_CONTACTS}
153permission in the manifest file:<br/>
154<code>&lt;uses-permission android:name="android.permission.READ_CONTACTS" /></code></p>
155
156