The display of elements in a lists is a very common pattern in mobile applications. The user sees a list of items and can scroll through them. Typically the user interacts with the list via the ActionBar, for example via a refresh button.

Individual list item can be selected, this selection can update the ActionBar or can trigger a detailed screen for the selection.

Android provides the ListView class which is capable of displaying a scrollable list of items. These items can be of any type.

Adapters are used to provide the data to the ListView object. The adapter also defines how each row is the ListView is displayed.

The adapter is assigned to the ListView via the setAdapter method on the ListView object.

An adapter extend the BaseAdapter class. Android provides some standard adapters; the most important are ArrayAdapter and CursorAdapter.

ArrayAdapter can handle data based on Arrays or java.util.List.

SimpleCursorAdapter can handle database related data. This description focuses on the non database case.

The following listing shows a layout file with includes a ListView.

<ListView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/listview"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" /> 

This layout file, called activity_listviewexampleactivity.xml is used in the following code. This example shows the usage of the ListView view. It includes the removal of list items and uses animations for the removal.

package com.vogella.android.listview.withanimation;

public class ListViewExampleActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_listviewexampleactivity);

    final ListView listview = (ListView) findViewById(R.id.listview);
    String[] values = new String[] { "Android", "iPhone", "WindowsMobile",
        "Blackberry", "WebOS", "Ubuntu", "Windows7", "Max OS X",
        "Linux", "OS/2", "Ubuntu", "Windows7", "Max OS X", "Linux",
        "OS/2", "Ubuntu", "Windows7", "Max OS X", "Linux", "OS/2",
        "Android", "iPhone", "WindowsMobile" };

    final ArrayList<String> list = new ArrayList<String>();
    for (int i = 0; i < values.length; ++i) {
      list.add(values[i]);
    }
    final StableArrayAdapter adapter = new StableArrayAdapter(this,
        android.R.layout.simple_list_item_1, list);
    listview.setAdapter(adapter);

    listview.setOnItemClickListener(new AdapterView.OnItemClickListener() {

      @Override
      public void onItemClick(AdapterView<?> parent, final View view,
          int position, long id) {
        final String item = (String) parent.getItemAtPosition(position);
        view.animate().setDuration(2000).alpha(0)
            .withEndAction(new Runnable() {
              @Override
              public void run() {
                list.remove(item);
                adapter.notifyDataSetChanged();
                view.setAlpha(1);
              }
            });
      }

    });
  }

  private class StableArrayAdapter extends ArrayAdapter<String> {

    HashMap<String, Integer> mIdMap = new HashMap<String, Integer>();

    public StableArrayAdapter(Context context, int textViewResourceId,
        List<String> objects) {
      super(context, textViewResourceId, objects);
      for (int i = 0; i < objects.size(); ++i) {
        mIdMap.put(objects.get(i), i);
      }
    }

    @Override
    public long getItemId(int position) {
      String item = getItem(position);
      return mIdMap.get(item);
    }

    @Override
    public boolean hasStableIds() {
      return true;
    }

  }

} 

The ArrayAdapter class can handle any Java object as input. It maps the data of this input to a TextView in the layout. You can define one in the constructor otherwise the android.R.id.text1 ID will be used.

ArrayAdapter uses the toString() method of the data input object to determine the String which should be displayed.

The ArrayAdapter class allows to remove all elements in its underlying data structure with the clear() method call. You can then add new elements via the add() method or a Collection via the addAll() method.

You can also directly modify the underlying data structure and call the notifyDataSetChanged() method on the adapter to notify him about the changes in data.

To react to selections in the list set an OnItemClickListener to your ListView.

listView.setOnItemClickListener(new OnItemClickListener() {
  @Override
  public void onItemClick(AdapterView<?> parent, View view,
    int position, long id) {
    Toast.makeText(getApplicationContext(),
      "Click ListItem Number " + position, Toast.LENGTH_LONG)
      .show();
  }
}); 

