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<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 @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<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<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<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 @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><uses-permission android:name="android.permission.READ_CONTACTS" /></code></p> 155 156