The following is the first few sections of a chapter from The Busy Coder's Guide to Android Development, plus headings for the remaining major sections, to give you an idea about the content of the chapter.


AdapterViews and Adapters

If you want the user to choose something out of a collection of somethings, you could use a bunch of RadioButton widgets. However, Android has a series of more flexible widgets than that, ones that this book will refer to as “selection widgets”.

These include:

and many more.

At their core, these are ordinary widgets. You will find them in your tool palette of your IDE’s graphical layout editor, and can drag them and position them as you see fit.

The key is that these all have a common superclass: AdapterView, so named because they partner with objects implementing the Adapter interface to determine what choices are available for the user to choose from.

Adapting to the Circumstances

An Adapter is your bridge between your model data and that data’s visual representation in the AdapterView:

Android ships with several Adapter classes ready for your use, where the different adapter classes are designed to “adapt” different sorts of collections (e.g., arrays versus results of database queries). Android also has a BaseAdapter class that can serve as the foundation for your own Adapter implementation, if you need to “adapt” a collection of data that does not fit any of the Adapter classes supplied by Android.

Using ArrayAdapter

The easiest adapter to use is ArrayAdapter — all you need to do is wrap one of these around a Java array or java.util.List instance, and you have a fully-functioning adapter:

String[] items={"this", "is", "a", "really", "silly", "list"};
new ArrayAdapter<String>(this,
                         android.R.layout.simple_list_item_1,
                         items);

One flavor of the ArrayAdapter constructor takes three parameters:

  1. The Context to use (typically this will be your activity instance)
  2. The resource ID of a view to use (such as a built-in system resource ID, as shown above)
  3. The actual array or list of items to show

By default, the ArrayAdapter will invoke toString() on the objects in the list and wrap each of those strings in the view designated by the supplied resource. android.R.layout.simple_list_item_1 simply turns those strings into TextView objects. Those TextView widgets, in turn, will be shown in the list or spinner or whatever widget uses this ArrayAdapter. If you want to see what android.R.layout.simple_list_item_1 looks like, you can find a copy of it in your SDK installation — just search for simple_list_item_1.xml.

We will see in a later section how to subclass an Adapter and override row creation, to give you greater control over how rows and cells appear.

Lists of Naughty and Nice

The classic listbox widget in Android is known as ListView. Include one of these in your layout, invoke setAdapter() to supply your data and child views, and attach a listener via setOnItemSelectedListener() to find out when the selection has changed. With that, you have a fully-functioning listbox.

However, if your activity is dominated by a single list, you might well consider creating your activity as a subclass of ListActivity, rather than the regular Activity base class. If your main view is just the list, you do not even need to supply a layout — ListActivity will construct a full-screen list for you. If you do want to customize the layout, you can, so long as you identify your ListView as @android:id/list, so ListActivity knows which widget is the main list for the activity.

For example, here is a layout pulled from the Selection/List sample project:

<?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" >
  <TextView
    android:id="@+id/selection"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"/>
  <ListView
    android:id="@android:id/list"
    android:layout_width="match_parent" 
    android:layout_height="match_parent"
    />
</LinearLayout>

It is just a list with a label on top to show the current selection.

The Java code to configure the list and connect the list with the label is:

package com.commonsware.android.list;

import android.app.ListActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.ArrayAdapter;
import android.widget.ListView;
import android.widget.TextView;

public class ListViewDemo extends ListActivity {
  private TextView selection;
  private static final String[] items={"lorem", "ipsum", "dolor",
          "sit", "amet",
          "consectetuer", "adipiscing", "elit", "morbi", "vel",
          "ligula", "vitae", "arcu", "aliquet", "mollis",
          "etiam", "vel", "erat", "placerat", "ante",
          "porttitor", "sodales", "pellentesque", "augue", "purus"};
  
  @Override
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    setContentView(R.layout.main);
    setListAdapter(new ArrayAdapter<String>(this,
                        android.R.layout.simple_list_item_1,
                        items));
    selection=(TextView)findViewById(R.id.selection);
  }
  
  @Override
  public void onListItemClick(ListView parent, View v, int position,
                                long id) {
    selection.setText(items[position]);
  }
}

With ListActivity, you can set the list adapter via setListAdapter() — in this case, providing an ArrayAdapter wrapping an array of Latin strings. To find out when the list selection changes, override onListItemClick() and take appropriate steps based on the supplied child view and position (in this case, updating the label with the text for that position).

The results?

ListViewDemo, After User Taps on consecteteur
Figure 176: ListViewDemo, After User Taps on “consecteteur”

The second parameter to our ArrayAdapterandroid.R.layout.simple_list_item_1 — controls what the rows look like. The value used in the preceding example provides the standard Android list row: a big font with lots of padding to offer a large touch target for the user.

Clicks versus Selections

The preview of this section was stepped on by Godzilla.

Spin Control

The preview of this section may contain nuts.

Grid Your Lions (Or Something Like That…)

The preview of this section is [REDACTED].

Fields: Now With 35% Less Typing!

The preview of this section was abducted by space aliens.

Customizing the Adapter

The preview of this section is in an invisible, microscopic font.

Visit the Trails!

The preview of this section was eaten by a grue.