searchable-config.jd revision b3b2b4f2def1719852cdffd8a190ee066b81b598
1page.title=Searchable Configuration 2parent.title=Search 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8<h2>See also</h2> 9<ol> 10 <li><a href="search-dialog.html">Using the Android Search Dialog</a></li> 11 <li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li> 12 <li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li> 13</ol> 14</div> 15</div> 16 17<p>In order to utilize the Android search framework and provide a custom search dialog, your 18application must provide a search 19configuration in the form of an XML resource. This document describes the search configuration XML 20in terms of its syntax and usage. For a more complete discussion about how to implement search 21features for your application, see the companion documents about <a 22href="index.html">Search</a>.</p> 23 24<dl class="xml"> 25 26<dt>file location:</dt> 27<dd><code>res/xml/<em>filename</em>.xml</code><br/> 28The filename will be used as the resource ID.</dd> 29 30<dt>syntax:</dt> 31<dd> 32<pre class="stx"> 33<?xml version="1.0" encoding="utf-8"?> 34<<a href="#searchable-element">searchable</a> xmlns:android="http://schemas.android.com/apk/res/android" 35 android:label="<em>string resource</em>" 36 android:hint="<em>string resource</em>" 37 android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"] 38 android:searchButtonText="<em>string resource</em>" 39 android:inputType="<em>{@link android.R.attr#inputType}</em>" 40 android:imeOptions="<em>{@link android.R.attr#imeOptions}</em>" 41 android:searchSuggestAuthority="<em>string</em>" 42 android:searchSuggestPath="<em>string</em>" 43 android:searchSuggestSelection="<em>string</em>" 44 android:searchSuggestIntentAction="<em>string</em>" 45 android:searchSuggestIntentData="<em>string</em>" 46 android:searchSuggestThreshold="<em>int</em>" 47 android:includeInGlobalSearch=["true" | "false"] 48 android:searchSettingsDescription="<em>string resource</em>" 49 android:queryAfterZeroResults=["true" | "false"] 50 android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"] 51 android:voiceLanguageModel=["free-form" | "web_search"] 52 android:voicePromptText="<em>string resource</em>" 53 android:voiceLanguage="<em>string</em>" 54 android:voiceMaxResults="<em>int</em>" 55 > 56 <<a href="#actionkey-element">actionkey</a> 57 android:keycode="<em>{@link android.view.KeyEvent KEYCODE}</em>" 58 android:queryActionMsg="<em>string</em>" 59 android:suggestActionMsg="<em>string</em>" 60 android:suggestActionMsgColumn="<em>string</em>" > 61</searchable> 62</pre> 63</dd> 64 65<dt>elements:</dt> 66<dd> 67<dl class="tag-list"> 68 <dt id="searchable-element"><code><searchable></code></dt> 69 <dd>Defines all search configurations used with the search dialog. 70 <p class="caps">attributes:</p> 71 <dl class="atn-list"> 72 <dt><code>android:label</code></dt> 73 <dd><em>String resource</em>. <strong>Required</strong>. This is the name of your application. 74It should normally be the same as the name applied to the {@code android:label} attribute of your <a 75href="{@docRoot}guide/topics/manifest/activity-element.html#label">{@code <activity>}</a> or 76<a href="{@docRoot}guide/topics/manifest/application-element.html#label">{@code 77<application>}</a> manifest element. This is only visible to the user when you set 78<code>android:includeInGlobalSearch</code> "true", in which case, this label is used to identify 79your application as a searchable item in the system's search settings.</dd> 80 <dt><code>android:hint</code></dt> 81 <dd><em>String resource</em>. The text to display in the search text field when no text has 82 been entered. This is recommended in order to provide a hint to the user about what 83content is searchable. For consistency among other Android applications, you should format the 84string for {@code android:hint} as "Search <em><content-or-product></em>". For example, 85"Search songs and artists" or "Search YouTube".</dd> 86 <dt><code>android:searchMode</code></dt> 87 <dd><em>Keyword</em>. Sets additional modes that control the search presentation. 88Specifically, the available modes define how the query text in the search dialog's text box 89should be rewritten when a suggestion is focused. The following mode values are accepted: 90 <table> 91 <tr><th>Value</th><th>Description</th></tr> 92 <tr> 93 <td><code>"queryRewriteFromData"</code></td> 94 <td>If set, this causes the suggestion column 95 {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} to be considered as the 96text for suggestion query 97 rewriting. This should only be used when the values in 98 {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user 99inspection and editing - 100 typically, HTTP/HTTPS Uri's.</td> 101 </tr> 102 <tr> 103 <td><code>"queryRewriteFromText"</code></td> 104 <td>If set, this causes the suggestion 105 column {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1} to be considered as the 106text for suggestion query 107 rewriting. This should be used for suggestions in which no query 108 text is provided and the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} 109values are not suitable 110 for user inspection and editing.</td> 111 </tr> 112 </table> 113 <p>For more information, see the discussion about rewriting the query text in <a 114href="adding-custom-suggestions.html#RewritingQueryText">Adding Custom Suggestions</a>.</p> 115 </dd> 116 <dt><code>android:searchButtonText</code></dt> 117 <dd><em>String resource</em>. The text to display in the button that executes the search. By 118default, the button shows a search icon (a magnifying glass), which is ideal for 119internationalization.</dd> 120 <dt><code>android:inputType</code></dt> 121 <dd><em>Keyword</em>. Defines the type of input method (soft-keyboard) to use with the search 122dialog. For most searches, in which free form text is expected, this attribute is not needed and 123the default input method should be used. See {@link android.R.attr#inputType} for a list of suitable 124values for this attribute.</dd> 125 <dt><code>android:imeOptions</code></dt> 126 <dd><em>Keyword</em>. Supplies additional options for the input method. 127 For most searches, in which free form text is expected, this attribute is not needed, 128 and will default to "actionSearch" (provides the "search" button instead of a carriage 129return). See {@link android.R.attr#imeOptions} for a list of suitable values for this attribute. 130 </dd> 131 </dl> 132 133 <p>If you have defined a content provider to generate search suggestions, you need to 134 define additional attributes in order to configure communications with the Content 135 Provider. When providing search suggestions, you'll need some of the following 136 {@code <searchable>} attributes:</p><br/> 137 138 <dl class="atn-list"> 139 <dt><code>android:searchSuggestAuthority</code></dt> 140 <dd><em>String</em>. <strong>Required to provide search suggestions</strong>. 141 This value must match the authority string provided in the {@code android:authorities} 142attribute of the {@code <provider>} element.</dd> 143 <dt><code>android:searchSuggestPath</code></dt> 144 <dd><em>String</em>. This path will be used as a portion of the suggestions 145 query {@link android.net.Uri}, after the prefix and authority, but before 146the standard suggestions path. 147 This is only required if you have a single content provider issuing different types 148 of suggestions (e.g. for different data types) and you need 149 a way to disambiguate the suggestions queries when they are received.</dd> 150 <dt><code>android:searchSuggestSelection</code></dt> 151 <dd><em>String</em>. This value will be passed into your 152 query function as the {@code selection} parameter. Typically this will be a WHERE clause 153for your database, and should contain a single question mark, which is a place-holder for the 154actual query string that has been typed by the user. However, you can also use any non-null 155value to simply trigger the delivery of the query text via the {@code 156selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd> 157 <dt><code>android:searchSuggestIntentAction</code></dt> 158 <dd><em>String</em>. The default Intent action to be used when a user 159 clicks on a search suggestion (such as {@code "android.intent.action.VIEW"}). 160 If not overridden by the selected suggestion (via the {@link 161android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value will 162 be placed in the action field of the {@link android.content.Intent} when the 163 user clicks a suggestion.</dd> 164 <dt><code>android:searchSuggestIntentData</code></dt> 165 <dd><em>String</em>. The default Intent data to be used when a user 166 clicks on a search suggestion. 167 If not overridden by the selected suggestion (via the {@link 168android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value will be 169 placed in the data field of the {@link android.content.Intent} when the user clicks 170 a suggestion.</dd> 171 <dt><code>android:searchSuggestThreshold</code></dt> 172 <dd><em>Integer</em>. The minimum number of characters needed to 173 trigger a suggestion look-up. Only guarantees that a source will not be 174 queried for anything shorter than the threshold. The default value is 0.</dd> 175 </dl> 176 177 <p>For more information about the above attributes for search suggestions, see the guides for 178 <a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a> and 179 <a href="adding-custom-suggestions.html">Adding Custom Suggestions</a>.</p> 180 181 <p>Beyond providing search suggestions while using your application's search dialog, you 182 can also configure your search suggestions to be made available to Quick Search Box, 183 which will allow users so receive search suggestions from your application content from outside 184 your application. When providing search suggestions to Quick Search Box, you'll need some of the 185 following {@code <searchable>} attributes:</p><br/> 186 187 <dl class="atn-list"> 188 <dt><code>android:includeInGlobalSearch</code></dt> 189 <dd><em>Boolean</em>. <strong>Required to provide search suggestions in 190 Quick Search Box</strong>. "true" if you want your suggestions to be 191 included in the globally accessible Quick Search Box. Note that the user must 192 still enable your application as a searchable item in the system search settings in order 193 for your suggestions to appear in Quick Search Box.</dd> 194 <dt><code>android:searchSettingsDescription</code></dt> 195 <dd><em>String</em>. Provides a brief description of the search suggestions that you provide 196to Quick Search Box, which will be displayed in the searchable items entry for your application. 197Your description should concisely describe the content that is searchable. For example, "Artists, 198albums, and tracks" for a music application, or "Saved notes" for a notepad application.</dd> 199 <dt><code>android:queryAfterZeroResults</code></dt> 200 <dd><em>Boolean</em>. "true" if you want your content provider to be invoked for 201 supersets of queries that have returned zero results for in the past. For example, if a 202 source returned zero results for "bo", it would be ignored for "bob". If "false", 203 this source will only be ignored for a single session; the next time the search dialog 204 is invoked, all sources will be queried. The default value is false.</dd> 205 </dl> 206 207 <p>To enable voice search for your search dialog, you'll need some of the 208 following {@code <searchable>} attributes:</p><br/> 209 210 <dl class="atn-list"> 211 <dt><code>android:voiceSearchMode</code></dt> 212 <dd><em>Keyword</em>. <strong>Required to provide voice search capabilities</strong>. 213 Enables voice search for the search dialog, with a specific mode for voice search. 214 (Voice search may not be provided by the device, in which case these flags will 215 have no effect.) The following mode values are accepted: 216 <table> 217 <tr><th>Value</th><th>Description</th></tr> 218 <tr> 219 <td><code>"showVoiceSearchButton"</code></td> 220 <td>Display a voice search button. This only 221 takes effect if voice search is available on the device. If set, then either 222 {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be set 223 (separated by the pipe | character).</td> 224 </tr> 225 <tr> 226 <td><code>"launchWebSearch"</code></td> 227 <td>The voice search button will take the user directly 228 to a built-in voice web search activity. Most applications will not use this flag, as 229 it will take the user away from the Activity in which search was invoked.</td> 230 </tr> 231 <tr> 232 <td><code>"launchRecognizer"</code></td> 233 <td>The voice search button will take 234 the user directly to a built-in voice recording activity. This Activity 235 will prompt the user to speak, transcribe the spoken text, and forward the resulting 236 query text to the searchable Activity, just as if the user had typed it into the 237 search UI and clicked the search button.</td> 238 </tr> 239 </table> 240 </dd> 241 <dt><code>android:voiceLanguageModel</code></dt> 242 <dd><em>Keyword</em>. The language model that 243 should be used by the voice recognition system. The following values are accepted: 244 <table> 245 <tr><th>Value</th><th>Description</th></tr> 246 <tr> 247 <td><code>"free_form"</code></td> 248 <td>Use a language model based on free-form speech recognition. This is the 249default.</td> 250 </tr> 251 <tr> 252 <td><code>"web_search"</code></td> 253 <td>Use a language model based on web search terms.</td> 254 </tr> 255 </table> 256 <p>Also see 257 {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL} for more 258 information.</p></dd> 259 <dt><code>android:voicePromptText</code></dt> 260 <dd><em>String</em>. An additional message to display in the voice input dialog.</dd> 261 <dt><code>android:voiceLanguage</code></dt> 262 <dd><em>String</em>. The spoken language to be expected, expressed as the string value of 263a constants in {@link java.util.Locale} (for example, {@code "de"} for German or {@code "fr"} for 264French). This is only needed if it is different from the current value of {@link 265java.util.Locale#getDefault() Locale.getDefault()}.</dd> 266 <dt><code>android:voiceMaxResults</code></dt> 267 <dd><em>Integer</em>. Forces the maximum number of results to return, 268 including the "best" result which will always be provided as the {@link 269android.content.Intent#ACTION_SEARCH} Intent's primary 270 query. Must be 1 or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS} to 271get the results from the Intent. 272 If not provided, the recognizer will choose how many results to return.</dd> 273 </dl> 274 </dd> <!-- end searchable element --> 275 276 277 <dt id="actionkey-element"><code><actionkey></code></dt> 278 <dd>Defines a shortcut key for a search action, in order to provide special behaviors at the touch 279of a button, based on the current query or selected suggestion. For example, the Contacts 280application enables the device call key for suggestions. So, when 281the user focuses on a search suggestion using the directional controls and then presses the call 282key, the application will immediately initiate a phone call to the suggested contact. See the 283{@link android.app.SearchManager} for more information about action keys. 284 <p class="caps">attributes:</p> 285 <dl class="atn-list"> 286 <dt><code>android:keycode</code></dt> 287 <dd><em>String</em>. <strong>Required</strong>. A key code from {@link 288android.view.KeyEvent} that represents the action key 289 you wish to respond to (for example {@code "KEYCODE_CALL"}). This will be added to the 290 {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your 291 searchable Activity. To examine the key code, use 292 {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. 293 In addition to the key code, you must also provide one or more of 294 the action specifier attributes below. Not all action keys 295are actually supported using this mechanism, as many of them are used for typing, 296 navigation, or system functions. Note that although each of the action message elements are 297optional, at least one must be present for the action key to have any effect.</dd> 298 <dt><code>android:queryActionMsg</code></dt> 299 <dd><em>String</em>. An action message to be sent if the action key is pressed while the 300user is simply entering query text. This will be added to the 301 {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is 302 passed to your searchable Activity. To examine the string, use 303 {@link android.content.Intent#getStringExtra 304 getStringExtra(SearchManager.ACTION_MSG)}.</dd> 305 <dt><code>android:suggestActionMsg</code></dt> 306 <dd><em>String</em>. An action message to be sent if the action key is pressed while a 307 suggestion is being displayed and is currently selected. This will be added to the 308 Intent that is passed to your searchable Activity (using the action you've defined for 309 suggestions). To examine the string, 310 use {@link android.content.Intent#getStringExtra 311 getStringExtra(SearchManager.ACTION_MSG)}. Note that this should only be used if all your 312suggestions support this action key. If not all suggestions can handle the same action key, then 313you must instead use the following {@code android:suggestActionMsgColumn} attribute.</dd> 314 <dt><code>android:suggestActionMsgColumn</code></dt> 315 <dd><em>String</em>. The name of the column in your content provider that defines the 316action message for this action key, which is to be sent if the action key is pressed while a 317 suggestion is being displayed and is currently selected. This attribute lets you control the 318action key on a suggestion-by-suggestion basis, because, instead of using the {@code 319android:suggestActionMsg} attribute to define the action message for all suggestions, each entry in 320your content provider provides its own action message. First, you must define a column in your 321content provider for each suggestion to provide an action message, then provide the name of that 322column in this attribute. The search manager will look at your suggestion cursor, 323 using the string provided here in order to select your action message column, and 324 then select the action message string from the cursor. That string will be added to the 325 Intent that is passed to your searchable Activity (using the action you've defined for 326 suggestions). To examine the string, use {@link 327android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data 328does not exist for the selected suggestion, the action key will be ignored.</dd> 329 </dl> 330 </dd><!-- end action key --> 331 </dl> 332</dd><!-- end elements --> 333 334 335<dt>example:</dt> 336<dd>XML file saved at <code>res/xml/searchable.xml</code>: 337<pre> 338<?xml version="1.0" encoding="utf-8"?> 339<searchable xmlns:android="http://schemas.android.com/apk/res/android" 340 android:label="@string/search_label" 341 android:hint="@string/search_hint" 342 android:searchSuggestAuthority="dictionary" 343 android:searchSuggestIntentAction="android.intent.action.VIEW" 344 android:includeInGlobalSearch="true" 345 android:searchSettingsDescription="@string/settings_description" > 346</searchable> 347</pre> 348 349</dd> <!-- end example --> 350 351 352</dl> 353 354 355 356 357