1page.title=Creating Lists
2
3@jd:body
4
5<div id="tb-wrapper">
6<div id="tb">
7<h2>This lesson teaches you to</h2>
8<ol>
9  <li><a href="#add-list">Add a List View</a></li>
10  <li><a href="#layout-impl">Create a Layout Implementation for List Items</a></li>
11  <li><a href="#layout-def">Create a Layout Definition for Items</a></li>
12  <li><a href="#adapter">Create an Adapter to Populate the List</a></li>
13  <li><a href="#adapter-listener">Associate the Adapter and Set a Click Listener</a></li>
14</ol>
15<h2>You should also read</h2>
16<ul>
17  <li><a href="{@docRoot}design/wear/index.html">Android Wear Design Principles</a></li>
18</ul>
19</div>
20</div>
21
22
23<p>Lists let users select an item from a set of choices easily on wearable devices. This lesson
24shows you how to create lists in your Android Wear apps.</p>
25
26<p>The Wearable UI Library includes the <code>WearableListView</code> class, which is a list
27implementation optimized for wearable devices..</p>
28
29<p class="note"><strong>Note:</strong> The <em>Notifications</em> sample in the Android SDK
30demonstrates how to use <code>WearableListView</code> in your apps. This sample is located in
31the <code>android-sdk/samples/android-20/wearable/Notifications</code> directory.</p>
32
33<p>To create a list in your Android Wear apps:</p>
34
35<ol>
36<li>Add a <code>WearableListView</code> element to your activity's layout definition.</li>
37<li>Create a custom layout implementation for your list items.</li>
38<li>Use this implementation to create a layout definition file for your list items.</li>
39<div style="float:right;margin-left:25px;width:220px;margin-top:-25px">
40<img src="{@docRoot}wear/images/06_uilib.png" width="200" height="200" alt=""/>
41<p class="img-caption" style="text-align:center;margin-left:-10px"><strong>Figure 3:</strong>
42A list view on Android Wear.</p>
43</div>
44<li>Create an adapter to populate the list.</li>
45<li>Assign the adapter to the <code>WearableListView</code> element.</li>
46</ol>
47
48<p>These steps are described in detail in the following sections.</p>
49
50
51<h2 id="add-list">Add a List View</h2>
52
53<p>The following layout adds a list view to an activity using a <code>BoxInsetLayout</code>, so
54the list is displayed properly on both round and square devices:</p>
55
56<pre>
57&lt;android.support.wearable.view.BoxInsetLayout
58    xmlns:android="http://schemas.android.com/apk/res/android"
59    xmlns:app="http://schemas.android.com/apk/res-auto"
60    android:background="@drawable/robot_background"
61    android:layout_height="match_parent"
62    android:layout_width="match_parent">
63
64    &lt;FrameLayout
65        android:id="@+id/frame_layout"
66        android:layout_height="match_parent"
67        android:layout_width="match_parent"
68        app:layout_box="left|bottom|right">
69
70        &lt;<strong>android.support.wearable.view.WearableListView</strong>
71            android:id="@+id/wearable_list"
72            android:layout_height="match_parent"
73            android:layout_width="match_parent">
74        &lt;/android.support.wearable.view.WearableListView>
75    &lt;/FrameLayout>
76&lt;/android.support.wearable.view.BoxInsetLayout>
77</pre>
78
79
80<h2 id="layout-impl">Create a Layout Implementation for List Items</h2>
81
82<p>In many cases, each list item consists of an icon and a description. The
83<em>Notifications</em> sample from the Android SDK implements a custom layout that extends
84{@link android.widget.LinearLayout} to incorporate these two elements inside each list item.
85This layout also implements the methods in the
86<code>WearableListView.OnCenterProximityListener</code> interface
87to change the color of the item's icon and fade the text in response to events from
88<code>WearableListView</code> as the user scrolls through the list.</p>
89
90<pre>
91public class WearableListItemLayout extends LinearLayout
92             implements WearableListView.OnCenterProximityListener {
93
94    private ImageView mCircle;
95    private TextView mName;
96
97    private final float mFadedTextAlpha;
98    private final int mFadedCircleColor;
99    private final int mChosenCircleColor;
100
101    public WearableListItemLayout(Context context) {
102        this(context, null);
103    }
104
105    public WearableListItemLayout(Context context, AttributeSet attrs) {
106        this(context, attrs, 0);
107    }
108
109    public WearableListItemLayout(Context context, AttributeSet attrs,
110                                  int defStyle) {
111        super(context, attrs, defStyle);
112
113        mFadedTextAlpha = getResources()
114                         .getInteger(R.integer.action_text_faded_alpha) / 100f;
115        mFadedCircleColor = getResources().getColor(R.color.grey);
116        mChosenCircleColor = getResources().getColor(R.color.blue);
117    }
118
119    // Get references to the icon and text in the item layout definition
120    &#64;Override
121    protected void onFinishInflate() {
122        super.onFinishInflate();
123        // These are defined in the layout file for list items
124        // (see next section)
125        mCircle = (ImageView) findViewById(R.id.circle);
126        mName = (TextView) findViewById(R.id.name);
127    }
128
129    &#64;Override
130    public void onCenterPosition(boolean animate) {
131        mName.setAlpha(1f);
132        ((GradientDrawable) mCircle.getDrawable()).setColor(mChosenCircleColor);
133    }
134
135    &#64;Override
136    public void onNonCenterPosition(boolean animate) {
137        ((GradientDrawable) mCircle.getDrawable()).setColor(mFadedCircleColor);
138        mName.setAlpha(mFadedTextAlpha);
139    }
140}
141</pre>
142
143<p>You can also create animator objects to enlarge the icon of the center item in the list. You can
144use the <code>onCenterPosition()</code> and <code>onNonCenterPosition()</code> callback methods
145in the <code>WearableListView.OnCenterProximityListener</code> interface to manage your
146animators. For more information about animators, see
147<a href="{@docRoot}guide/topics/graphics/prop-animation.html#object-animator">Animating with
148ObjectAnimator</a>.</p>
149
150
151<h2 id="layout-def">Create a Layout Definition for Items</h2>
152
153<p>After you implement a custom layout for list items, you provide a layout definition file that
154specifies the layout parameters of each of the components inside a list item. The following layout
155definition uses the custom layout implementation from the previous section and defines an icon
156and a text view whose IDs match those in the layout implementation class:</p>
157
158<p class="code-caption">res/layout/list_item.xml</p>
159
160<pre>
161&lt;com.example.android.support.wearable.notifications.WearableListItemLayout
162    xmlns:android="http://schemas.android.com/apk/res/android"
163    android:gravity="center_vertical"
164    android:layout_width="match_parent"
165    android:layout_height="80dp">
166    &lt;ImageView
167        android:id="@+id/circle"
168        android:layout_height="20dp"
169        android:layout_margin="16dp"
170        android:layout_width="20dp"
171        android:src="@drawable/wl_circle"/>
172    &lt;TextView
173        android:id="@+id/name"
174        android:gravity="center_vertical|left"
175        android:layout_width="wrap_content"
176        android:layout_marginRight="16dp"
177        android:layout_height="match_parent"
178        android:fontFamily="sans-serif-condensed-light"
179        android:lineSpacingExtra="-4sp"
180        android:textColor="@color/text_color"
181        android:textSize="16sp"/>
182&lt;/com.example.android.support.wearable.notifications.WearableListItemLayout>
183</pre>
184
185
186<h2 id="adapter">Create an Adapter to Populate the List</h2>
187
188<p>The adapter populates the <code>WearableListView</code> with content. The following simple
189adapter populates the list with elements based on an array of strings:</p>
190
191<pre>
192private static final class Adapter extends WearableListView.Adapter {
193    private String[] mDataset;
194    private final Context mContext;
195    private final LayoutInflater mInflater;
196
197    // Provide a suitable constructor (depends on the kind of dataset)
198    public Adapter(Context context, String[] dataset) {
199        mContext = context;
200        mInflater = LayoutInflater.from(context);
201        mDataset = dataset;
202    }
203
204    // Provide a reference to the type of views you're using
205    public static class ItemViewHolder extends WearableListView.ViewHolder {
206        private TextView textView;
207        public ItemViewHolder(View itemView) {
208            super(itemView);
209            // find the text view within the custom item's layout
210            textView = (TextView) itemView.findViewById(R.id.name);
211        }
212    }
213
214    // Create new views for list items
215    // (invoked by the WearableListView's layout manager)
216    &#64;Override
217    public WearableListView.ViewHolder onCreateViewHolder(ViewGroup parent,
218                                                          int viewType) {
219        // Inflate our custom layout for list items
220        return new ItemViewHolder(mInflater.inflate(R.layout.list_item, null));
221    }
222
223    // Replace the contents of a list item
224    // Instead of creating new views, the list tries to recycle existing ones
225    // (invoked by the WearableListView's layout manager)
226    &#64;Override
227    public void onBindViewHolder(WearableListView.ViewHolder holder,
228                                 int position) {
229        // retrieve the text view
230        ItemViewHolder itemHolder = (ItemViewHolder) holder;
231        TextView view = itemHolder.textView;
232        // replace text contents
233        view.setText(mDataset[position]);
234        // replace list item's metadata
235        holder.itemView.setTag(position);
236    }
237
238    // Return the size of your dataset
239    // (invoked by the WearableListView's layout manager)
240    &#64;Override
241    public int getItemCount() {
242        return mDataset.length;
243    }
244}
245</pre>
246
247
248<h2 id="adapter-listener">Associate the Adapter and Set a Click Listener</h2>
249
250<p>In your activity, obtain a reference to the <code>WearableListView</code> element from
251your layout, assign an instance of the adapter to populate the list, and set a click listener
252to complete an action when the user selects a particular list item.</p>
253
254<pre>
255public class WearActivity extends Activity
256                          implements WearableListView.ClickListener {
257
258    // Sample dataset for the list
259    String[] elements = { "List Item 1", "List Item 2", ... };
260
261    &#64;Override
262    protected void onCreate(Bundle savedInstanceState) {
263        super.onCreate(savedInstanceState);
264        setContentView(R.layout.my_list_activity);
265
266        // Get the list component from the layout of the activity
267        WearableListView listView =
268            (WearableListView) findViewById(R.id.wearable_list);
269
270        // Assign an adapter to the list
271        listView.setAdapter(new Adapter(this, elements));
272
273        // Set a click listener
274        listView.setClickListener(this);
275    }
276
277    // WearableListView click listener
278    &#64;Override
279    public void onClick(WearableListView.ViewHolder v) {
280        Integer tag = (Integer) v.itemView.getTag();
281        // use this data to complete some action ...
282    }
283
284    &#64;Override
285    public void onTopEmptyRegionClick() {
286    }
287}
288</pre>
289