Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 1 | page.title=Creating a Search Interface |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=searchview |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 3 | @jd:body |
| 4 | |
| 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 7 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 8 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 9 | <h2>In this document</h2> |
| 10 | <ol> |
Scott Main | 72e0df6 | 2011-06-23 12:02:10 -0700 | [diff] [blame] | 11 | <li><a href="#TheBasics">The Basics</a></li> |
| 12 | <li><a href="#SearchableConfiguration">Creating a Searchable Configuration</a></li> |
| 13 | <li><a href="#SearchableActivity">Creating a Searchable Activity</a> |
| 14 | <ol> |
| 15 | <li><a href="#DeclaringSearchableActivity">Declaring a searchable activity</a></li> |
| 16 | <li><a href="#PerformingSearch">Performing a search</a></li> |
| 17 | </ol> |
| 18 | </li> |
| 19 | <li><a href="#SearchDialog">Using the Search Dialog</a> |
| 20 | <ol> |
| 21 | <li><a href="#InvokingTheSearchDialog">Invoking the search dialog</a></li> |
| 22 | <li><a href="#LifeCycle">The impact of the search dialog on your activity lifecycle</a></li> |
| 23 | <li><a href="#SearchContextData">Passing search context data</a></li> |
| 24 | </ol> |
| 25 | </li> |
| 26 | <li><a href="#UsingSearchWidget">Using the Search Widget</a> |
| 27 | <ol> |
| 28 | <li><a href="#ConfiguringWidget">Configuring the search widget</a></li> |
| 29 | <li><a href="#WidgetFeatures">Other search widget features</a></li> |
| 30 | <li><a href="#UsingBoth">Using both the widget and the dialog</a></li> |
| 31 | </ol> |
| 32 | </li> |
| 33 | <li><a href="#VoiceSearch">Adding Voice Search</a></li> |
| 34 | <li><a href="#SearchSuggestions">Adding Search Suggestions</a></li> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 35 | </ol> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 36 | |
| 37 | <h2>Key classes</h2> |
| 38 | <ol> |
| 39 | <li>{@link android.app.SearchManager}</li> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 40 | <li>{@link android.widget.SearchView}</li> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 41 | </ol> |
| 42 | |
Scott Main | ec80d7f | 2010-09-24 16:17:27 -0700 | [diff] [blame] | 43 | <h2>Related samples</h2> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 44 | <ol> |
| 45 | <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable |
| 46 | Dictionary</a></li> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 47 | <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.html">SearchView |
| 48 | in the Action Bar</a></li> |
| 49 | <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewFilterMode.html">SearchView |
| 50 | filter mode</a></li> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 51 | </ol> |
| 52 | |
| 53 | <h2>Downloads</h2> |
| 54 | <ol> |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 55 | <li><a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar |
| 56 | Icon Pack</a></li> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 57 | </ol> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 58 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 59 | </div> |
| 60 | </div> |
| 61 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 62 | <p>When you're ready to add search functionality to your application, Android helps you implement |
| 63 | the user interface with either a search dialog that appears at the top of the activity window or a |
| 64 | search widget that you can insert in your layout. Both the search dialog and the widget can deliver |
| 65 | the user's search query to a specific activity in your application. This way, the user can initiate |
| 66 | a search from any activity where the search dialog or widget is available, and the system starts the |
| 67 | appropriate activity to perform the search and present results.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 68 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 69 | <p>Other features available for the search dialog and widget include:</p> |
| 70 | |
| 71 | <ul> |
| 72 | <li>Voice search</li> |
| 73 | <li>Search suggestions based on recent queries</li> |
| 74 | <li>Search suggestions that match actual results in your application data</li> |
| 75 | </ul> |
| 76 | |
| 77 | <p>This guide shows you how to set up your application to provide a search interface |
| 78 | that's assisted by the Android system to deliver search queries, using either the |
| 79 | search dialog or the search widget.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 80 | |
| 81 | |
| 82 | <h2 id="TheBasics">The Basics</h2> |
| 83 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 84 | <div class="figure" style="width:250px"> |
| 85 | <img src="{@docRoot}images/search/search-ui.png" alt="" height="417" /> |
| 86 | <p class="img-caption"><strong>Figure 1.</strong> Screenshot of an application's search dialog.</p> |
| 87 | </div> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 88 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 89 | <p>Before you begin, you should decide whether you'll implement your search interface using the |
| 90 | search dialog or the search widget. Both provide the same search features, but in slightly different |
| 91 | ways:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 92 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 93 | <ul> |
| 94 | <li>The <strong>search dialog</strong> is a UI component that's controlled by the Android system. |
| 95 | When activated by the user, the search dialog appears at the top of the activity, as shown in figure |
| 96 | 1. |
| 97 | <p>The Android system controls all events in the search dialog. When the user |
| 98 | submits a query, the system delivers the query to the activity that you specify to |
| 99 | handle searches. The dialog can also provide search suggestions while the user types.</p></li> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 100 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 101 | <li>The <strong>search widget</strong> is an instance of {@link android.widget.SearchView} that |
| 102 | you can place anywhere in your layout. By default, the search widget behaves like a standard {@link |
| 103 | android.widget.EditText} widget and doesn't do anything, but you can configure it so that the |
| 104 | Android system handles all input events, delivers queries to the appropriate activity, and provides |
| 105 | search suggestions (just like the search dialog). However, the search widget is available only in |
| 106 | Android 3.0 (API Level 11) and higher. |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 107 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 108 | <p class="note"><strong>Note:</strong> If you want, you can handle all user input into the |
| 109 | search widget yourself, using various callback methods and listeners. This document, however, |
| 110 | focuses on how to integrate the search widget with the system for an assisted search |
| 111 | implementation. If you want to handle all user input yourself, read the reference documentation for |
| 112 | {@link android.widget.SearchView} and its nested interfaces. </p></li> |
| 113 | </ul> |
| 114 | |
| 115 | <p>When the user executes a search from the search dialog or a search widget, the system creates an |
| 116 | {@link android.content.Intent} and stores the user query in it. The system then starts the activity |
| 117 | that you've declared to handle searches (the "searchable activity") and delivers it the intent. To |
| 118 | set up your application for this kind of assisted search, you need the following:</p> |
| 119 | |
| 120 | <ul> |
| 121 | <li>A searchable configuration |
| 122 | <p>An XML file that configures some settings for the search dialog or widget. It includes settings |
| 123 | for features such as voice search, search suggestion, and hint text for the search box.</p></li> |
| 124 | <li>A searchable activity |
| 125 | <p>The {@link android.app.Activity} that receives the search query, searches your |
| 126 | data, and displays the search results.</p></li> |
| 127 | <li>A search interface, provided by either: |
| 128 | <ul> |
| 129 | <li>The search dialog |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 130 | <p>By default, the search dialog is hidden, but appears at the top of the screen when |
| 131 | you call {@link android.app.Activity#onSearchRequested()} (when the user presses your |
| 132 | Search button).</p> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 133 | </li> |
| 134 | <li>Or, a {@link android.widget.SearchView} widget |
| 135 | <p>Using the search widget allows you to put the search box anywhere in your activity. |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 136 | Instead of putting it in your activity layout, you should usually use |
| 137 | {@link android.widget.SearchView} as an |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 138 | <a href="{@docRoot}guide/topics/ui/actionbar.html#ActionView">action view in the Action Bar</a>.</p> |
| 139 | </li> |
| 140 | </ul> |
| 141 | </li> |
| 142 | </ul> |
| 143 | |
| 144 | <p>The rest of this document shows you how to create the searchable configuration, searchable |
| 145 | activity, and implement a search interface with either the search dialog or search widget.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 146 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 147 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 148 | <h2 id="SearchableConfiguration">Creating a Searchable Configuration</h2> |
| 149 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 150 | <p>The first thing you need is an XML file called the searchable configuration. It configures |
| 151 | certain UI aspects of the search dialog or widget and defines how features such as suggestions and |
| 152 | voice search behave. This file is traditionally named {@code searchable.xml} and must be saved in |
| 153 | the {@code res/xml/} project directory.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 154 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 155 | <p class="note"><strong>Note:</strong> The system uses this file to instantiate a {@link |
| 156 | android.app.SearchableInfo} object, but you cannot create this object yourself at |
| 157 | runtime—you must declare the searchable configuration in XML.</p> |
| 158 | |
| 159 | <p>The searchable configuration file must include the <a |
| 160 | href="{@docRoot}guide/topics/search/searchable-config.html#searchable-element">{@code |
| 161 | <searchable>}</a> element as the root node and specify one |
| 162 | or more attributes. For example:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 163 | |
| 164 | <pre> |
| 165 | <?xml version="1.0" encoding="utf-8"?> |
| 166 | <searchable xmlns:android="http://schemas.android.com/apk/res/android" |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 167 | android:label="@string/app_label" |
| 168 | android:hint="@string/search_hint" > |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 169 | </searchable> |
| 170 | </pre> |
| 171 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 172 | <p>The {@code android:label} attribute is the only required attribute. It points to a string |
| 173 | resource, which should be the application name. This label isn't actually visible to the |
| 174 | user until you enable search suggestions for Quick Search Box. At that point, this label is visible |
| 175 | in the list of Searchable items in the system Settings.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 176 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 177 | <p>Though it's not required, we recommend that you always include the {@code android:hint} |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 178 | attribute, which provides a hint string in the search box before users |
| 179 | enters a query. The hint is important because it provides important clues to users about what |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 180 | they can search.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 181 | |
| 182 | <p class="note"><strong>Tip:</strong> For consistency among other |
| 183 | Android applications, you should format the string for {@code android:hint} as "Search |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 184 | <content-or-product>". For example, "Search songs and artists" or "Search |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 185 | YouTube".</p> |
| 186 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 187 | <p>The <a |
| 188 | href="{@docRoot}guide/topics/search/searchable-config.html#searchable-element">{@code |
| 189 | <searchable>}</a> element accepts several other attributes. However, you don't need |
| 190 | most attributes until you add features such as <a href="#SearchSuggestions">search suggestions</a> |
| 191 | and <a href="#VoiceSearch">voice search</a>. For detailed information about the searchable |
| 192 | configuration file, see the <a |
| 193 | href="{@docRoot}guide/topics/search/searchable-config.html">Searchable Configuration</a> reference |
| 194 | document.</p> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 195 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 196 | |
| 197 | |
| 198 | <h2 id="SearchableActivity">Creating a Searchable Activity</h2> |
| 199 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 200 | <p>A searchable activity is the {@link android.app.Activity} in your application that performs |
| 201 | searches based on a query string and presents the search results.</p> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 202 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 203 | <p>When the user executes a search in the search dialog or widget, the system starts your |
| 204 | searchable activity and delivers it the search query in an {@link |
| 205 | android.content.Intent} with the {@link android.content.Intent#ACTION_SEARCH} action. Your |
| 206 | searchable activity retrieves the query from the intent's {@link android.app.SearchManager#QUERY |
| 207 | QUERY} extra, then searches your data and presents the results.</p> |
| 208 | |
| 209 | <p>Because you may include the search dialog or widget in any other activity in your application, |
| 210 | the system must know which activity is your searchable activity, so it can properly deliver the |
| 211 | search query. So, you must first declare your searchable activity in the Android manifest file.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 212 | |
| 213 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 214 | <h3 id="DeclaringSearchableActivity">Declaring a searchable activity</h3> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 215 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 216 | <p>If you don't have one already, create an {@link android.app.Activity} that will perform |
| 217 | searches and present results. You don't need to implement the search functionality yet—just |
| 218 | create an activity that you can declare in the manifest. Inside the manifest's <a |
| 219 | href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> |
| 220 | element:</p> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 221 | <ol> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 222 | <li>Declare the activity to accept the {@link android.content.Intent#ACTION_SEARCH} intent, in an |
| 223 | <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code |
| 224 | <intent-filter>}</a> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 225 | element.</li> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 226 | <li>Specify the searchable configuration to use, in a <a |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 227 | href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 228 | element.</li> |
| 229 | </ol> |
| 230 | |
| 231 | <p>For example:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 232 | |
| 233 | <pre> |
| 234 | <application ... > |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 235 | <activity android:name=".SearchableActivity" > |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 236 | <intent-filter> |
| 237 | <action android:name="android.intent.action.SEARCH" /> |
| 238 | </intent-filter> |
| 239 | <meta-data android:name="android.app.searchable" |
| 240 | android:resource="@xml/searchable"/> |
| 241 | </activity> |
| 242 | ... |
| 243 | </application> |
| 244 | </pre> |
| 245 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 246 | <p>The {@code <meta-data>} element must include the {@code android:name} attribute with a |
| 247 | value of {@code "android.app.searchable"} and the {@code android:resource} attribute with a |
| 248 | reference to the searchable configuration file (in this example, it |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 249 | refers to the {@code res/xml/searchable.xml} file).</p> |
| 250 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 251 | <p class="note"><strong>Note:</strong> The <a |
| 252 | href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code |
| 253 | <intent-filter>}</a> does not need a <a |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 254 | href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a> with the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 255 | {@code DEFAULT} value (which you usually see in <a |
| 256 | href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> elements), |
| 257 | because the system delivers the {@link android.content.Intent#ACTION_SEARCH} intent explicitly to |
| 258 | your searchable activity, using its component name.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 259 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 260 | |
| 261 | |
| 262 | <h3 id="PerformingSearch">Performing a search</h3> |
| 263 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 264 | <p>Once you have declared your searchable activity in the manifest, performing a search in your |
| 265 | searchable activity involves three steps:</p> |
| 266 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 267 | <ol> |
| 268 | <li><a href="#ReceivingTheQuery">Receiving the query</a></li> |
| 269 | <li><a href="#SearchingYourData">Searching your data</a></li> |
| 270 | <li><a href="#PresentingTheResults">Presenting the results</a></li> |
| 271 | </ol> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 272 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 273 | <p>Traditionally, your search results should be presented in a {@link android.widget.ListView}, so |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 274 | you might want your searchable activity to extend {@link android.app.ListActivity}. It includes |
| 275 | a default layout with a single {@link android.widget.ListView} and provides several |
| 276 | convenience methods for working with the {@link android.widget.ListView}.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 277 | |
| 278 | |
| 279 | <h4 id="ReceivingTheQuery">Receiving the query</h4> |
| 280 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 281 | <p>When a user executes a search from the search dialog or widget, the system starts your |
| 282 | searchable activity and sends it a {@link android.content.Intent#ACTION_SEARCH} intent. This intent |
| 283 | carries the search query in the |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 284 | {@link android.app.SearchManager#QUERY QUERY} string extra. You must check for |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 285 | this intent when the activity starts and extract the string. For example, here's how you can get the |
| 286 | search query when your searchable activity starts:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 287 | |
| 288 | <pre> |
| 289 | @Override |
| 290 | public void onCreate(Bundle savedInstanceState) { |
| 291 | super.onCreate(savedInstanceState); |
| 292 | setContentView(R.layout.search); |
| 293 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 294 | // Get the intent, verify the action and get the query |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 295 | Intent intent = getIntent(); |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 296 | if (Intent.ACTION_SEARCH.equals(intent.getAction())) { |
| 297 | String query = intent.getStringExtra(SearchManager.QUERY); |
| 298 | doMySearch(query); |
| 299 | } |
| 300 | } |
| 301 | </pre> |
| 302 | |
| 303 | <p>The {@link android.app.SearchManager#QUERY QUERY} string is always included with |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 304 | the {@link android.content.Intent#ACTION_SEARCH} intent. In this example, the query is |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 305 | retrieved and passed to a local {@code doMySearch()} method where the actual search operation |
| 306 | is done.</p> |
| 307 | |
| 308 | |
| 309 | <h4 id="SearchingYourData">Searching your data</h4> |
| 310 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 311 | <p>The process of storing and searching your data is unique to your application. |
| 312 | You can store and search your data in many ways, but this guide does not show you how to store your |
| 313 | data and search it. Storing and searching your data is something you should carefully consider in |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 314 | terms of your needs and your data format. However, here are some tips you might be able to |
| 315 | apply:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 316 | |
| 317 | <ul> |
| 318 | <li>If your data is stored in a SQLite database on the device, performing a full-text search |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 319 | (using FTS3, rather than a {@code LIKE} query) can provide a more robust search across text data and |
| 320 | can produce results significantly faster. See <a href="http://sqlite.org/fts3.html">sqlite.org</a> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 321 | for information about FTS3 and the {@link android.database.sqlite.SQLiteDatabase} class for |
| 322 | information about SQLite on Android. Also look at the <a |
| 323 | href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable Dictionary</a> sample |
| 324 | application to see a complete SQLite implementation that performs searches with FTS3.</li> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 325 | <li>If your data is stored online, then the perceived search performance might be |
| 326 | inhibited by the user's data connection. You might want to display a spinning progress wheel until |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 327 | your search returns. See {@link android.net} for a reference of network APIs and <a |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 328 | href="{@docRoot}guide/topics/ui/dialogs.html#ProgressDialog">Creating a Progress Dialog</a> |
| 329 | for information about how to display a progress wheel.</li> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 330 | </ul> |
| 331 | |
| 332 | |
| 333 | <div class="sidebox-wrapper"> |
| 334 | <div class="sidebox"> |
| 335 | <h2>About Adapters</h2> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 336 | <p>An {@link android.widget.Adapter} binds each item from a set of data into a |
| 337 | {@link android.view.View} object. When the {@link android.widget.Adapter} |
| 338 | is applied to a {@link android.widget.ListView}, each piece of data is inserted as an individual |
| 339 | view into the list. {@link |
| 340 | android.widget.Adapter} is just an interface, so implementations such as {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 341 | android.widget.CursorAdapter} (for binding data from a {@link android.database.Cursor}) are needed. |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 342 | If none of the existing implementations work for your data, then you can implement your own from |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 343 | {@link android.widget.BaseAdapter}. Install the SDK Samples package for API Level 4 to see the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 344 | original version of the Searchable Dictionary, which creates a custom adapter to read data from |
| 345 | a file.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 346 | </div> |
| 347 | </div> |
| 348 | |
| 349 | <p>Regardless of where your data lives and how you search it, we recommend that you return search |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 350 | results to your searchable activity with an {@link android.widget.Adapter}. This way, you can easily |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 351 | present all the search results in a {@link android.widget.ListView}. If your data comes from a |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 352 | SQLite database query, you can apply your results to a {@link android.widget.ListView} |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 353 | using a {@link android.widget.CursorAdapter}. If your data comes in some other type of format, then |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 354 | you can create an extension of {@link android.widget.BaseAdapter}.</p> |
| 355 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 356 | |
| 357 | <h4 id="PresentingTheResults">Presenting the results</h4> |
| 358 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 359 | <p>As discussed above, the recommended UI for your search results is a {@link |
| 360 | android.widget.ListView}, so you might want your searchable activity to extend {@link |
| 361 | android.app.ListActivity}. You can then call {@link |
| 362 | android.app.ListActivity#setListAdapter(ListAdapter) setListAdapter()}, passing it an {@link |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 363 | android.widget.Adapter} that is bound to your data. This injects all the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 364 | search results into the activity {@link android.widget.ListView}.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 365 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 366 | <p>For more help presenting your results in a list, see the {@link android.app.ListActivity} |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 367 | documentation.</p> |
| 368 | |
| 369 | <p>Also see the <a |
| 370 | href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable Dictionary</a> sample |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 371 | for an a complete demonstration of how to search an SQLite database and use an |
| 372 | {@link android.widget.Adapter} to provide results in a {@link android.widget.ListView}.</p> |
| 373 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 374 | |
| 375 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 376 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 377 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 378 | <h2 id="SearchDialog">Using the Search Dialog</h2> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 379 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 380 | <div class="sidebox-wrapper"> |
| 381 | <div class="sidebox"> |
| 382 | <h2>Should I use the search dialog or the widget?</h2> |
| 383 | <p>The answer depends mostly on whether you are developing for Android 3.0 (API Level 11 or |
| 384 | higher), because the {@link android.widget.SearchView} widget was introduced in Android 3.0. So, |
| 385 | if you are developing your application for a version of Android lower than 3.0, the search widget is |
| 386 | not an option and you should use the search dialog to implement your search interface.</p> |
| 387 | <p>If you <em>are</em> developing for Android 3.0 or higher, then the decision depends more on |
| 388 | your needs. In most cases, we recommend that you use the search widget as an "action view" in the |
| 389 | Action Bar. However, it might not be an option for you to put the search |
| 390 | widget in the Action Bar for some reason (perhaps there's not enough space or you don't use the |
| 391 | Action Bar). So, you might instead want to put the search widget somewhere in your activity layout. |
| 392 | And if all else fails, you can still use the search dialog if you prefer to keep the search box |
| 393 | hidden. In fact, you might want to offer both the dialog and the widget in some cases. For more |
| 394 | information about the widget, skip to <a href="#UsingSearchWidget">Using the Search Widget</a>.</p> |
| 395 | </div> |
| 396 | </div> |
| 397 | |
| 398 | <p>The search dialog provides a floating search box at the top of the screen, with the application |
| 399 | icon on the left. The search dialog can provide search suggestions as the user types and, when |
| 400 | the user executes a search, the system sends the search query to a |
| 401 | searchable activity that performs the search. However, if you are developing |
| 402 | your application for devices running Android 3.0, you should consider using the search widget |
| 403 | instead (see the side box).</p> |
| 404 | |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 405 | <p>The search dialog is always hidden by default, until the user activates it. Your application |
| 406 | can activate the search dialog by calling {@link |
| 407 | android.app.Activity#onSearchRequested onSearchRequested()}. However, this method doesn't work |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 408 | until you enable the search dialog for the activity.</p> |
| 409 | |
| 410 | <p>To enable the search dialog, you must indicate to the system which searchable activity should |
| 411 | receive search queries from the search dialog, in order to perform searches. For example, in the |
| 412 | previous section about <a href="#SearchableActivity">Creating a Searchable Activity</a>, a |
| 413 | searchable activity named {@code SearchableActivity} was created. If you want a separate activity, |
| 414 | named {@code OtherActivity}, to show the search dialog and deliver searches to {@code |
| 415 | SearchableActivity}, you must declare in the manifest that {@code SearchableActivity} is the |
| 416 | searchable activity to use for the search dialog in {@code OtherActivity}.</p> |
| 417 | |
| 418 | <p>To declare the searchable activity for an activity's search dialog, |
| 419 | add a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 420 | element inside the respective activity's <a |
| 421 | href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> element. |
| 422 | The <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 423 | element must include the {@code android:value} attribute that specifies the searchable activity's |
| 424 | class name and the {@code android:name} attribute with a value of {@code |
| 425 | "android.app.default_searchable"}.</p> |
| 426 | |
| 427 | <p>For example, here is the declaration for |
| 428 | both a searchable activity, {@code SearchableActivity}, and another activity, {@code |
| 429 | OtherActivity}, which uses {@code SearchableActivity} to perform searches executed from its |
| 430 | search dialog:</p> |
| 431 | |
| 432 | <pre> |
| 433 | <application ... > |
| 434 | <!-- this is the searchable activity; it performs searches --> |
| 435 | <activity android:name=".SearchableActivity" > |
| 436 | <intent-filter> |
| 437 | <action android:name="android.intent.action.SEARCH" /> |
| 438 | </intent-filter> |
| 439 | <meta-data android:name="android.app.searchable" |
| 440 | android:resource="@xml/searchable"/> |
| 441 | </activity> |
| 442 | |
| 443 | <!-- this activity enables the search dialog to initiate searches |
| 444 | in the SearchableActivity --> |
| 445 | <activity android:name=".OtherActivity" ... > |
| 446 | <!-- enable the search dialog to send searches to SearchableActivity --> |
| 447 | <b><meta-data android:name="android.app.default_searchable" |
| 448 | android:value=".SearchableActivity" /></b> |
| 449 | </activity> |
| 450 | ... |
| 451 | </application> |
| 452 | </pre> |
| 453 | |
| 454 | <p>Because the {@code OtherActivity} now includes a <a |
| 455 | href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 456 | element to declare which searchable activity to use for searches, the activity has enabled the |
| 457 | search dialog. |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 458 | While the user is in this activity, the {@link |
| 459 | android.app.Activity#onSearchRequested onSearchRequested()} method activates the search dialog. |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 460 | When the user executes the search, the system starts {@code SearchableActivity} and delivers it |
| 461 | the {@link android.content.Intent#ACTION_SEARCH} intent.</p> |
| 462 | |
| 463 | <p class="note"><strong>Note:</strong> The searchable activity itself provides the search dialog |
| 464 | by default, so you don't need to add this declaration to {@code SearchableActivity}.</p> |
| 465 | |
| 466 | <p>If you want every activity in your application to provide the search dialog, insert the above <a |
| 467 | href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 468 | element as a child of the <a |
| 469 | href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> |
| 470 | element, instead of each <a |
| 471 | href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a>. This |
| 472 | way, every activity inherits the value, provides the search dialog, and delivers searches to |
| 473 | the same searchable activity. (If you have multiple searchable activities, you can override the |
| 474 | default searchable activity by placing a different <a |
| 475 | href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> |
| 476 | declaration inside individual activities.)</p> |
| 477 | |
| 478 | <p>With the search dialog now enabled for your activities, your application is ready to perform |
| 479 | searches.</p> |
| 480 | |
| 481 | |
| 482 | <h3 id="InvokingTheSearchDialog">Invoking the search dialog</h3> |
| 483 | |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 484 | <p>Although some devices provide a dedicated Search button, the behavior of the button may vary |
| 485 | between devices and many devices do not provide a Search button at all. So when using the search |
| 486 | dialog, you <strong>must provide a search button in your UI</strong> that activates the search |
| 487 | dialog by calling {@link android.app.Activity#onSearchRequested()}.</p> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 488 | |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 489 | <p>For instance, you should add a Search button in your <a |
| 490 | href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> or UI |
| 491 | layout that calls {@link android.app.Activity#onSearchRequested()}. For consistency with |
| 492 | the Android system and other apps, you should label your button with the Android Search icon that's |
| 493 | available from the <a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar |
| 494 | Icon Pack</a>.</p> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 495 | |
Scott Main | 911711f | 2012-08-13 18:22:21 -0700 | [diff] [blame] | 496 | <p class="note"><strong>Note:</strong> If your app uses the <a |
| 497 | href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>, then you should not use |
| 498 | the search dialog for your search interface. Instead, use the <a href="#UsingSearchWidget">search |
| 499 | widget</a> as a collapsible view in the action bar.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 500 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 501 | <p>You can also enable "type-to-search" functionality, which activates the search dialog when the |
| 502 | user starts typing on the keyboard—the keystrokes are inserted into the search dialog. You can |
| 503 | enable type-to-search in your activity by calling |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 504 | {@link android.app.Activity#setDefaultKeyMode(int) setDefaultKeyMode}({@link |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 505 | android.app.Activity#DEFAULT_KEYS_SEARCH_LOCAL}) during your activity's |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 506 | {@link android.app.Activity#onCreate(Bundle) onCreate()} method.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 507 | |
| 508 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 509 | <h3 id="LifeCycle">The impact of the search dialog on your activity lifecycle</h3> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 510 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 511 | <p>The search dialog is a {@link android.app.Dialog} that floats at the top of the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 512 | screen. It does not cause any change in the activity stack, so when the search dialog appears, no |
| 513 | lifecycle methods (such as {@link android.app.Activity#onPause()}) are called. Your activity just |
| 514 | loses input focus, as input focus is given to the search dialog. |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 515 | </p> |
| 516 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 517 | <p>If you want to be notified when the search dialog is activated, override the {@link |
| 518 | android.app.Activity#onSearchRequested()} method. When the system calls this method, it is an |
| 519 | indication that your activity has lost input focus to the search dialog, so you can do any |
| 520 | work appropriate for the event (such as pause |
| 521 | a game). Unless you are <a |
| 522 | href="#SearchContextData">passing search context data</a> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 523 | (discussed below), you should end the method by calling the super class implementation. For |
| 524 | example:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 525 | |
| 526 | <pre> |
| 527 | @Override |
| 528 | public boolean onSearchRequested() { |
| 529 | pauseSomeStuff(); |
| 530 | return super.onSearchRequested(); |
| 531 | } |
| 532 | </pre> |
| 533 | |
Scott Main | cf9fe43 | 2012-01-31 19:14:35 -0800 | [diff] [blame] | 534 | <p>If the user cancels search by pressing the <em>Back</em> button, the search dialog closes and the |
| 535 | activity |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 536 | regains input focus. You can register to be notified when the search dialog is |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 537 | closed with {@link android.app.SearchManager#setOnDismissListener(SearchManager.OnDismissListener) |
| 538 | setOnDismissListener()} |
| 539 | and/or {@link android.app.SearchManager#setOnCancelListener(SearchManager.OnCancelListener) |
| 540 | setOnCancelListener()}. You |
| 541 | should need to register only the {@link android.app.SearchManager.OnDismissListener |
| 542 | OnDismissListener}, because it is called every time the search dialog closes. The {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 543 | android.app.SearchManager.OnCancelListener OnCancelListener} only pertains to events in which the |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 544 | user explicitly exited the search dialog, so it is not called when a search is executed (in which |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 545 | case, the search dialog naturally disappears).</p> |
| 546 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 547 | <p>If the current activity is not the searchable activity, then the normal activity lifecycle |
| 548 | events are triggered once the user executes a search (the current activity receives {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 549 | android.app.Activity#onPause()} and so forth, as |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 550 | described in the <a |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 551 | href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 552 | document). If, however, the current activity is the searchable activity, then one of two |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 553 | things happens:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 554 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 555 | <ol type="a"> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 556 | <li>By default, the searchable activity receives the {@link |
| 557 | android.content.Intent#ACTION_SEARCH} intent with a call to {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 558 | android.app.Activity#onCreate(Bundle) onCreate()} and a new instance of the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 559 | activity is brought to the top of the activity stack. There are now two instances of your |
Scott Main | cf9fe43 | 2012-01-31 19:14:35 -0800 | [diff] [blame] | 560 | searchable activity in the activity stack (so pressing the <em>Back</em> button goes back to the |
| 561 | previous |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 562 | instance of the searchable activity, rather than exiting the searchable activity).</li> |
| 563 | <li>If you set {@code android:launchMode} to <code>"singleTop"</code>, then the |
| 564 | searchable activity receives the {@link android.content.Intent#ACTION_SEARCH} intent with a call |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 565 | to {@link android.app.Activity#onNewIntent(Intent)}, passing the new {@link |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 566 | android.content.Intent#ACTION_SEARCH} intent here. For example, here's how you might handle |
| 567 | this case, in which the searchable activity's launch mode is <code>"singleTop"</code>: |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 568 | <pre> |
| 569 | @Override |
| 570 | public void onCreate(Bundle savedInstanceState) { |
| 571 | super.onCreate(savedInstanceState); |
| 572 | setContentView(R.layout.search); |
| 573 | handleIntent(getIntent()); |
| 574 | } |
| 575 | |
| 576 | @Override |
| 577 | protected void onNewIntent(Intent intent) { |
| 578 | setIntent(intent); |
| 579 | handleIntent(intent); |
| 580 | } |
| 581 | |
| 582 | private void handleIntent(Intent intent) { |
| 583 | if (Intent.ACTION_SEARCH.equals(intent.getAction())) { |
| 584 | String query = intent.getStringExtra(SearchManager.QUERY); |
| 585 | doMySearch(query); |
| 586 | } |
| 587 | } |
| 588 | </pre> |
| 589 | |
Scott Main | 369c1c1 | 2010-12-07 11:17:00 -0800 | [diff] [blame] | 590 | <p>Compared to the example code in the section about <a href="#PerformingSearch">Performing a |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 591 | Search</a>, all the code to handle the |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 592 | search intent is now in the {@code handleIntent()} method, so that both {@link |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 593 | android.app.Activity#onCreate(Bundle) |
| 594 | onCreate()} and {@link android.app.Activity#onNewIntent(Intent) onNewIntent()} can execute it.</p> |
| 595 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 596 | <p>When the system calls {@link android.app.Activity#onNewIntent(Intent)}, the activity has |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 597 | not been restarted, so the {@link android.app.Activity#getIntent()} method |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 598 | returns the same intent that was received with {@link |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 599 | android.app.Activity#onCreate(Bundle) onCreate()}. This is why you should call {@link |
| 600 | android.app.Activity#setIntent(Intent)} inside {@link |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 601 | android.app.Activity#onNewIntent(Intent)} (so that the intent saved by the activity is updated in |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 602 | case you call {@link android.app.Activity#getIntent()} in the future).</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 603 | |
| 604 | </li> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 605 | </ol> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 606 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 607 | <p>The second scenario using <code>"singleTop"</code> launch mode is usually ideal, because chances |
| 608 | are good that once a search is done, the user will perform additional searches and it's a bad |
| 609 | experience if your application creates multiple instances of the searchable activity. So, we |
| 610 | recommend that you set your searchable activity to <code>"singleTop"</code> launch mode in the |
| 611 | application manifest. For example:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 612 | |
| 613 | <pre> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 614 | <activity android:name=".SearchableActivity" |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 615 | <b>android:launchMode="singleTop"</b> > |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 616 | <intent-filter> |
| 617 | <action android:name="android.intent.action.SEARCH" /> |
| 618 | </intent-filter> |
| 619 | <meta-data android:name="android.app.searchable" |
| 620 | android:resource="@xml/searchable"/> |
| 621 | </activity> |
| 622 | </pre> |
| 623 | |
| 624 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 625 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 626 | <h3 id="SearchContextData">Passing search context data</h3> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 627 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 628 | <p>In some cases, you can make necessary refinements to the search query inside the searchable |
| 629 | activity, for every search made. However, if you want to refine your search criteria based on the |
| 630 | activity from which the user is performing a search, you can provide additional data in the intent |
| 631 | that the system sends to your searchable activity. You can pass the additional data in the {@link |
| 632 | android.app.SearchManager#APP_DATA} {@link android.os.Bundle}, which is included in the {@link |
| 633 | android.content.Intent#ACTION_SEARCH} intent.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 634 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 635 | <p>To pass this kind of data to your searchable activity, override the {@link |
| 636 | android.app.Activity#onSearchRequested()} method for the activity from which the user can perform a |
| 637 | search, create a {@link android.os.Bundle} with the additional data, and call {@link |
| 638 | android.app.Activity#startSearch startSearch()} to activate the search dialog. |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 639 | For example:</p> |
| 640 | |
| 641 | <pre> |
| 642 | @Override |
| 643 | public boolean onSearchRequested() { |
| 644 | Bundle appData = new Bundle(); |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 645 | appData.putBoolean(SearchableActivity.JARGON, true); |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 646 | startSearch(null, false, appData, false); |
| 647 | return true; |
| 648 | } |
| 649 | </pre> |
| 650 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 651 | <p>Returning "true" indicates that you have successfully handled this callback event and |
| 652 | called {@link android.app.Activity#startSearch startSearch()} to activate |
| 653 | the search dialog. Once the user submits a query, it's delivered to your |
| 654 | searchable activity along with the data you've added. You can extract the extra data from the {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 655 | android.app.SearchManager#APP_DATA} {@link android.os.Bundle} to refine the search. For example:</p> |
| 656 | |
| 657 | <pre> |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 658 | Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA); |
| 659 | if (appData != null) { |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 660 | boolean jargon = appData.getBoolean(SearchableActivity.JARGON); |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 661 | } |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 662 | </pre> |
| 663 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 664 | <p class="caution"><strong>Caution:</strong> Never call the {@link |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 665 | android.app.Activity#startSearch(String,boolean,Bundle,boolean) startSearch()} method from outside |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 666 | the {@link android.app.Activity#onSearchRequested()} callback method. To activate the search dialog |
| 667 | in your activity, always call {@link android.app.Activity#onSearchRequested()}. Otherwise, {@link |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 668 | android.app.Activity#onSearchRequested()} is not called and customizations (such as the addition of |
| 669 | {@code appData} in the above example) are missed.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 670 | |
| 671 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 672 | |
| 673 | <h2 id="UsingSearchWidget">Using the Search Widget</h2> |
| 674 | |
| 675 | <div class="figure" style="width:429px;margin:0"> |
| 676 | <img src="{@docRoot}images/ui/actionbar-actionview.png" alt="" /> |
| 677 | <p class="img-caption"><strong>Figure 2.</strong> The {@link |
| 678 | android.widget.SearchView} widget as an "action view" in the Action Bar.</p> |
| 679 | </div> |
| 680 | |
| 681 | <p>The {@link android.widget.SearchView} widget is available in Android 3.0 and higher. If |
| 682 | you're developing your application for Android 3.0 and have decided to use the search widget, we |
| 683 | recommend that you insert the search widget as an <a |
| 684 | href="{@docRoot}guide/topics/ui/actionbar.html#ActionView">action view in the Action Bar</a>, |
| 685 | instead of using the search dialog (and instead of placing the search widget in your activity |
| 686 | layout). For example, figure 2 shows the search widget in the Action Bar.</p> |
| 687 | |
| 688 | <p>The search widget provides the same functionality as the search dialog. It starts the appropriate |
| 689 | activity when the user executes a search, and it can provide search suggestions and perform voice |
| 690 | search.</p> |
| 691 | |
| 692 | <p class="note"><strong>Note:</strong> When you use the search widget as an action view, you |
| 693 | still might need to support using the search dialog, for cases in which the search widget does |
| 694 | not fit in the Action Bar. See the following section about <a href="#UsingBoth">Using both |
| 695 | the widget and the dialog</a>.</p> |
| 696 | |
| 697 | |
| 698 | <h3 id="ConfiguringWidget">Configuring the search widget</h3> |
| 699 | |
| 700 | <p>After you've created a <a href="#SearchableConfiguration">searchable configuration</a> and a <a |
| 701 | href="#SearchableActivity">searchable activity</a>, as discussed above, you need to enable assisted |
| 702 | search for each {@link android.widget.SearchView}. You can do so by calling {@link |
| 703 | android.widget.SearchView#setSearchableInfo setSearchableInfo()} and passing it the {@link |
| 704 | android.app.SearchableInfo} object that represents your searchable configuration.</p> |
| 705 | |
| 706 | <p>You can get a reference to the {@link android.app.SearchableInfo} by calling {@link |
| 707 | android.app.SearchManager#getSearchableInfo getSearchableInfo()} on {@link |
| 708 | android.app.SearchManager}.</p> |
| 709 | |
| 710 | <p>For example, if you're using a {@link android.widget.SearchView} as an action view in the <a |
| 711 | href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, you should enable the widget |
| 712 | during the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback:</p> |
| 713 | |
| 714 | <pre> |
| 715 | @Override |
| 716 | public boolean onCreateOptionsMenu(Menu menu) { |
| 717 | // Inflate the options menu from XML |
| 718 | MenuInflater inflater = getMenuInflater(); |
| 719 | inflater.inflate(R.menu.options_menu, menu); |
| 720 | |
| 721 | // Get the SearchView and set the searchable configuration |
| 722 | SearchManager searchManager = (SearchManager) {@link android.app.Activity#getSystemService getSystemService}(Context.SEARCH_SERVICE); |
| 723 | SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView(); |
kmccormick | 3b9f0aa | 2013-04-01 18:08:28 -0700 | [diff] [blame] | 724 | // Assumes current activity is the searchable activity |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 725 | searchView.setSearchableInfo(searchManager.getSearchableInfo({@link android.app.Activity#getComponentName()})); |
| 726 | searchView.setIconifiedByDefault(false); // Do not iconify the widget; expand it by default |
| 727 | |
| 728 | return true; |
| 729 | } |
| 730 | </pre> |
| 731 | |
| 732 | <p>That's all you need. The search widget is now configured and the system will deliver search |
| 733 | queries to your searchable activity. You can also enable <a href="#SearchSuggestions">search |
| 734 | suggestions</a> for the search widget.</p> |
| 735 | |
| 736 | <p class="note"><strong>Note:</strong> If you want to handle all user input yourself, you can do so |
| 737 | with some callback methods and event listeners. For more information, see the reference |
| 738 | documentation for {@link android.widget.SearchView} and its nested interfaces for the |
| 739 | appropriate event listeners.</p> |
| 740 | |
Scott Main | b10b48f | 2011-09-13 16:40:52 -0700 | [diff] [blame] | 741 | <p>For more information about action views in the Action Bar, read the <a |
| 742 | href="{@docRoot}guide/topics/ui/actionbar.html#ActionView">Action Bar</a> developer guide (which |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 743 | includes sample code for adding a search widget as an action view).</p> |
| 744 | |
| 745 | |
| 746 | <h3 id="WidgetFeatures">Other search widget features</h3> |
| 747 | |
| 748 | <p>The {@link android.widget.SearchView} widget allows for a few additional features you might |
| 749 | want:</p> |
| 750 | |
| 751 | <dl> |
| 752 | <dt>A submit button</dt> |
| 753 | <dd>By default, there's no button to submit a search query, so the user must press the |
| 754 | "Return" key on the keyboard to initiate a search. You can add a "submit" button by calling |
| 755 | {@link android.widget.SearchView#setSubmitButtonEnabled setSubmitButtonEnabled(true)}.</dd> |
| 756 | <dt>Query refinement for search suggestions</dt> |
| 757 | <dd>When you've enabled search suggestions, you usually expect users to simply select a |
| 758 | suggestion, but they might also want to refine the suggested search query. You can add a button |
| 759 | alongside each suggestion that inserts the suggestion in the search box for refinement by the |
| 760 | user, by calling {@link android.widget.SearchView#setQueryRefinementEnabled |
| 761 | setQueryRefinementEnabled(true)}.</dd> |
| 762 | <dt>The ability to toggle the search box visibility</dt> |
| 763 | <dd>By default, the search widget is "iconified," meaning that it is represented only by a |
| 764 | search icon (a magnifying glass), and expands to show the search box when the user touches it. |
| 765 | As shown above, you can show the search box by default, by calling {@link |
| 766 | android.widget.SearchView#setIconifiedByDefault setIconifiedByDefault(false)}. You can also |
| 767 | toggle the search widget appearance by calling {@link android.widget.SearchView#setIconified |
| 768 | setIconified()}.</dd> |
| 769 | </dl> |
| 770 | |
| 771 | <p>There are several other APIs in the {@link android.widget.SearchView} class that allow you to |
| 772 | customize the search widget. However, most of them are used only when you handle all |
| 773 | user input yourself, instead of using the Android system to deliver search queries and display |
| 774 | search suggestions.</p> |
| 775 | |
| 776 | |
| 777 | <h3 id="UsingBoth">Using both the widget and the dialog</h3> |
| 778 | |
| 779 | <p>If you insert the search widget in the Action Bar as an <a |
| 780 | href="{@docRoot}guide/topics/ui/actionbar.html#ActionView">action view</a>, and you enable it to |
| 781 | appear in the Action Bar "if there is room" (by setting {@code |
| 782 | android:showAsAction="ifRoom"}), then there is a chance that the search widget will not appear |
| 783 | as an action view, but the menu item will appear in the overflow menu. For example, when your |
| 784 | application runs on a smaller screen, there might not be enough room in the Action Bar to display |
| 785 | the search widget along with other action items or navigation elements, so the menu item will |
| 786 | instead appear in the overflow menu. When placed in the overflow menu, the item works like an |
| 787 | ordinary menu item and does not display the action view (the search widget).</p> |
| 788 | |
| 789 | <p>To handle this situation, the menu item to which you've attached the search widget should |
| 790 | activate the search dialog when the user selects it from the overflow menu. In order for it to do |
| 791 | so, you must implement {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} to |
| 792 | handle the "Search" menu item and open the search dialog by calling {@link |
| 793 | android.app.Activity#onSearchRequested onSearchRequested()}.</p> |
| 794 | |
| 795 | <p>For more information about how items in the Action Bar work and how to handle this situation, see |
Scott Main | b10b48f | 2011-09-13 16:40:52 -0700 | [diff] [blame] | 796 | the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action |
| 797 | Bar</a> developer guide.</p> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 798 | |
| 799 | <p>Also see the <a |
Scott Main | 19aad29 | 2011-10-18 16:57:32 -0700 | [diff] [blame] | 800 | href="{@docRoot}resources/samples/SearchableDictionary/src/com/example/android/searchabledict/SearchableDictionary.html" |
| 801 | >Searchable Dictionary</a> for an example implementation using |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 802 | both the dialog and the widget.</p> |
| 803 | |
| 804 | |
| 805 | |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 806 | <h2 id="VoiceSearch">Adding Voice Search</h2> |
| 807 | |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 808 | <p>You can add voice search functionality to your search dialog or widget by adding the {@code |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 809 | android:voiceSearchMode} attribute to your searchable configuration. This adds a voice search |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 810 | button that launches a voice prompt. When the user |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 811 | has finished speaking, the transcribed search query is sent to your searchable |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 812 | activity.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 813 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 814 | <p>For example:</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 815 | |
| 816 | <pre> |
| 817 | <?xml version="1.0" encoding="utf-8"?> |
| 818 | <searchable xmlns:android="http://schemas.android.com/apk/res/android" |
| 819 | android:label="@string/search_label" |
| 820 | android:hint="@string/search_hint" |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 821 | <b>android:voiceSearchMode="showVoiceSearchButton|launchRecognizer"</b> > |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 822 | </searchable> |
| 823 | </pre> |
| 824 | |
| 825 | <p>The value {@code showVoiceSearchButton} is required to enable voice |
| 826 | search, while the second value, {@code launchRecognizer}, specifies that the voice search button |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 827 | should launch a recognizer that returns the transcribed text to the searchable activity.</p> |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 828 | |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 829 | <p>You can provide additional attributes to specify the voice search behavior, such |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 830 | as the language to be expected and the maximum number of results to return. See the <a |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 831 | href="searchable-config.html">Searchable Configuration</a> reference for more information about the |
Scott Main | b3b2b4f | 2010-02-12 17:19:02 -0800 | [diff] [blame] | 832 | available attributes.</p> |
| 833 | |
| 834 | <p class="note"><strong>Note:</strong> Carefully consider whether voice search is appropriate for |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 835 | your application. All searches performed with the voice search button are immediately sent to |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 836 | your searchable activity without a chance for the user to review the transcribed query. Sufficiently |
Scott Main | 5e892d8 | 2010-05-25 17:04:01 -0700 | [diff] [blame] | 837 | test the voice recognition and ensure that it understands the types of queries that |
| 838 | the user might submit inside your application.</p> |
Scott Main | abdf0d5 | 2011-02-08 10:20:27 -0800 | [diff] [blame] | 839 | |
| 840 | |
| 841 | |
| 842 | <h2 id="SearchSuggestions">Adding Search Suggestions</h2> |
| 843 | |
| 844 | <div class="figure" style="width:250px;margin:0"> |
| 845 | <img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" /> |
| 846 | <p class="img-caption"><strong>Figure 3.</strong> Screenshot of a search dialog with custom |
| 847 | search suggestions.</p> |
| 848 | </div> |
| 849 | |
| 850 | <p>Both the search dialog and the search widget can provide search suggestions as the user |
| 851 | types, with assistance from the Android system. The system manages the list of suggestions and |
| 852 | handles the event when the user selects a suggestion.</p> |
| 853 | |
| 854 | <p>You can provide two kinds of search suggestions:</p> |
| 855 | |
| 856 | <dl> |
| 857 | <dt>Recent query search suggestions</dt> |
| 858 | <dd>These suggestions are simply words that the user previously used as search queries in |
| 859 | your application. |
| 860 | <p>See <a href="adding-recent-query-suggestions.html">Adding Recent Query |
| 861 | Suggestions</a>.</p></dd> |
| 862 | <dt>Custom search suggestions</dt> |
| 863 | <dd>These are search suggestions that you provide from your own data source, to help users |
| 864 | immediately select the correct spelling or item they are searching for. Figure 3 shows an |
| 865 | example of custom suggestions for a dictionary application—the user can select a suggestion |
| 866 | to instantly go to the definition. |
| 867 | <p>See <a href="adding-custom-suggestions.html">Adding Custom |
| 868 | Suggestions</a></p></dd> |
| 869 | </dl> |
| 870 | |