Filtering and sorting is handled by the Adapter. You need to implement the logic in your custom Adapter implementation.

To control the data assignment and to support this assignment to several Views, you create your own Adapter implementation. For this you would extend an existing adapter implementations or by sub-classing the BaseAdapter class directly.

ListView calls the getView() method on the adapter for each data element. In this method the adapter determines the layout of the row and how the data is mapped to the Views in this layout.

This root of the layout is typically a ViewGroup (LayoutManager) and contains several other Views, e.g. an ImageView and a TextView.

Within the getView() method you would inflate an XML based layout and then set the values of the individual Views in the layout. For inflating an XML layout you can use the system service LayoutInflator. This service can get accessed via the activity or via the context.getSystemService(Context.LAYOUT_INFLATER_SERVICE) method call.

The individual elements in the layout can be found via the findViewById() method call.

The following shows an implementation of an own adapter. This adapter assumes that you have two png files (no.png and yes.png) in one of your res/drawable folders. The coding inflates an XML layout file, finds the relevant Views in the layout and sets their content based on the input data.

package de.vogella.android.listactivity;

import android.content.Context;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.ImageView;
import android.widget.TextView;

public class MySimpleArrayAdapter extends ArrayAdapter<String> {
  private final Context context;
  private final String[] values;

  public MySimpleArrayAdapter(Context context, String[] values) {
    super(context, R.layout.rowlayout, values);
    this.context = context;
    this.values = values;
  }

  @Override
  public View getView(int position, View convertView, ViewGroup parent) {
    LayoutInflater inflater = (LayoutInflater) context
        .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View rowView = inflater.inflate(R.layout.rowlayout, parent, false);
    TextView textView = (TextView) rowView.findViewById(R.id.label);
    ImageView imageView = (ImageView) rowView.findViewById(R.id.icon);
    textView.setText(values[position]);
    // Change the icon for Windows and iPhone
    String s = values[position];
    if (s.startsWith("iPhone")) {
      imageView.setImageResource(R.drawable.no);
    } else {
      imageView.setImageResource(R.drawable.ok);
    }

    return rowView;
  }
} 

An adapter can receive any Java object as input. In its getView() method it extracts the correct data from the data object and assigns this data to the views in the row which is representing the data.

The row can also contain views which interact with the underlying data model via the adapter. For example you can have a Checkbox in your row layout and if the Checkbox is selected, the underlying data is changed.

The notifyDataSetChanged() method on the adapter is called if the data has changed or if new data is available.

The notifyDataSetInvalidated() method is called if the data is not available anymore.

The ListActivity class which extends the activity class was designed to simplify the handling of ListViews.

It you do not assign a layout to a ListActivity it contains a default ListView and defines the onListItemClick() method for handling selection of list items. Internally the ListActivity registers an OnItemClickListener on the ListView.

ListActivity allows to set the adapter to the ListView via the setListAdapter() method.

package de.vogella.android.listactivity;

import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;

public class MyListActivity extends ListActivity {
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    String[] values = new String[] { "Android", "iPhone", "WindowsMobile",
        "Blackberry", "WebOS", "Ubuntu", "Windows7", "Max OS X",
        "Linux", "OS/2" };
    ArrayAdapter<String> adapter = new ArrayAdapter<String>(this,
        android.R.layout.simple_list_item_1, values);
    setListAdapter(adapter);
  }
} 

ListActivity does not require that you assign a layout to it via the setContentView() method, if you only want to show a ListView ListActivity contains by default a ListView.

In case you need to include more Views than a ListView in your ListActivity you can still assign a layout to your activity. In this case your layout must contain a ListView with the android:id attribute set to @android:id/list.

<ListView
  android:id="@android:id/list"
  android:layout_width="match_parent"
  android:layout_height="wrap_content" >
</ListView> 

If you use a View with the @android:id/empty ID in your layout, ListActivity will automatically show this View if the ListView is empty and hide it otherwise. For example you could display here an error message.

