blob: 20f8bbd59da55c8cf7b827400d8b74d3d24eb70e [file] [log] [blame]
page.title=Creating Lists
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<li><a href="#add-list">Add a List View</a></li>
<li><a href="#layout-impl">Create a Layout Implementation for List Items</a></li>
<li><a href="#layout-def">Create a Layout Definition for Items</a></li>
<li><a href="#adapter">Create an Adapter to Populate the List</a></li>
<li><a href="#adapter-listener">Associate the Adapter and Set a Click Listener</a></li>
<h2>You should also read</h2>
<li><a href="{@docRoot}design/wear/index.html">Android Wear Design Principles</a></li>
<p>Lists let users select an item from a set of choices easily on wearable devices. This lesson
shows you how to create lists in your Android Wear apps.</p>
<p>The Wearable UI Library includes the <code>WearableListView</code> class, which is a list
implementation optimized for wearable devices..</p>
<p class="note"><strong>Note:</strong> The <em>Notifications</em> sample in the Android SDK
demonstrates how to use <code>WearableListView</code> in your apps. This sample is located in
the <code>android-sdk/samples/android-20/wearable/Notifications</code> directory.</p>
<p>To create a list in your Android Wear apps:</p>
<li>Add a <code>WearableListView</code> element to your activity's layout definition.</li>
<li>Create a custom layout implementation for your list items.</li>
<li>Use this implementation to create a layout definition file for your list items.</li>
<div style="float:right;margin-left:25px;width:220px;margin-top:-25px">
<img src="{@docRoot}wear/images/06_uilib.png" width="200" height="200" alt=""/>
<p class="img-caption" style="text-align:center;margin-left:-10px"><strong>Figure 3:</strong>
A list view on Android Wear.</p>
<li>Create an adapter to populate the list.</li>
<li>Assign the adapter to the <code>WearableListView</code> element.</li>
<p>These steps are described in detail in the following sections.</p>
<h2 id="add-list">Add a List View</h2>
<p>The following layout adds a list view to an activity using a <code>BoxInsetLayout</code>, so
the list is displayed properly on both round and square devices:</p>
<h2 id="layout-impl">Create a Layout Implementation for List Items</h2>
<p>In many cases, each list item consists of an icon and a description. The
<em>Notifications</em> sample from the Android SDK implements a custom layout that extends
{@link android.widget.LinearLayout} to incorporate these two elements inside each list item.
This layout also implements the methods in the
<code>WearableListView.OnCenterProximityListener</code> interface
to change the color of the item's icon and fade the text in response to events from
<code>WearableListView</code> as the user scrolls through the list.</p>
public class WearableListItemLayout extends LinearLayout
implements WearableListView.OnCenterProximityListener {
private ImageView mCircle;
private TextView mName;
private final float mFadedTextAlpha;
private final int mFadedCircleColor;
private final int mChosenCircleColor;
public WearableListItemLayout(Context context) {
this(context, null);
public WearableListItemLayout(Context context, AttributeSet attrs) {
this(context, attrs, 0);
public WearableListItemLayout(Context context, AttributeSet attrs,
int defStyle) {
super(context, attrs, defStyle);
mFadedTextAlpha = getResources()
.getInteger(R.integer.action_text_faded_alpha) / 100f;
mFadedCircleColor = getResources().getColor(R.color.grey);
mChosenCircleColor = getResources().getColor(;
// Get references to the icon and text in the item layout definition
protected void onFinishInflate() {
// These are defined in the layout file for list items
// (see next section)
mCircle = (ImageView) findViewById(;
mName = (TextView) findViewById(;
public void onCenterPosition(boolean animate) {
((GradientDrawable) mCircle.getDrawable()).setColor(mChosenCircleColor);
public void onNonCenterPosition(boolean animate) {
((GradientDrawable) mCircle.getDrawable()).setColor(mFadedCircleColor);
<p>You can also create animator objects to enlarge the icon of the center item in the list. You can
use the <code>onCenterPosition()</code> and <code>onNonCenterPosition()</code> callback methods
in the <code>WearableListView.OnCenterProximityListener</code> interface to manage your
animators. For more information about animators, see
<a href="{@docRoot}guide/topics/graphics/prop-animation.html#object-animator">Animating with
<h2 id="layout-def">Create a Layout Definition for Items</h2>
<p>After you implement a custom layout for list items, you provide a layout definition file that
specifies the layout parameters of each of the components inside a list item. The following layout
definition uses the custom layout implementation from the previous section and defines an icon
and a text view whose IDs match those in the layout implementation class:</p>
<p class="code-caption">res/layout/list_item.xml</p>
<h2 id="adapter">Create an Adapter to Populate the List</h2>
<p>The adapter populates the <code>WearableListView</code> with content. The following simple
adapter populates the list with elements based on an array of strings:</p>
private static final class Adapter extends WearableListView.Adapter {
private String[] mDataset;
private final Context mContext;
private final LayoutInflater mInflater;
// Provide a suitable constructor (depends on the kind of dataset)
public Adapter(Context context, String[] dataset) {
mContext = context;
mInflater = LayoutInflater.from(context);
mDataset = dataset;
// Provide a reference to the type of views you're using
public static class ItemViewHolder extends WearableListView.ViewHolder {
private TextView textView;
public ItemViewHolder(View itemView) {
// find the text view within the custom item's layout
textView = (TextView) itemView.findViewById(;
// Create new views for list items
// (invoked by the WearableListView's layout manager)
public WearableListView.ViewHolder onCreateViewHolder(ViewGroup parent,
int viewType) {
// Inflate our custom layout for list items
return new ItemViewHolder(mInflater.inflate(R.layout.list_item, null));
// Replace the contents of a list item
// Instead of creating new views, the list tries to recycle existing ones
// (invoked by the WearableListView's layout manager)
public void onBindViewHolder(WearableListView.ViewHolder holder,
int position) {
// retrieve the text view
ItemViewHolder itemHolder = (ItemViewHolder) holder;
TextView view = itemHolder.textView;
// replace text contents
// replace list item's metadata
// Return the size of your dataset
// (invoked by the WearableListView's layout manager)
public int getItemCount() {
return mDataset.length;
<h2 id="adapter-listener">Associate the Adapter and Set a Click Listener</h2>
<p>In your activity, obtain a reference to the <code>WearableListView</code> element from
your layout, assign an instance of the adapter to populate the list, and set a click listener
to complete an action when the user selects a particular list item.</p>
public class WearActivity extends Activity
implements WearableListView.ClickListener {
// Sample dataset for the list
String[] elements = { "List Item 1", "List Item 2", ... };
protected void onCreate(Bundle savedInstanceState) {
// Get the list component from the layout of the activity
WearableListView listView =
(WearableListView) findViewById(;
// Assign an adapter to the list
listView.setAdapter(new Adapter(this, elements));
// Set a click listener
// WearableListView click listener
public void onClick(WearableListView.ViewHolder v) {
Integer tag = (Integer) v.itemView.getTag();
// use this data to complete some action ...
public void onTopEmptyRegionClick() {