150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpage.title= Spinners 250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainparent.title=Input Controls 350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainparent.link=../controls.html 450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main@jd:body 550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv-wrapper"> 750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<div id="qv"> 850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>In this document</h2> 1050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 1150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="#Populate">Populate the Spinner with User Choices</a></li> 1250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="#SelectListener">Responding to User Selections</a></li> 1350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 1450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2>Key classes</h2> 1550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<ol> 1650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.widget.Spinner}</li> 1750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.widget.SpinnerAdapter}</li> 1850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li>{@link android.widget.AdapterView.OnItemSelectedListener}</li> 1950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</ol> 2050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 2250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</div> 2350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Spinners provide a quick way to select one value from a set. In the default state, a spinner 2550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainshows its currently selected value. Touching the spinner displays a dropdown menu with all other 2650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainavailable values, from which the user can select a new one.</p> 2750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 2850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<img src="{@docRoot}images/ui/spinner.png" alt="" /> 2950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 3050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>You can add a spinner to your layout with the {@link android.widget.Spinner} object. You 3150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainshould usually do so in your XML layout with a {@code <Spinner>} element. For example:</p> 3250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 3350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 3450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<Spinner 3550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:id="@+id/planets_spinner" 3650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_width="fill_parent" 3750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main android:layout_height="wrap_content" /> 3850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 3950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 4050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>To populate the spinner with a list of choices, you then need to specify a {@link 4150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.SpinnerAdapter} in your {@link android.app.Activity} or {@link android.app.Fragment} 4250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainsource code.</p> 4350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 4450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="Populate">Populate the Spinner with User Choices</h2> 4550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 4650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>The choices you provide for the spinner can come from any source, but must be provided through 4750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainan {@link android.widget.SpinnerAdapter}, such as an {@link android.widget.ArrayAdapter} if the 4850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainchoices are available in an array or a {@link android.widget.CursorAdapter} if the choices are 4950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainavailable from a database query.</p> 5050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 5150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>For instance, if the available choices for your spinner are pre-determined, you can provide 5250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainthem with a string array defined in a <a 5350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}guide/topics/resources/string-resource.html">string 5450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainresource file</a>:</p> 5550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 5650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 5750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<?xml version="1.0" encoding="utf-8"?> 5850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<resources> 5950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <string-array name="planets_array"> 6050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Mercury</item> 6150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Venus</item> 6250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Earth</item> 6350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Mars</item> 6450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Jupiter</item> 6550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Saturn</item> 6650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Uranus</item> 6750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <item>Neptune</item> 6850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main </string-array> 6950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</resources> 7050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 7150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 7250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <p>With an array such as this one, you can use the following code in your {@link 7350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.app.Activity} or {@link android.app.Fragment} to supply the spinner with the array using 7450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainan instance of {@link android.widget.ArrayAdapter}: 7550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 7650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 7750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainSpinner spinner = (Spinner) findViewById(R.id.spinner); 7850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Create an ArrayAdapter using the string array and a default spinner layout 7950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource(this, 8050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main R.array.planets_array, android.R.layout.simple_spinner_item); 8150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Specify the layout to use when the list of choices appears 8250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainadapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); 8350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main// Apply the adapter to the spinner 8450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainspinner.setAdapter(adapter); 8550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 8650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 8750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>The {@link 8850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.ArrayAdapter#createFromResource(Context,int,int) createFromResource()} method allows 8950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainyou to create an {@link android.widget.ArrayAdapter} from the string array. The third argument for 9050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainthis method is a layout resource that defines how the selected choice appears in the 9150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainspinner control. The {@link android.R.layout#simple_spinner_item} layout is provided by the 9250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainplatform and is the default layout you should use unless you'd like to define your own layout 9350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfor the spinner's appearance.</p> 9450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 9550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>You should then call {@link android.widget.ArrayAdapter#setDropDownViewResource(int)} to specify 9650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainthe layout the adapter should use to display the list of spinner choices ({@link 9750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.R.layout#simple_spinner_dropdown_item} is another standard layout defined by the 9850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainplatform).</p> 9950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Call {@link android.widget.AdapterView#setAdapter setAdapter()} to apply the adapter to your 10150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main{@link android.widget.Spinner}.</p> 10250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<h2 id="SelectListener">Responding to User Selections</h2> 10550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>When the user selects an item from the drop-down, the {@link android.widget.Spinner} object 10750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainreceives an on-item-selected event.</p> 10850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 10950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>To define the selection event handler for a spinner, implement the {@link 11050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView.OnItemSelectedListener} interface and the corresponding {@link 11150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView.OnItemSelectedListener#onItemSelected onItemSelected()} callback method. 11250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainFor example, here's an implementation of the interface in an {@link android.app.Activity}:</p> 11350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 11450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 11550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainpublic class SpinnerActivity extends Activity implements OnItemSelectedListener { 11650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main ... 11750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 11850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main public void onItemSelected(AdapterView<?> parent, View view, 11950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main int pos, long id) { 12050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // An item was selected. You can retrieve the selected item using 12150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // parent.getItemAtPosition(pos) 12250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } 12350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 12450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main public void onNothingSelected(AdapterView<?> parent) { 12550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main // Another interface callback 12650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main } 12750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main} 12850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 12950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 13050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>The {@link android.widget.AdapterView.OnItemSelectedListener} requires the {@link 13150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView.OnItemSelectedListener#onItemSelected(AdapterView,View,int,long) 13250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainonItemSelected()} and {@link 13350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView.OnItemSelectedListener#onNothingSelected(AdapterView) 13450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainonNothingSelected()} callback methods.</p> 13550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 13650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>Then you need to specify the interface implementation by calling {@link 13750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView#setOnItemSelectedListener setOnItemSelectedListener()}:</p> 13850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 13950e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<pre> 14050e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott MainSpinner spinner = (Spinner) findViewById(R.id.spinner); 14150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainspinner.setOnItemSelectedListener(this); 14250e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main</pre> 14350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main 14450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>If you implement the {@link 14550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.widget.AdapterView.OnItemSelectedListener} interface with your {@link 14650e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainandroid.app.Activity} or {@link android.app.Fragment} (such as in the example above), you can pass 14750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<code>this</code> as the interface instance.</p>