Every View which get inflated from an XML layout file will result in a Java object. Creating Java objects is expensive with regards to time and memory consumption.

In addition using the findViewById() method is relatively time consuming, even though it is not as bad as XML inflating.

This part describes how to reduce these operations to make your ListView faster. The default Android adapters like ArrayAdapter are already performance optimized.

A ListView typically contain more data then the number of displayed rows. If the user scrolls the list then rows and their associated Views will be scrolled out of the visible area. The Java objects which represents the rows can be reused for newly visible rows.

If Android determines that a View which represents a row is not visible anymore it allows the getView() method to reuse it via the convertView parameter.

A performance optimized adapter assigns the new data to the convertView. This avoids inflating an XML file and creating new Java objects.

In case no View is available for reuse, Android will pass null to the convertView parameter. Therefore the adapter implementation need to check for this.

The View Holder pattern allows to avoid the findViewById() method call for a reused convertView.

A ViewHolder class is a static inner class in your adapter which hold references to the relevant Views in your layout. This reference is assigned to the View which represent the row layout as a tag via the setTag() method.

If we receive a convertView object, we can get the instance of the ViewHolder via the getTag() method and assign the new attributes to the Views via the ViewHolder reference.

While this sounds complex this is approx. 15 % faster then using the findViewById() method.

The following code shows a performance optimized adapter implementation which reuses existing views and implements the holder pattern.

package de.vogella.android.listactivity;

import android.app.Activity;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.ImageView;
import android.widget.TextView;

public class MyPerformanceArrayAdapter extends ArrayAdapter<String> {
  private final Activity context;
  private final String[] names;

  static class ViewHolder {
    public TextView text;
    public ImageView image;
  }

  public MyPerformanceArrayAdapter(Activity context, String[] names) {
    super(context, R.layout.rowlayout, names);
    this.context = context;
    this.names = names;
  }

  @Override
  public View getView(int position, View convertView, ViewGroup parent) {
    View rowView = convertView;
    if (rowView == null) {
      LayoutInflater inflater = context.getLayoutInflater();
      rowView = inflater.inflate(R.layout.rowlayout, null);
      ViewHolder viewHolder = new ViewHolder();
      viewHolder.text = (TextView) rowView.findViewById(R.id.TextView01);
      viewHolder.image = (ImageView) rowView
          .findViewById(R.id.ImageView01);
      rowView.setTag(viewHolder);
    }

    ViewHolder holder = (ViewHolder) rowView.getTag();
    String s = names[position];
    holder.text.setText(s);
    if (s.startsWith("Windows7") || s.startsWith("iPhone")
        || s.startsWith("Solaris")) {
      holder.image.setImageResource(R.drawable.no);
    } else {
      holder.image.setImageResource(R.drawable.ok);
    }

    return rowView;
  }
} 

Frequently you need to select items in your ListView. As the row of the ListView are getting recycled you cannot store the selection on the View level.

Selection is just one possible example but you can imange other interaction between your row and model.

To persist the selection you have to update your data model with the selected state.

To update the data model in your ListView you define your own Adapter class. In this adapter class you attach a listener to the View which is responsible for selecting the model element. If selected you update the state in the model which you can add as a tag to the View to have access to it.

The following example demonstrates how to use standard Java object and how to interact from the Views with the model.

Continue to use the de.vogella.android.listactivity project.

Create the following Model which hold the name and the information if this element is currently selected.

package de.vogella.android.listactivity;

public class Model {

  private String name;
  private boolean selected;

  public Model(String name) {
    this.name = name;
    selected = false;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public boolean isSelected() {
    return selected;
  }

  public void setSelected(boolean selected) {
    this.selected = selected;
  }

} 

Create the following new layout file called rowbuttonlayout.xml.

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" >

    <TextView
        android:id="@+id/label"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@+id/label"
        android:textSize="30px" >
    </TextView>

