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