Scott Main | 64461bf | 2013-04-11 19:32:08 -0700 | [diff] [blame] | 1 | page.title=Spinners |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=adapterview,spinneradapter |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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 |
| 24 | shows its currently selected value. Touching the spinner displays a dropdown menu with all other |
| 25 | available 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 |
| 30 | should usually do so in your XML layout with a {@code <Spinner>} element. For example:</p> |
| 31 | |
| 32 | <pre> |
| 33 | <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 |
| 40 | android.widget.SpinnerAdapter} in your {@link android.app.Activity} or {@link android.app.Fragment} |
| 41 | source 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 |
| 46 | an {@link android.widget.SpinnerAdapter}, such as an {@link android.widget.ArrayAdapter} if the |
| 47 | choices are available in an array or a {@link android.widget.CursorAdapter} if the choices are |
| 48 | available from a database query.</p> |
| 49 | |
| 50 | <p>For instance, if the available choices for your spinner are pre-determined, you can provide |
| 51 | them with a string array defined in a <a |
| 52 | href="{@docRoot}guide/topics/resources/string-resource.html">string |
| 53 | resource file</a>:</p> |
| 54 | |
| 55 | <pre> |
| 56 | <?xml version="1.0" encoding="utf-8"?> |
| 57 | <resources> |
| 58 | <string-array name="planets_array"> |
| 59 | <item>Mercury</item> |
| 60 | <item>Venus</item> |
| 61 | <item>Earth</item> |
| 62 | <item>Mars</item> |
| 63 | <item>Jupiter</item> |
| 64 | <item>Saturn</item> |
| 65 | <item>Uranus</item> |
| 66 | <item>Neptune</item> |
| 67 | </string-array> |
| 68 | </resources> |
| 69 | </pre> |
| 70 | |
| 71 | <p>With an array such as this one, you can use the following code in your {@link |
| 72 | android.app.Activity} or {@link android.app.Fragment} to supply the spinner with the array using |
| 73 | an instance of {@link android.widget.ArrayAdapter}: |
| 74 | |
| 75 | <pre> |
| 76 | Spinner spinner = (Spinner) findViewById(R.id.spinner); |
| 77 | // Create an ArrayAdapter using the string array and a default spinner layout |
| 78 | ArrayAdapter<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 |
| 81 | adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); |
| 82 | // Apply the adapter to the spinner |
| 83 | spinner.setAdapter(adapter); |
| 84 | </pre> |
| 85 | |
| 86 | <p>The {@link |
| 87 | android.widget.ArrayAdapter#createFromResource(Context,int,int) createFromResource()} method allows |
| 88 | you to create an {@link android.widget.ArrayAdapter} from the string array. The third argument for |
| 89 | this method is a layout resource that defines how the selected choice appears in the |
| 90 | spinner control. The {@link android.R.layout#simple_spinner_item} layout is provided by the |
| 91 | platform and is the default layout you should use unless you'd like to define your own layout |
| 92 | for the spinner's appearance.</p> |
| 93 | |
| 94 | <p>You should then call {@link android.widget.ArrayAdapter#setDropDownViewResource(int)} to specify |
| 95 | the layout the adapter should use to display the list of spinner choices ({@link |
| 96 | android.R.layout#simple_spinner_dropdown_item} is another standard layout defined by the |
| 97 | platform).</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 |
| 106 | receives an on-item-selected event.</p> |
| 107 | |
| 108 | <p>To define the selection event handler for a spinner, implement the {@link |
| 109 | android.widget.AdapterView.OnItemSelectedListener} interface and the corresponding {@link |
| 110 | android.widget.AdapterView.OnItemSelectedListener#onItemSelected onItemSelected()} callback method. |
| 111 | For example, here's an implementation of the interface in an {@link android.app.Activity}:</p> |
| 112 | |
| 113 | <pre> |
| 114 | public class SpinnerActivity extends Activity implements OnItemSelectedListener { |
| 115 | ... |
| 116 | |
| 117 | public void onItemSelected(AdapterView<?> 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<?> parent) { |
| 124 | // Another interface callback |
| 125 | } |
| 126 | } |
| 127 | </pre> |
| 128 | |
| 129 | <p>The {@link android.widget.AdapterView.OnItemSelectedListener} requires the {@link |
| 130 | android.widget.AdapterView.OnItemSelectedListener#onItemSelected(AdapterView,View,int,long) |
| 131 | onItemSelected()} and {@link |
| 132 | android.widget.AdapterView.OnItemSelectedListener#onNothingSelected(AdapterView) |
| 133 | onNothingSelected()} callback methods.</p> |
| 134 | |
| 135 | <p>Then you need to specify the interface implementation by calling {@link |
| 136 | android.widget.AdapterView#setOnItemSelectedListener setOnItemSelectedListener()}:</p> |
| 137 | |
| 138 | <pre> |
| 139 | Spinner spinner = (Spinner) findViewById(R.id.spinner); |
| 140 | spinner.setOnItemSelectedListener(this); |
| 141 | </pre> |
| 142 | |
| 143 | <p>If you implement the {@link |
| 144 | android.widget.AdapterView.OnItemSelectedListener} interface with your {@link |
| 145 | android.app.Activity} or {@link android.app.Fragment} (such as in the example above), you can pass |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 146 | <code>this</code> as the interface instance.</p> |