    <CheckBox
        android:id="@+id/check"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentRight="true"
        android:layout_marginLeft="4px"
        android:layout_marginRight="10px" >
    </CheckBox>

</RelativeLayout> 

Create the following Adapter. This adapter adds a listener on the Checkbox view. If the checkbox is selected the underlying data of the model is changed. Checkbox gets the corresponding model element assigned via the getTag() method.

package de.vogella.android.listactivity;

import java.util.List;

import android.app.Activity;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.CheckBox;
import android.widget.CompoundButton;
import android.widget.TextView;

public class InteractiveArrayAdapter extends ArrayAdapter<Model> {

  private final List<Model> list;
  private final Activity context;

  public InteractiveArrayAdapter(Activity context, List<Model> list) {
    super(context, R.layout.rowbuttonlayout, list);
    this.context = context;
    this.list = list;
  }

  static class ViewHolder {
    protected TextView text;
    protected CheckBox checkbox;
  }

  @Override
  public View getView(int position, View convertView, ViewGroup parent) {
    View view = null;
    if (convertView == null) {
      LayoutInflater inflator = context.getLayoutInflater();
      view = inflator.inflate(R.layout.rowbuttonlayout, null);
      final ViewHolder viewHolder = new ViewHolder();
      viewHolder.text = (TextView) view.findViewById(R.id.label);
      viewHolder.checkbox = (CheckBox) view.findViewById(R.id.check);
      viewHolder.checkbox
          .setOnCheckedChangeListener(new CompoundButton.OnCheckedChangeListener() {

            @Override
            public void onCheckedChanged(CompoundButton buttonView,
                boolean isChecked) {
              Model element = (Model) viewHolder.checkbox
                  .getTag();
              element.setSelected(buttonView.isChecked());

            }
          });
      view.setTag(viewHolder);
      viewHolder.checkbox.setTag(list.get(position));
    } else {
      view = convertView;
      ((ViewHolder) view.getTag()).checkbox.setTag(list.get(position));
    }
    ViewHolder holder = (ViewHolder) view.getTag();
    holder.text.setText(list.get(position).getName());
    holder.checkbox.setChecked(list.get(position).isSelected());
    return view;
  }
} 

Finally change your activity to the following.

package de.vogella.android.listactivity;

import java.util.ArrayList;
import java.util.List;

import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;

public class MyList extends ListActivity {

  
/** Called when the activity is first created. */
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    // Create an array of Strings, that will be put to our ListActivity
    ArrayAdapter<Model> adapter = new InteractiveArrayAdapter(this,
        getModel());
    setListAdapter(adapter);
  }

  private List<Model> getModel() {
    List<Model> list = new ArrayList<Model>();
    list.add(get("Linux"));
    list.add(get("Windows7"));
    list.add(get("Suse"));
    list.add(get("Eclipse"));
    list.add(get("Ubuntu"));
    list.add(get("Solaris"));
    list.add(get("Android"));
    list.add(get("iPhone"));
    // Initially select one of the items
    list.get(1).setSelected(true);
    return list;
  }

  private Model get(String s) {
    return new Model(s);
  }

} 

If you start your app you should be able to flag items. These changes will be reflected in your model.

You can also add a LongItemClickListener to the View. For this receive the ListView via the getListVIew() method and set the LongItemClickListener via the setOnItemLongClickListener() method.

package de.vogella.android.listactivity;

import android.app.ListActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.AdapterView;
import android.widget.AdapterView.OnItemLongClickListener;
import android.widget.ArrayAdapter;
import android.widget.ListView;
import android.widget.Toast;

