Android ListView tutorial

  • Written by  Clive

Android ListView Tutorial

What’s a ListView

A ListView displays items in a vertical, scrolling list. It contains a number of views, one for each item in the list. Here’s an example:

Android ListView list 

A list of countries

Where do the list items come from?

You could get the list items from a number of sources, for example, from an array or from a database query.

Use an Adapter to load the list

The adapter pulls the items out of a data source, an array for example, and then converts each item into a view which it then inserts into the ListView.

Where is the list displayed?

You use a ListView to display the list. You can use your own layout which you can customise to suite your needs. For example you could use your own colours, text sizes, fonts, etc.

You can also use the Android system's default list layouts. This is the easiest way and the way I have chosen for this tutorial. 

Coding the ListView

The MainActivity

We have one activity in this app, the MainActivity. You’ll note that it extends the ListActivity class which enables it to display a list of items in its own ListView object. You don’t need to use a layout of your own hence, there is no setContentView() where you assign it a layout to use.

The layout

You don’t need a layout as we use the Android system's simple_list_item_1 layout.

The arrays

First off, let’s get our array of items that we would like to display in the list. I have two arrays that we can choose from. The first is an array of countries that I declare in the MainActivity. This is what it looks like:

String[]countryNamesArray = {"South Africa", "Namibia", "Zimbabwe", "Botswana", "Zambia", "Kenya", "Mali", "Sudan", "Nigeria"};

I also have an array in the strings.xml resource file. This is what that array looks like:

Android ListView String array

So in my code, I can choose which of the arrays to use. I use a boolean object, isColorArray in an if else statement. If it’s true then I use the colours array else I use the countries array.

The adapter

The adapter is the bridge between the array and the list view. I create the adapter object with this line:

ArrayAdapter myArrayAdapter;

Then in the if else statement I create a new adapter for each of the if else options. These two adapters are exactly the same except for the different arrays fed to them as parameters.

The ArrayAdapter constructor has this format:

ArrayAdapter(context, resource, array)

I access the resource array like this:

getResources().getStringArray(R.array.myResourceStringArray)

  • getResources() – gets an instance of the resources for this app
  • getStringArray() – returns the string array associated with the resource ID passed as a parameter
  • R.array.myResourceStringArray – this is the resource ID for the array in the strings resource file

Then we set up the adapter and pass it the relevant array to display in the list.

Handling the clicks

So you’ve got the app running and the list displays as expected but what now? What do we do if someone clicks on an item?

Use the onListItemClick() method to process the clicks. This method receives 4 parameters:

  • ListView – the ListView containing the item views
  • View – the specific item view that was selected
  • Position – the position of the selected item in the array. Remember that the array is zero indexed, so the first item in the array is at position 0
  • Id – the id of the selected item. Not of importance for our tutorial but is important when using data retrieved from a database as you can use the id (which is the id of the row containing the item in the database) to retrieve the item from the database

Toasting the result

I use Toast to display the selected item. If we’re using the colour array then we get the colour in the array at the index represented by position. Similarly with the countries array. This is what the code looks like:

Android's ListView application code

You may want to have a look at our Expandable Lists tutorial where we show you how to display two-level lists.

This project was created using Android Studio. You can download the project files and import them into Android Studio.