Linux.com

Home Learn Linux Linux Documentation Android Programming for Beginners: User Menus

Android Programming for Beginners: User Menus

In our previous Android coding tutorials (part 1, part 2), you set up your dev environment, built a basic app, and then improved it by adding a menu and a second Activity. In this tutorial we're going to look at a very handy part of the Android API: ListView, ListActivity, and the associated methods which give you an easy way to show the user a list and then act when they click a list item.

Creating a ListView

A very common pattern in an Android activity is showing a list of items for the user to select from. The Android API provides the ListView and ListActivity classes to help out with this. Carrying on with the Countdown app from previous tutorials, we'll list a few sample countdown times for the user to select from to set the timer.

If all you want is a List, ListActivity will set your View up for you automatically; no need to write any XML at all. So onCreate()can be very simple:

public class CountdownActivity extends ListActivity {
  public void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	
    Integer[] values = new Integer[] { 5, 10, 15, 20, 25, 30, 45, 60 }; 
    ArrayAdapter adapter = 
        new ArrayAdapter(this, android.R.layout.simple_list_item_1, 
                                  values);
    setListAdapter(adapter);
  }
}

CountdownActivity now extends ListActivity. ListActivity does a lot of the preparation work for you, so to show a list, you just need to create an array of values to show, hook it up to an ArrayAdapter, and set the ArrayAdapter as the ListActivity's ListAdapter. The ArrayAdapter has three parameters:

  1. The current context (this);
  2. The layout resource defining how each array element should be displayed;
  3. The array itself (values).

For the layout resource, we're use a standard Android resource, android.R.layout.simple_list_item_1. But you could create your own, or use another of the standard layout items (of which more later). You can also take a look at the XML of the standard resources.

The problem with this layout is that it only shows a list. We want to be able to see the countdown and the start button as well. This means setting up our own XML layout, rather than relying on ListActivity to generate its own layout. Add this to your XML, below the TextView and the Button:

<ListView
          android:id="@android:id/list"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content" 
          android:layout_below="@+id/startbutton" />

It's important that the ListView should have the ID @android:id/list. This is what enables the ListActivity to do its magic without you explicitly setting up the List.

android 3 listchoice

Now go back to CountdownActivity.onCreate(), and put your previous display and button setup code back in, after the ListView setup:

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
		
  Integer[] values .... etc ...
  [ ... ]
  setListAdapter(adapter);
  setContentView(R.layout.activity_main);
  countdownDisplay = (TextView) findViewById(R.id.time_display_box);
  Button startButton = (Button) findViewById(R.id.startbutton);
  [ .... etc .... ]
}

Again, it's important that you set up the ListView first, before setContentView(), or it won't work properly. Recompile and run, and you'll see the list appear below the text and button. What you won't see, though, is anything happening when you click the list elements. The next section will tackle that problem.

One final note: you can also set up an empty element in the layout, which will display if and only if the ListView is empty. Add this to your XML:

<TextView 
       android:id="@android:id/empty" 
       android:layout_width="wrap_content" 
       android:layout_height="wrap_content" 
       android:layout_centerHorizontal="true" 
       android:layout_below="@+id/startbutton" 
       android:text="@string/empty_list" /> 

(You'll need to set up the string value in res/values/strings.xml, too). Now replace the array declaration line in CountdownActivity.onCreate()with this one:

Integer[] values = new Integer[] { };

Compile and run, and you'll see the empty text displayed, and no list. Put the array declaration back how it was, compile and run again, and the list shows, but no text. In our app this isn't particularly useful, but if you were populating the array from elsewhere in your code, it's a neat trick to have available.

Clicking on List elements

Now we have the List set up, we need to make it do something when you click on a list element. Specifically, it should set the countdown seconds to the new value, and change the display. Happily, Android has a straightforward API for this, too:

ListView list = getListView();
list.setOnItemClickListener(new OnItemClickListener() {
  public void onItemClick(AdapterView<?> parent, View view, int position, 
                          long id ) {
    countdownSeconds = (Integer) getListAdapter().getItem(position);
   	countdownDisplay.setText(Long.toString(countdownSeconds));
  }
});

This is all pretty self-explanatory! We grab the ListView, set its OnItemClickListener, and create an onItemClick() method for the Listener. As you can see here, onItemClick()has access to the position in the List of the item you clicked on. So we can grab the ListAdapter, get the item from that position, and then cast the value to an Integer. Save and run, and you have a list of values to set your timer.

Changing the List's appearance

Earlier, we mentioned the other standard layouts available. If you switch simple_list_item_1 to simple_list_item_single_choice, and rerun your code, you'll see that you get a selection indicator next to your list items. However, when you click it, the countdown value changes, but the selection indicator doesn't do anything. To make this work, you need to change your ListView, too. Add this attribute in your XML:

<ListView .... 
          android:choiceMode="singleChoice" 
... >

Run it again, and the selection indicator does its job. If you were using a ListActivity without an XML file, you could do this with a line of code in your app:

getListView().setChoiceMode(ListView.CHOICE_MODE_SINGLE); 

Conclusion

There are lots of situations in apps where you might want to show the user a list. ListView and ListActivity make that very easy, and as shown just above, there are plenty of ways to improve the UI experience. You could also look at providing a context menu (in these tutorials we've only used the options menu so far) when the user long-clicks on a list item. Or you could look at some form of back-end data storage, and allow the user to add and edit their own list items, so they have a list of countdown times that they regularly use. As ever, keep playing with the code and see where it takes you!

For more Android programming training resources, please visit the Linux training website.

 

Comments

Subscribe to Comments Feed
  • DavidChipman Said:

    I see you still persist in not including the required java import statements at the top of the java files. I suppose your laziness could be explained by the fact that Eclipse will offer to add them for you. But really, as code examples, these suck big time! Some beginners tutorial! Idiot!

  • Cedric RAVALEC Said:

    You can use AndroVM for testing your app.

  • Poul Said:

    can you create a special place on the menu or in site where will all the tutorials for android? Because now is a little chaotic part 1, part 2 now User Menus,... For example: Linux Documentation>android-part1 -part2...

  • Al Said:

    This tutorial could use some serious help. You consistently just glaze over the details that a beginner ready a tutorial would need to complete the sample app. It just baffles me that you would go through all of the work to put this tutorial together and only do it 90%. Add in the missing pieces, some source code, and maybe connect the dots a little better and I WOULD give this 5 stars!

Upcoming Linux Foundation Courses

  1. LFD211 Introduction to Linux for Developers
    08 Dec » 09 Dec - Virtual
    Details
  2. LFS220 Linux System Administration
    08 Dec » 11 Dec - Virtual
    Details
  3. LFS520 OpenStack Cloud Architecture and Deployment
    08 Dec » 11 Dec - Virtual
    Details

View All Upcoming Courses

Become an Individual Member
Check out the Friday Funnies

Sign Up For the Linux.com Newsletter


Who we are ?

The Linux Foundation is a non-profit consortium dedicated to the growth of Linux.

More About the foundation...

Frequent Questions

Join / Linux Training / Board