public class MyList extends ListActivity {

  
/** Called when the activity is first created. */
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    // Create an array of Strings, that will be put to our ListActivity
    String[] names = new String[] { "Linux", "Windows7", "Eclipse", "Suse",
        "Ubuntu", "Solaris", "Android", "iPhone" };
    ArrayAdapter<String> adapter = new MyPerformanceArrayAdapter(this, names);
    setListAdapter(adapter);
    ListView list = getListView();
    list.setOnItemLongClickListener(new OnItemLongClickListener() {

      @Override
      public boolean onItemLongClick(AdapterView<?> parent, View view,
          int position, long id) {
        Toast.makeText(MyList.this,
            "Item in position " + position + " clicked",
            Toast.LENGTH_LONG).show();
        // Return true to consume the click event. In this case the
        // onListItemClick listener is not called anymore.
        return true;
      }
    });
  }

  @Override
  protected void onListItemClick(ListView l, View v, int position, long id) {
    super.onListItemClick(l, v, position, id);
    // Get the item that was clicked
    Object o = this.getListAdapter().getItem(position);
    String keyword = o.toString();
    Toast.makeText(this, "You selected: " + keyword, Toast.LENGTH_SHORT)
        .show();

  }

} 

To get the selected item(s) of a ListView use the getCheckedItemPosition() for a single selection method or listView.getCheckedItemPositions() for multiple selections. . If you have stable ID you could also use the getCheckedItemIds() method to get the selected IDs.

By default a ListView supports only the single selection of a row, but you can activate multi selection via a flag. See the following snippets for examples.

package de.vogella.android.listactivity;

import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class MyList extends ListActivity {

  
/** Called when the activity is first created. */
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    // Create an array of Strings, that will be put to our ListActivity
    String[] names = new String[] { "Linux", "Windows7", "Eclipse", "Suse",
        "Ubuntu", "Solaris", "Android", "iPhone", "Linux", "Windows7",
        "Eclipse", "Suse", "Ubuntu", "Solaris", "Android", "iPhone" };
    setListAdapter(new ArrayAdapter<String>(this,
        android.R.layout.simple_list_item_multiple_choice,
        android.R.id.text1, names));
    ListView listView = getListView();
    listView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE);
  }

} 

package de.vogella.android.listactivity;

import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class MyList extends ListActivity {

  
/** Called when the activity is first created. */
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    // Create an array of Strings, that will be put to our ListActivity
    String[] names = new String[] { "Linux", "Windows7", "Eclipse", "Suse",
        "Ubuntu", "Solaris", "Android", "iPhone", "Linux", "Windows7",
        "Eclipse", "Suse", "Ubuntu", "Solaris", "Android", "iPhone" };
    setListAdapter(new ArrayAdapter<String>(this,
        android.R.layout.simple_list_item_single_choice,
        android.R.id.text1, names));
    ListView listView = getListView();
    listView.setChoiceMode(ListView.CHOICE_MODE_SINGLE);
  }

} 

The ExpandableListView is similar to ListView but allow you to define groups and details for this group. ExpandableListView expects and adapter of type BaseExpandableListAdapter.

You can of course put arbitrary Views elements around your ListView. For example you can define a layout with two TextViews and a ListView between them. In this case the two TextViews will always be visible above the List (header) and the other will be visible below the ListView. If you want to display a list header or list footer only at the see the beginning or end of the list you can use the setHeaderView() method or setFooterView() method on ListView.

package de.vogella.android.listactivity;

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

public class MyList extends ListActivity {

  
/** Called when the activity is first created. */
  public void onCreate(Bundle icicle) {
    super.onCreate(icicle);
    // Create an array of Strings, that will be put to our ListActivity
    String[] names = new String[] { "Linux", "Windows7", "Eclipse", "Suse",
        "Ubuntu", "Solaris", "Android", "iPhone", "Linux", "Windows7",
        "Eclipse", "Suse", "Ubuntu", "Solaris", "Android", "iPhone" };
    View header = getLayoutInflater().inflate(R.layout.header, null);
    View footer = getLayoutInflater().inflate(R.layout.footer, null);
    ListView listView = getListView();
    listView.addHeaderView(header);
    listView.addFooterView(footer);
    setListAdapter(new ArrayAdapter<String>(this,
        android.R.layout.simple_list_item_single_choice,
        android.R.id.text1, names));

  }
} 

Source Code of Examples

Source code for an ListView which uses 3D effets

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java and compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put everything you have under distributed version control system