Implementing a Horizontal ListView Guide

Overview

One common challenge on Android that often arises is the need to create a horizontal ListView that works like a regular ListView but scrolls horizontally instead. This is common for news, images, etc.

Horizontal ListView

Note: This guide predates RecyclerView, which is now the officially supported way to build a horizontally scrolling list — attach a LinearLayoutManager with HORIZONTAL orientation, e.g. new LinearLayoutManager(context, LinearLayoutManager.HORIZONTAL, false). See Using the RecyclerView for a full guide. The TwoWayView library used below was archived by its owner on December 1, 2017 and should not be used in new projects; the rest of this page is kept as historical reference.

When this guide was originally written, there was no “canonical” officially supported solution for this. Instead all that existed was a series of half-baked unfinished libraries. This made developing a Horizontal ListView more challenging than you would initially suspect.

This guide is a step-by-step walkthrough of implementing a Horizontal ListView using the third-party libraries available at the time.

Introducing TwoWayView

Of the third-party libraries that existed for a Horizontal ListView, the most complete and usable was called TwoWayView (archived by its owner on December 1, 2017, with its last commit to master in April 2015). Even though there was a warning about this not being production ready, at the time it was probably the best view short of implementing one yourself.

Installing TwoWayView

Download TwoWayView as a ZIP and then install it as a library project. Note: If you have any trouble importing the version downloaded, try this modified version compatible with Eclipse.

Adding TwoWayView to Layout

First, let’s add a style indicating the orientation of the ListView (horizontal or vertical) in res/values/styles.xml:

<style name="TwoWayView">
    <item name="android:orientation">horizontal</item>
</style>

In your Layout XML, use the following code to add the TwoWayView:

<org.lucasr.twowayview.TwoWayView 
     xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     android:id="@+id/lvItems"
     style="@style/TwoWayView"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:drawSelectorOnTop="false"
     tools:context=".MainActivity" />

Populating Data into TwoWayView

Now we can populate data into the TwoWayView much like any ListView as described in the Adapter guide. For example, we might create a very simple array of items:

ArrayList<String> items = new ArrayList<String>();
items.add("Item 1");
items.add("Item 2");
items.add("Item 3");
items.add("Item 4");
// ...

and then construct a super simple ArrayAdapter and populate the TwoWayView with:

Take into account that the layout_width param is defined as match_parent in simple_list_item_1, so if you use it, the list will show just the first element. So, please create a new layout like this:

<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@android:id/text1"
    android:layout_width="wrap_content"
    android:layout_height="match_parent"
    android:textAppearance="?android:attr/textAppearanceListItemSmall"
    android:gravity="center_vertical" />

Name it as simple_list_item_1 and use the following code to test it:

ArrayAdapter<String> aItems = new ArrayAdapter<String>(this, R.layout.simple_list_item_1, items);
TwoWayView lvTest = (TwoWayView) findViewById(R.id.lvItems);
lvTest.setAdapter(aItems);

The view will now present the items horizontally like:

View Screen

Conclusion

Here we have implemented a simple Horizontal ListView using a popular third-party library. Obviously this example is very simple but you can follow the steps in the the Adapter guide to create arbitrarily complex list items.