M7350/base/docs/html/resources/tutorials/views/hello-spinner.jd

page.title=Spinner
parent.title=Hello, Views
parent.link=index.html
@jd:body

<p>{@link android.widget.Spinner} is a widget similar to a drop-down list for selecting items.</p>

<p>In this tutorial, you'll create
a simple spinner widget that displays a list of planets. When one is selected, a toast message
will display the selected item.</p>

<ol>
  <li>Start a new project named <em>HelloSpinner</em>.</li>
  <li>Open the <code>res/layout/main.xml</code> file and insert the following:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:padding="10dip"
    android:layout_width="fill_parent"
    android:layout_height="wrap_content">
    &lt;TextView
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:layout_marginTop="10dip"
        android:text="@string/planet_prompt"
    />
    &lt;Spinner 
        android:id="@+id/spinner"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:prompt="@string/planet_prompt"
    />
&lt;/LinearLayout>
</pre>
  <p>Notice that the {@link android.widget.TextView}'s <code>android:text</code> attribute and the
{@link android.widget.Spinner}'s <code>android:prompt</code> attribute both reference the same
string resource. This text behaves as a title for the widget. When applied to the {@link
android.widget.Spinner}, the title text will appear
in the selection dialog that appears upon selecting the widget.</p>
</li>

<li>Create a <code>strings.xml</code> file in <code>res/values/</code> and edit the file to look
like this:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
    &lt;string name="planet_prompt">Choose a planet&lt;/string>
    &lt;string-array name="planets_array">
        &lt;item>Mercury&lt;/item>
        &lt;item>Venus&lt;/item>
        &lt;item>Earth&lt;/item>
        &lt;item>Mars&lt;/item>
        &lt;item>Jupiter&lt;/item>
        &lt;item>Saturn&lt;/item>
        &lt;item>Uranus&lt;/item>
        &lt;item>Neptune&lt;/item>
    &lt;/string-array>
&lt;/resources>
</pre>
  <p>The {@code &lt;string>} element defines the title string referenced by the {@link
android.widget.TextView} and {@link android.widget.Spinner} in the layout above. The {@code
&lt;string-array} element defines the list of strings that will be displayed as the list in
the {@link android.widget.Spinner} widget.</p>
</li>

<li>Now open the <code>HelloSpinner.java</code> file and insert the following code for the {@link
android.app.Activity#onCreate(Bundle) onCreate()} method:
<pre>
&#64;Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Spinner spinner = (Spinner) findViewById(R.id.spinner);
    ArrayAdapter&lt;CharSequence> adapter = ArrayAdapter.createFromResource(
            this, R.array.planets_array, android.R.layout.simple_spinner_item);
    adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
    spinner.setAdapter(adapter);
}
</pre>
  <p>After the {@code main.xml} layout is set as the content view, the  {@link
android.widget.Spinner} widget is captured from the layout with {@link
android.app.Activity#findViewById(int)}. The {@link
android.widget.ArrayAdapter#createFromResource(Context,int,int) createFromResource()} method then
creates a new {@link  android.widget.ArrayAdapter}, which binds each item in the string array
to the initial appearance for the {@link android.widget.Spinner} (which is how each item will
appear in the spinner when selected). The {@code
R.array.planets_array} ID references the {@code string-array} defined above and the
{@code android.R.layout.simple_spinner_item} ID references a layout for the standard spinner
appearance, defined by the platform. Then {@link
android.widget.ArrayAdapter#setDropDownViewResource(int)} is called to define the appearance for
each item when the widget is opened ({@code simple_spinner_dropdown_item} is
another standard layout defined by the platform). Finally, the {@link android.widget.ArrayAdapter}
is set to associate all of its items with the {@link android.widget.Spinner} by calling {@link
android.widget.AdapterView#setAdapter(T)}.</p>
</li>

<li>Now create a nested class that implements {@link
android.widget.AdapterView.OnItemSelectedListener}. This will provide a callback method that will
notify your application when an item has been selected from the {@link
android.widget.Spinner}. Here's what this class should look like:
<pre>
public class MyOnItemSelectedListener implements OnItemSelectedListener {

    public void onItemSelected(AdapterView&lt;?> parent,
        View view, int pos, long id) {
      Toast.makeText(parent.getContext()), "The planet is " +
          parent.getItemAtPosition(pos).toString(), Toast.LENGTH_LONG).show();
    }

    public void onNothingSelected(AdapterView<?> parent) {
      // Do nothing.
    }
}
</pre>
<p>The {@link android.widget.AdapterView.OnItemSelectedListener} requires the {@link
android.widget.AdapterView.OnItemSelectedListener#onItemSelected(AdapterView,View,int,long)
onItemSelected()} and {@link
android.widget.AdapterView.OnItemSelectedListener#onNothingSelected(AdapterView)
onNothingSelected()} callback methods. The former is called when an item from the {@link
android.widget.AdapterView} is selected, in which case, a short {@link android.widget.Toast}
message displays the selected text; and the latter is called when a selection disappears from the
{@link android.widget.AdapterView}, which doesn't happen in this case, so it's ignored.</p>
</li>

<li>Now the {@code MyOnItemSelectedListener} needs to be applied to the {@link
android.widget.Spinner}. Go back to the {@link android.app.Activity#onCreate(Bundle) onCreate()}
method and add the following line to the end:
<pre>
    spinner.setOnItemSelectedListener(new MyOnItemSelectedListener());
</pre>
<p>This creates a new anonymous instance of the {@code MyOnItemSelectedListener} and sets it as the
listener for the {@link android.widget.Spinner}.</p>
</li>

<li>Run the application.</li>
</ol>
<p>It should look like this:</p>
<img src="images/hello-spinner.png" width="150px" />


<h3>Resources</h3>
<ul>
	<li>{@link android.R.layout}</li>
	<li>{@link android.widget.ArrayAdapter}</li>
	<li>{@link android.widget.Spinner}</li>
</ul>