frameworks/base/docs/html/resources/tutorials/views/hello-autocomplete.jd

   1 page.title=Auto Complete
   2 parent.title=Hello, Views
   3 parent.link=index.html
   4 @jd:body
   5
   6 <p>To create a text entry widget that provides auto-complete suggestions, use
   7 the {@link android.widget.AutoCompleteTextView} widget. Suggestions are received from a
   8 collection of strings associated with the widget through an {@link
   9 android.widget.ArrayAdapter}.</p>
  10
  11 <p>In this tutorial, you will create a {@link android.widget.AutoCompleteTextView} widget that
  12 provides suggestions for a country name.</p>
  13
  14
  15 <ol>
  16   <li>Start a new project named <em>HelloAutoComplete</em>.</li>
  17   <li>Create an XML file named <code>list_item.xml</code> and save it inside the
  18 <code>res/layout/</code> folder. Edit the file to look like this:
  19 <pre>
  20 &lt;?xml version="1.0" encoding="utf-8"?>
  21 &lt;TextView xmlns:android="http://schemas.android.com/apk/res/android"
  22     android:layout_width="fill_parent"
  23     android:layout_height="fill_parent"
  24     android:padding="10dp"
  25     android:textSize="16sp"
  26     android:textColor="#000">
  27 &lt;/TextView>
  28 </pre>
  29   <p>This file defines a simple {@link android.widget.TextView} that will be used for each
  30 item that appears in the list of suggestions.</p>
  31   </li>
  32   <li>Open the <code>res/layout/main.xml</code> file and insert the following:
  33 <pre>
  34 &lt;?xml version="1.0" encoding="utf-8"?>
  35 &lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  36     android:orientation="horizontal"
  37     android:layout_width="fill_parent"
  38     android:layout_height="wrap_content"
  39     android:padding="5dp">
  40     &lt;TextView
  41         android:layout_width="wrap_content"
  42         android:layout_height="wrap_content"
  43         android:text="Country" />
  44     &lt;AutoCompleteTextView android:id="@+id/autocomplete_country"
  45         android:layout_width="fill_parent"
  46         android:layout_height="wrap_content"
  47         android:layout_marginLeft="5dp"/>
  48 &lt;/LinearLayout>
  49 </pre>
  50   <p>The {@link android.widget.TextView} is a label that introduces the {@link
  51 android.widget.AutoCompleteTextView} widget.
  52 </li>
  53
  54 <li>Open <code>HelloAutoComplete.java</code> and insert the following code for the {@link
  55 android.app.Activity#onCreate(Bundle) onCreate()} method:
  56 <pre>
  57 &#64;Override
  58 protected void onCreate(Bundle savedInstanceState) {
  59     super.onCreate(savedInstanceState);
  60     setContentView(R.layout.main);
  61
  62     AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.autocomplete_country);
  63     ArrayAdapter&lt;String> adapter = new ArrayAdapter&lt;String>(this, R.layout.list_item, COUNTRIES);
  64     textView.setAdapter(adapter);
  65 }
  66 </pre>
  67
  68 <p>After the content view is set to the <code>main.xml</code> layout, the {@link
  69 android.widget.AutoCompleteTextView} widget is captured from the layout with {@link
  70 android.app.Activity#findViewById(int)}. A new {@link
  71 android.widget.ArrayAdapter} is then initialized to bind the <code>list_item.xml</code> layout
  72 to each list item in the <code>COUNTRIES</code> string array (defined in the next step).
  73 Finally, {@link android.widget.AutoCompleteTextView#setAdapter(T) setAdapter()} is called to
  74 associate the {@link android.widget.ArrayAdapter} with the
  75 {@link android.widget.AutoCompleteTextView} widget so that the string array will populate
  76 the list of suggestions.</p>
  77 </li>
  78
  79 <li>Inside the <code>HelloAutoComplete</code> class, add the string array:
  80 <pre>
  81 static final String[] COUNTRIES = new String[] {
  82   "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra",
  83   "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina",
  84   "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan",
  85   "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium",
  86   "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia",
  87   "Bosnia and Herzegovina", "Botswana", "Bouvet Island", "Brazil", "British Indian Ocean Territory",
  88   "British Virgin Islands", "Brunei", "Bulgaria", "Burkina Faso", "Burundi",
  89   "Cote d'Ivoire", "Cambodia", "Cameroon", "Canada", "Cape Verde",
  90   "Cayman Islands", "Central African Republic", "Chad", "Chile", "China",
  91   "Christmas Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo",
  92   "Cook Islands", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czech Republic",
  93   "Democratic Republic of the Congo", "Denmark", "Djibouti", "Dominica", "Dominican Republic",
  94   "East Timor", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea",
  95   "Estonia", "Ethiopia", "Faeroe Islands", "Falkland Islands", "Fiji", "Finland",
  96   "Former Yugoslav Republic of Macedonia", "France", "French Guiana", "French Polynesia",
  97   "French Southern Territories", "Gabon", "Georgia", "Germany", "Ghana", "Gibraltar",
  98   "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau",
  99   "Guyana", "Haiti", "Heard Island and McDonald Islands", "Honduras", "Hong Kong", "Hungary",
 100   "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica",
 101   "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Kuwait", "Kyrgyzstan", "Laos",
 102   "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg",
 103   "Macau", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands",
 104   "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", "Micronesia", "Moldova",
 105   "Monaco", "Mongolia", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia",
 106   "Nauru", "Nepal", "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand",
 107   "Nicaragua", "Niger", "Nigeria", "Niue", "Norfolk Island", "North Korea", "Northern Marianas",
 108   "Norway", "Oman", "Pakistan", "Palau", "Panama", "Papua New Guinea", "Paraguay", "Peru",
 109   "Philippines", "Pitcairn Islands", "Poland", "Portugal", "Puerto Rico", "Qatar",
 110   "Reunion", "Romania", "Russia", "Rwanda", "Sqo Tome and Principe", "Saint Helena",
 111   "Saint Kitts and Nevis", "Saint Lucia", "Saint Pierre and Miquelon",
 112   "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Saudi Arabia", "Senegal",
 113   "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands",
 114   "Somalia", "South Africa", "South Georgia and the South Sandwich Islands", "South Korea",
 115   "Spain", "Sri Lanka", "Sudan", "Suriname", "Svalbard and Jan Mayen", "Swaziland", "Sweden",
 116   "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "The Bahamas",
 117   "The Gambia", "Togo", "Tokelau", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey",
 118   "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Virgin Islands", "Uganda",
 119   "Ukraine", "United Arab Emirates", "United Kingdom",
 120   "United States", "United States Minor Outlying Islands", "Uruguay", "Uzbekistan",
 121   "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "Wallis and Futuna", "Western Sahara",
 122   "Yemen", "Yugoslavia", "Zambia", "Zimbabwe"
 123 };
 124 </pre>
 125 <p>This is the list of suggestions that will be provided in a drop-down list when the user types into
 126 the {@link android.widget.AutoCompleteTextView} widget.</p>
 127 </li>
 128
 129 <li>Run the application.</li>
 130 </ol>
 131 <p>As you type, you should see something like this:</p>
 132 <img src="images/hello-autocomplete.png" width="150px" />
 133
 134
 135 <h2>More Information</h2>
 136
 137 <p>Note that using a hard-coded string array is not a recommended design practice because your
 138 application code should focus on behavior, not content. Application content such as strings
 139 should be externalized from the code in order to make modifications to the content easier and
 140 facilitate localization of the content. The hard-coded strings are used in this tutorial only to
 141 make it simple and focus on the {@link android.widget.AutoCompleteTextView} widget.
 142 Instead, your application should declare such string arrays in an XML file. This can be done
 143 with a {@code &lt;string-array&lt;} resource in your project {@code res/values/strings.xml} file.
 144 For example:</p>
 145 <pre>
 146 &lt;?xml version="1.0" encoding="utf-8"?>
 147 &lt;resources>
 148     &lt;string-array name="countries_array">
 149         &lt;item>Bahrain&lt;/item>
 150         &lt;item>Bangladesh&lt;/item>
 151         &lt;item>Barbados&lt;/item>
 152         &lt;item>Belarus&lt;/item>
 153         &lt;item>Belgium&lt;/item>
 154         &lt;item>Belize&lt;/item>
 155         &lt;item>Benin&lt;/item>
 156     &lt;/string-array>
 157 &lt;/resources>
 158 </pre>
 159 <p>To use these resource strings for the {@link android.widget.ArrayAdapter}, replace the original
 160 {@link android.widget.ArrayAdapter} constructor line with the following:</p>
 161 <pre>
 162 String[] countries = getResources().getStringArray(R.array.countries_array);
 163 ArrayAdapter&lt;String> adapter = new ArrayAdapter&lt;String>(this, R.layout.list_item, countries);
 164 </pre>
 165
 166
 167 <h3>References</h3>
 168 <ul>
 169         <li>{@link android.widget.ArrayAdapter}</li>
 170         <li>{@link android.widget.AutoCompleteTextView}</li>
 171 </ul>
 172
 173