1page.title=Setting Up the Search Interface 2trainingnavtop=true 3next.title=Storing and Searching for Data 4next.link=search.html 5 6@jd:body 7 8 <div id="tb-wrapper"> 9 <div id="tb"> 10 <h2>This lesson teaches you to</h2> 11 12 <ul> 13 <li><a href="{@docRoot}training/search/setup.html#add-sv">Add the Search View to the Action 14 Bar</a></li> 15 16 <li><a href="{@docRoot}training/search/setup.html#create-sc">Create a Searchable 17 Configuration</a></li> 18 19 <li><a href="{@docRoot}training/search/setup.html#create-sa">Create a Searchable 20 Activity</a></li> 21 </ul> 22 23 <h2>You should also read:</h2> 24 25 <ul> 26 <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> 27 </ul> 28 </div> 29 </div> 30 31 <p>Beginning in Android 3.0, using the {@link android.widget.SearchView} widget as an item in 32 the action bar is the preferred way to provide search in your app. Like with all items in 33 the action bar, you can define the {@link android.widget.SearchView} to show at all times, only 34 when there is room, or as a collapsible action, which displays the {@link 35 android.widget.SearchView} as an icon initially, then takes up the entire action bar as a search 36 field when the user clicks the icon.</p> 37 38 <p class="note"><strong>Note:</strong> Later in this class, you will learn how to make your 39 app compatible down to Android 2.1 (API level 7) for devices that do not support 40 {@link android.widget.SearchView}.</p> 41 42 <h2 id="add-sv">Add the Search View to the Action Bar</h2> 43 44 <p>To add a {@link android.widget.SearchView} widget to the action bar, create a file named 45 <code>res/menu/options_menu.xml</code> in your project and add the following code to the file. 46 This code defines how to create the search item, such as the icon to use and the title of the 47 item. The <code>collapseActionView</code> attribute allows your {@link android.widget.SearchView} 48 to expand to take up the whole action bar and collapse back down into a 49 normal action bar item when not in use. Because of the limited action bar space on handset devices, 50 using the <code>collapsibleActionView</code> attribute is recommended to provide a better 51 user experience.</p> 52 <pre> 53<?xml version="1.0" encoding="utf-8"?> 54<menu xmlns:android="http://schemas.android.com/apk/res/android"> 55 <item android:id="@+id/search" 56 android:title="@string/search_title" 57 android:icon="@drawable/ic_search" 58 android:showAsAction="collapseActionView|ifRoom" 59 android:actionViewClass="android.widget.SearchView" /> 60</menu> 61</pre> 62 63 <p class="note"><strong>Note:</strong> If you already have an existing XML file for your menu 64 items, you can add the <code><item></code> element to that file instead.</p> 65 66 <p>To display the {@link android.widget.SearchView} in the action bar, inflate the XML menu 67 resource (<code>res/menu/options_menu.xml</code>) in the {@link 68 android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method of your activity:</p> 69 <pre> 70@Override 71public boolean onCreateOptionsMenu(Menu menu) { 72 MenuInflater inflater = getMenuInflater(); 73 inflater.inflate(R.menu.options_menu, menu); 74 75 return true; 76} 77</pre> 78 79 <p>If you run your app now, the {@link android.widget.SearchView} appears in your app's action 80 bar, but it isn't functional. You now need to define <em>how</em> the {@link 81 android.widget.SearchView} behaves.</p> 82 83 <h2 id="create-sc">Create a Searchable Configuration</h2> 84 85 <p>A <a href="http://developer.android.com/guide/topics/search/searchable-config.html">searchable 86 configuration</a> defines how the {@link android.widget.SearchView} behaves and is defined in a 87 <code>res/xml/searchable.xml</code> file. At a minimum, a searchable configuration must contain 88 an <code>android:label</code> attribute that has the same value as the 89 <code>android:label</code> attribute of the <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> or 90 <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> element in your Android manifest. 91 However, we also recommend adding an <code>android:hint</code> attribute to give the user an idea of what to enter into the search 92 box:</p> 93 <pre> 94<?xml version="1.0" encoding="utf-8"?> 95 96<searchable xmlns:android="http://schemas.android.com/apk/res/android" 97 android:label="@string/app_name" 98 android:hint="@string/search_hint" /> 99</pre> 100 101 <p>In your application's manifest file, declare a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"> 102 <code><meta-data></code></a> element that points to the <code>res/xml/searchable.xml</code> file, 103 so that your application knows where to find it. Declare the element in an <code><activity></code> 104 that you want to display the {@link android.widget.SearchView} in:</p> 105 <pre> 106<activity ... > 107 ... 108 <meta-data android:name="android.app.searchable" 109 android:resource="@xml/searchable" /> 110 111</activity> 112</pre> 113 114 <p>In the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method that you 115 created before, associate the searchable configuration with the {@link android.widget.SearchView} 116 by calling {@link android.widget.SearchView#setSearchableInfo}:</p> 117 <pre> 118@Override 119public boolean onCreateOptionsMenu(Menu menu) { 120 MenuInflater inflater = getMenuInflater(); 121 inflater.inflate(R.menu.options_menu, menu); 122 123 // Associate searchable configuration with the SearchView 124 SearchManager searchManager = 125 (SearchManager) getSystemService(Context.SEARCH_SERVICE); 126 SearchView searchView = 127 (SearchView) menu.findItem(R.id.search).getActionView(); 128 searchView.setSearchableInfo( 129 searchManager.getSearchableInfo(getComponentName())); 130 131 return true; 132} 133</pre> 134 135 <p>The call to {@link android.app.SearchManager#getSearchableInfo getSearchableInfo()} obtains a 136 {@link android.app.SearchableInfo} object that is created from the searchable configuration XML 137 file. When the searchable configuration is correctly associated with your {@link 138 android.widget.SearchView}, the {@link android.widget.SearchView} starts an activity with the 139 {@link android.content.Intent#ACTION_SEARCH} intent when a user submits a query. You now need an 140 activity that can filter for this intent and handle the search query.</p> 141 142 <h2 id="create-sa">Create a Searchable Activity</h2> 143 144 <p>A {@link android.widget.SearchView} tries to start an activity with the {@link 145 android.content.Intent#ACTION_SEARCH} when a user submits a search query. A searchable activity 146 filters for the {@link android.content.Intent#ACTION_SEARCH} intent and searches for the query in 147 some sort of data set. To create a searchable activity, declare an activity of your choice to 148 filter for the {@link android.content.Intent#ACTION_SEARCH} intent:</p> 149 <pre> 150<activity android:name=".SearchResultsActivity" ... > 151 ... 152 <intent-filter> 153 <action android:name="android.intent.action.SEARCH" /> 154 </intent-filter> 155 ... 156</activity> 157</pre> 158 159 <p>In your searchable activity, handle the {@link android.content.Intent#ACTION_SEARCH} intent by 160 checking for it in your {@link android.app.Activity#onCreate onCreate()} method.</p> 161 162 <p class="note"><strong>Note:</strong> If your searchable activity launches in single top mode 163 (<code>android:launchMode="singleTop"</code>), also handle the {@link 164 android.content.Intent#ACTION_SEARCH} intent in the {@link android.app.Activity#onNewIntent 165 onNewIntent()} method. In single top mode, only one instance of your activity is created and 166 subsequent calls to start your activity do not create a new activity on the 167 stack. This launch mode is useful so users can perform searches from the same activity 168 without creating a new activity instance every time.</p> 169 <pre> 170public class SearchResultsActivity extends Activity { 171 172 @Override 173 public void onCreate(Bundle savedInstanceState) { 174 ... 175 handleIntent(getIntent()); 176 } 177 178 @Override 179 protected void onNewIntent(Intent intent) { 180 ... 181 handleIntent(intent); 182 } 183 184 private void handleIntent(Intent intent) { 185 186 if (Intent.ACTION_SEARCH.equals(intent.getAction())) { 187 String query = intent.getStringExtra(SearchManager.QUERY); 188 //use the query to search your data somehow 189 } 190 } 191 ... 192} 193</pre> 194 195 <p>If you run your app now, the {@link android.widget.SearchView} can accept the user's query and 196 start your searchable activity with the {@link android.content.Intent#ACTION_SEARCH} intent. It 197 is now up to you to figure out how to store and search your data given a query.</p>