1page.title=Spinners
2page.tags=adapterview,spinneradapter
3@jd:body
4
5<div id="qv-wrapper">
6<div id="qv">
7
8<h2>In this document</h2>
9<ol>
10  <li><a href="#Populate">Populate the Spinner with User Choices</a></li>
11  <li><a href="#SelectListener">Responding to User Selections</a></li>
12</ol>
13<h2>Key classes</h2>
14<ol>
15  <li>{@link android.widget.Spinner}</li>
16  <li>{@link android.widget.SpinnerAdapter}</li>
17  <li>{@link android.widget.AdapterView.OnItemSelectedListener}</li>
18</ol>
19
20</div>
21</div>
22
23<p>Spinners provide a quick way to select one value from a set. In the default state, a spinner
24shows its currently selected value. Touching the spinner displays a dropdown menu with all other
25available values, from which the user can select a new one.</p>
26
27<img src="{@docRoot}images/ui/spinner.png" alt="" />
28
29<p>You can add a spinner to your layout with the {@link android.widget.Spinner} object. You
30should usually do so in your XML layout with a {@code &lt;Spinner&gt;} element. For example:</p>
31
32<pre>
33&lt;Spinner
34    android:id="@+id/planets_spinner"
35    android:layout_width="fill_parent"
36    android:layout_height="wrap_content" />
37</pre>
38
39<p>To populate the spinner with a list of choices, you then need to specify a {@link
40android.widget.SpinnerAdapter} in your {@link android.app.Activity} or {@link android.app.Fragment}
41source code.</p>
42
43<h2 id="Populate">Populate the Spinner with User Choices</h2>
44
45<p>The choices you provide for the spinner can come from any source, but must be provided through
46an {@link android.widget.SpinnerAdapter}, such as an {@link android.widget.ArrayAdapter} if the
47choices are available in an array or a {@link android.widget.CursorAdapter} if the choices are
48available from a database query.</p>
49
50<p>For instance, if the available choices for your spinner are pre-determined, you can provide
51them with a string array defined in a <a
52href="{@docRoot}guide/topics/resources/string-resource.html">string
53resource file</a>:</p>
54
55<pre>
56&lt;?xml version="1.0" encoding="utf-8"?>
57&lt;resources>
58    &lt;string-array name="planets_array">
59        &lt;item>Mercury&lt;/item>
60        &lt;item>Venus&lt;/item>
61        &lt;item>Earth&lt;/item>
62        &lt;item>Mars&lt;/item>
63        &lt;item>Jupiter&lt;/item>
64        &lt;item>Saturn&lt;/item>
65        &lt;item>Uranus&lt;/item>
66        &lt;item>Neptune&lt;/item>
67    &lt;/string-array>
68&lt;/resources>
69</pre>
70
71  <p>With an array such as this one, you can use the following code in your {@link
72android.app.Activity} or {@link android.app.Fragment} to supply the spinner with the array using
73an instance of {@link android.widget.ArrayAdapter}:
74
75<pre>
76Spinner spinner = (Spinner) findViewById(R.id.spinner);
77// Create an ArrayAdapter using the string array and a default spinner layout
78ArrayAdapter&lt;CharSequence> adapter = ArrayAdapter.createFromResource(this,
79        R.array.planets_array, android.R.layout.simple_spinner_item);
80// Specify the layout to use when the list of choices appears
81adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
82// Apply the adapter to the spinner
83spinner.setAdapter(adapter);
84</pre>
85
86<p>The {@link
87android.widget.ArrayAdapter#createFromResource(Context,int,int) createFromResource()} method allows
88you to create an {@link  android.widget.ArrayAdapter} from the string array. The third argument for
89this method is a layout resource that defines how the selected choice appears in the
90spinner control. The {@link android.R.layout#simple_spinner_item} layout is provided by the
91platform and is the default layout you should use unless you'd like to define your own layout
92for the spinner's appearance.</p>
93
94<p>You should then call {@link android.widget.ArrayAdapter#setDropDownViewResource(int)} to specify
95the layout the adapter should use to display the list of spinner choices ({@link
96android.R.layout#simple_spinner_dropdown_item} is another standard layout defined by the
97platform).</p>
98
99<p>Call {@link android.widget.AdapterView#setAdapter setAdapter()} to apply the adapter to your
100{@link android.widget.Spinner}.</p>
101
102
103<h2 id="SelectListener">Responding to User Selections</h2>
104
105<p>When the user selects an item from the drop-down, the {@link android.widget.Spinner} object
106receives an on-item-selected event.</p>
107
108<p>To define the selection event handler for a spinner, implement the {@link
109android.widget.AdapterView.OnItemSelectedListener} interface and the corresponding {@link
110android.widget.AdapterView.OnItemSelectedListener#onItemSelected onItemSelected()} callback method.
111For example, here's an implementation of the interface in an {@link android.app.Activity}:</p>
112
113<pre>
114public class SpinnerActivity extends Activity implements OnItemSelectedListener {
115    ...
116
117    public void onItemSelected(AdapterView&lt;?> parent, View view,
118            int pos, long id) {
119        // An item was selected. You can retrieve the selected item using
120        // parent.getItemAtPosition(pos)
121    }
122
123    public void onNothingSelected(AdapterView&lt;?> parent) {
124        // Another interface callback
125    }
126}
127</pre>
128
129<p>The {@link android.widget.AdapterView.OnItemSelectedListener} requires the {@link
130android.widget.AdapterView.OnItemSelectedListener#onItemSelected(AdapterView,View,int,long)
131onItemSelected()} and {@link
132android.widget.AdapterView.OnItemSelectedListener#onNothingSelected(AdapterView)
133onNothingSelected()} callback methods.</p>
134
135<p>Then you need to specify the interface implementation by calling {@link
136android.widget.AdapterView#setOnItemSelectedListener setOnItemSelectedListener()}:</p>
137
138<pre>
139Spinner spinner = (Spinner) findViewById(R.id.spinner);
140spinner.setOnItemSelectedListener(this);
141</pre>
142
143<p>If you implement the {@link
144android.widget.AdapterView.OnItemSelectedListener} interface with your {@link
145android.app.Activity} or {@link android.app.Fragment} (such as in the example above), you can pass
146<code>this</code> as the interface instance.</p>
147