Home | History | Annotate | Download | only in ui 
      1 page.title=Binding to Data with AdapterView
      2 parent.title=User Interface
      3 parent.link=index.html
      4 @jd:body
      5 
      6 <div id="qv-wrapper">
      7 <div id="qv">
      8   <h2>In this document</h2>
      9   <ol>
     10     <li><a href="#FillingTheLayout">Filling the Layout with Data</a></li>
     11     <li><a href="#HandlingUserSelections">Handling User Selections</a></li>
     12   </ol>
     13   
     14   <h2>Related tutorials</h2>
     15   <ol>
     16     <li><a href="{@docRoot}resources/tutorials/views/hello-spinner.html">Spinner</a></li>
     17     <li><a href="{@docRoot}resources/tutorials/views/hello-listview.html">List View</a></li>
     18     <li><a href="{@docRoot}resources/tutorials/views/hello-gridview.html">Grid View</a></li>
     19   </ol>
     20 </div>
     21 </div>
     22 
     23 <p>The {@link android.widget.AdapterView} is a ViewGroup subclass whose child Views are determined by an {@link android.widget.Adapter Adapter} that 
     24 binds to data of some type. AdapterView is useful whenever you need to display stored data (as opposed to resource strings or drawables) in your layout.</p>
     25 
     26 <p>{@link android.widget.Gallery Gallery}, {@link android.widget.ListView ListView}, and  {@link android.widget.Spinner Spinner} are examples of AdapterView subclasses that you can use to bind to a specific type of data and display it in a certain way. </p>
     27 
     28 
     29 <p>AdapterView objects have two main responsibilities: </p>
     30 <ul>
     31     <li>Filling the layout with data
     32     </li>
     33     <li>Handling user selections
     34     </li>
     35 </ul>
     36 
     37 
     38 <h2 id="FillingTheLayout">Filling the Layout with Data</h2>
     39 <p>Inserting data into the layout is typically done by binding the AdapterView class to an {@link
     40 android.widget.Adapter}, which retrieves data from an external source (perhaps a list that
     41 the code supplies or query results from the device's database). </p>
     42 <p>The following code sample does the following:</p>
     43 <ol>
     44   <li>Creates a {@link android.widget.Spinner Spinner} with an existing View and binds it to a new ArrayAdapter
     45 that reads an array of colors from the local resources.</li>
     46   <li>Creates another Spinner object from a View and binds it to a new SimpleCursorAdapter that will read 
     47 people's names from the device contacts (see {@link android.provider.Contacts.People}).</li>
     48 </ol>
     49 
     50 <pre>
     51 // Get a Spinner and bind it to an ArrayAdapter that 
     52 // references a String array.
     53 Spinner s1 = (Spinner) findViewById(R.id.spinner1);
     54 ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource(
     55     this, R.array.colors, android.R.layout.simple_spinner_item);
     56 adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
     57 s1.setAdapter(adapter);
     58 
     59 // Load a Spinner and bind it to a data query.
     60 private static String[] PROJECTION = new String[] {
     61         People._ID, People.NAME
     62     };
     63 
     64 Spinner s2 = (Spinner) findViewById(R.id.spinner2);
     65 Cursor cur = managedQuery(People.CONTENT_URI, PROJECTION, null, null);
     66      
     67 SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this,
     68     android.R.layout.simple_spinner_item, // Use a template
     69                                           // that displays a
     70                                           // text view
     71     cur, // Give the cursor to the list adapter
     72     new String[] {People.NAME}, // Map the NAME column in the
     73                                          // people database to...
     74     new int[] {android.R.id.text1}); // The "text1" view defined in
     75                                      // the XML template
     76 					 
     77 adapter2.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
     78 s2.setAdapter(adapter2);
     79 </pre>
     80 
     81 <p>Note that it is necessary to have the People._ID column in projection used with CursorAdapter
     82 or else you will get an exception.</p>
     83 
     84 <p>If, during the course of your application's life, you change the underlying data that is read by your Adapter,
     85 you should call {@link android.widget.ArrayAdapter#notifyDataSetChanged()}. This will notify the attached View
     86 that the data has been changed and it should refresh itself.</p>
     87 
     88 <h2 id="HandlingUserSelections">Handling User Selections</h2>
     89 <p>You handle the user's selection by setting the class's {@link
     90 android.widget.AdapterView.OnItemClickListener} member to a listener and
     91 catching the selection changes. </p>
     92 <pre>
     93 // Create a message handling object as an anonymous class.
     94 private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() {
     95     public void onItemClick(AdapterView parent, View v, int position, long id)
     96     {
     97         // Display a messagebox.
     98         Toast.makeText(mContext,"You've got an event",Toast.LENGTH_SHORT).show();
     99     }
    100 };
    101 
    102 // Now hook into our object and set its onItemClickListener member
    103 // to our class handler object.
    104 mHistoryView = (ListView)findViewById(R.id.history);
    105 mHistoryView.setOnItemClickListener(mMessageClickedHandler); 
    106 </pre>
    107 
    108 <div class="special">
    109 <p>For more discussion on how to create different AdapterViews, read the following tutorials:
    110 <a href="{@docRoot}resources/tutorials/views/hello-spinner.html">Hello Spinner</a>,
    111 <a href="{@docRoot}resources/tutorials/views/hello-listview.html">Hello ListView</a>, and
    112 <a href="{@docRoot}resources/tutorials/views/hello-gridview.html">Hello GridView</a>.
    113 </div>
    114