SimpleCursorAdapters and ListViews

Hey everyone,

So this post will be a comprehensive tutorial on using SimpleCursorAdapters, as well as creating your own Custom CursorAdapters, and also using the alternative BaseAdapters / Custom BaseAdapters, and finally how these different CursorAdapters are used to create listviews in your activities! This post will be replete with examples, so hopefully you guys find it helpful.

So first off, what is a SimpleCursorAdapter and how do you use it? So let’s say you want to create a list that “mimics” the native contact list. In order to do this, you’re going to need two XML files in addition to your ListActivity – so I’ll define all three here:

public class ListA extends ListActivity {

      @Override
      public void onCreate(Bundle savedInstance) {
            setContentView(R.layout.list_example);

            // some code

            Cursor cursor = getContentResolver().query(People.CONTENT_URI, new String[] {People._ID, People.NAME, People.NUMBER}, null, null, null);
            startManagingCursor(cursor);

            // the desired columns to be bound
            String[] columns = new String[] { People.NAME, People.NUMBER };
            // the XML defined views which the data will be bound to
            int[] to = new int[] { R.id.name_entry, R.id.number_entry };

            // create the adapter using the cursor pointing to the desired data as well as the layout information
            SimpleCursorAdapter mAdapter = new SimpleCursorAdapter(this, R.layout.list_example_entry, cursor, columns, to);

            // set this adapter as your ListActivity's adapter
            this.setListAdapter(mAdapter);
      }
}

And now this is how we would define:

R.layout.list_example

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
	android:layout_width="fill_parent"
	android:layout_height="wrap_content" >
	<ListView
		android:id="@android:id/android:list"
		android:layout_width="fill_parent"
		android:layout_height="wrap_content" />
</LinearLayout>

Note a few things here. This is just the very basic layout your Activity can take… for instance if you wanted to pad the list with TextViews or EditTexts above and or below then that’s perfectly fine – you would just need to add them in the appropriate place relative to the defined ListView. Also, note that the id of the ListView is “@android:id/android:list”, CONTRARY to what many sources say (some say it is “@id/android:list” or “@+id/android:list” but this will throw you an error). Now, with our Activity’s layout defined, the last thing we need to do is define each entry’s layout, and so I typically create a separate XML file and make it something like:

R.layout.list_example_entry

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
	android:orientation="vertical"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content" >
	<TextView
		android:id="@+id/name_entry"
		android:layout_width="wrap_content"
		android:layout_height="wrap_content"
		android:textSize="28dip" />
       <TextView
		android:id="@+id/number_entry"
		android:layout_width="wrap_content"
		android:layout_height="wrap_content"
		android:textSize="28dip" />
</LinearLayout>

Now, with this list entry each row of our list will look like:

Contact Name
Contact Number

And so you can use this R.layout.list_example_entry file to customize how you want EACH ROW ENTRY to look like.

Now it’s important to look at these three pieces of code and see the relationship between each one. In your SimpleCursorAdapter, first you obtain a cursor pointing to the table of data that you want. In your CursorAdapter, it will move the cursor down each row and first obtain the desired information, and then it will add that information to the correct places in your list_example_entry. How does your CursorAdapter know which columns from your data table to retrieve? Well that’s precisely what the

String[] columns = new String[] { People.NAME, People.NUMBER };

line in our example does, and once this data is retrieved where does it know which views in our XML layout to place them in? Well that’s what the “to” array is for:

int[] to = new int[] { R.id.name_entry, R.id.number_entry };

And finally, where does the cursor know which layout file to look for R.id.name_entry and R.id.number_entry? Well you supply it in the constructor of the SimpleCursorAdapter:

// note the 2nd parameter tells the cursor which row entry layout to use
SimpleCursorAdapter mAdapter = new SimpleCursorAdapter(this, R.layout.list_example_entry, cursor, columns, to);

And so that’s how everything is pieced together!

The next post will be on creating your own Custom CursorAdapters.

– jwei