| page.title=Searchable Configuration |
| parent.title=Search |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>See also</h2> |
| <ol> |
| <li><a href="search-dialog.html">Using the Android Search Dialog</a></li> |
| <li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li> |
| <li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>In order to utilize the Android search framework and provide a custom search dialog, your |
| application must provide a search |
| configuration in the form of an XML resource. This document describes the search configuration XML |
| in terms of its syntax and usage. For a more complete discussion about how to implement search |
| features for your application, see the companion documents about <a |
| href="index.html">Search</a>.</p> |
| |
| <dl class="xml"> |
| |
| <dt>file location:</dt> |
| <dd><code>res/xml/<em>filename</em>.xml</code><br/> |
| The filename will be used as the resource ID.</dd> |
| |
| <dt>syntax:</dt> |
| <dd> |
| <pre class="stx"> |
| <?xml version="1.0" encoding="utf-8"?> |
| <<a href="#searchable-element">searchable</a> xmlns:android="http://schemas.android.com/apk/res/android" |
| android:label="<em>string resource</em>" |
| android:hint="<em>string resource</em>" |
| android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"] |
| android:searchButtonText="<em>string resource</em>" |
| android:inputType="<em>{@link android.R.attr#inputType}</em>" |
| android:imeOptions="<em>{@link android.R.attr#imeOptions}</em>" |
| android:searchSuggestAuthority="<em>string</em>" |
| android:searchSuggestPath="<em>string</em>" |
| android:searchSuggestSelection="<em>string</em>" |
| android:searchSuggestIntentAction="<em>string</em>" |
| android:searchSuggestIntentData="<em>string</em>" |
| android:searchSuggestThreshold="<em>int</em>" |
| android:includeInGlobalSearch=["true" | "false"] |
| android:searchSettingsDescription="<em>string resource</em>" |
| android:queryAfterZeroResults=["true" | "false"] |
| android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"] |
| android:voiceLanguageModel=["free-form" | "web_search"] |
| android:voicePromptText="<em>string resource</em>" |
| android:voiceLanguage="<em>string</em>" |
| android:voiceMaxResults="<em>int</em>" |
| > |
| <<a href="#actionkey-element">actionkey</a> |
| android:keycode="<em>{@link android.view.KeyEvent KEYCODE}</em>" |
| android:queryActionMsg="<em>string</em>" |
| android:suggestActionMsg="<em>string</em>" |
| android:suggestActionMsgColumn="<em>string</em>" > |
| </searchable> |
| </pre> |
| </dd> |
| |
| <dt>elements:</dt> |
| <dd> |
| <dl class="tag-list"> |
| <dt id="searchable-element"><code><searchable></code></dt> |
| <dd>Defines all search configurations used with the search dialog. |
| <p class="caps">attributes:</p> |
| <dl class="atn-list"> |
| <dt><code>android:label</code></dt> |
| <dd><em>String resource</em>. <strong>Required</strong>. This is the name of your application. |
| It should normally be the same as the name applied to the {@code android:label} attribute of your <a |
| href="{@docRoot}guide/topics/manifest/activity-element.html#label">{@code <activity>}</a> or |
| <a href="{@docRoot}guide/topics/manifest/application-element.html#label">{@code |
| <application>}</a> manifest element. This is only visible to the user when you set |
| <code>android:includeInGlobalSearch</code> "true", in which case, this label is used to identify |
| your application as a searchable item in the system's search settings.</dd> |
| <dt><code>android:hint</code></dt> |
| <dd><em>String resource</em>. The text to display in the search text field when no text has |
| been entered. This is recommended in order to provide a hint to the user about what |
| content is searchable. For consistency among other Android applications, you should format the |
| string for {@code android:hint} as "Search <em><content-or-product></em>". For example, |
| "Search songs and artists" or "Search YouTube".</dd> |
| <dt><code>android:searchMode</code></dt> |
| <dd><em>Keyword</em>. Sets additional modes that control the search presentation. |
| Specifically, the available modes define how the query text in the search dialog's text box |
| should be rewritten when a suggestion is focused. The following mode values are accepted: |
| <table> |
| <tr><th>Value</th><th>Description</th></tr> |
| <tr> |
| <td><code>"queryRewriteFromData"</code></td> |
| <td>If set, this causes the suggestion column |
| {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} to be considered as the |
| text for suggestion query |
| rewriting. This should only be used when the values in |
| {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user |
| inspection and editing - |
| typically, HTTP/HTTPS Uri's.</td> |
| </tr> |
| <tr> |
| <td><code>"queryRewriteFromText"</code></td> |
| <td>If set, this causes the suggestion |
| column {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1} to be considered as the |
| text for suggestion query |
| rewriting. This should be used for suggestions in which no query |
| text is provided and the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} |
| values are not suitable |
| for user inspection and editing.</td> |
| </tr> |
| </table> |
| <p>For more information, see the discussion about rewriting the query text in <a |
| href="adding-custom-suggestions.html#RewritingQueryText">Adding Custom Suggestions</a>.</p> |
| </dd> |
| <dt><code>android:searchButtonText</code></dt> |
| <dd><em>String resource</em>. The text to display in the button that executes the search. By |
| default, the button shows a search icon (a magnifying glass), which is ideal for |
| internationalization.</dd> |
| <dt><code>android:inputType</code></dt> |
| <dd><em>Keyword</em>. Defines the type of input method (soft-keyboard) to use with the search |
| dialog. For most searches, in which free form text is expected, this attribute is not needed and |
| the default input method should be used. See {@link android.R.attr#inputType} for a list of suitable |
| values for this attribute.</dd> |
| <dt><code>android:imeOptions</code></dt> |
| <dd><em>Keyword</em>. Supplies additional options for the input method. |
| For most searches, in which free form text is expected, this attribute is not needed, |
| and will default to "actionSearch" (provides the "search" button instead of a carriage |
| return). See {@link android.R.attr#imeOptions} for a list of suitable values for this attribute. |
| </dd> |
| </dl> |
| |
| <p>If you have defined a content provider to generate search suggestions, you need to |
| define additional attributes in order to configure communications with the Content |
| Provider. When providing search suggestions, you'll need some of the following |
| {@code <searchable>} attributes:</p><br/> |
| |
| <dl class="atn-list"> |
| <dt><code>android:searchSuggestAuthority</code></dt> |
| <dd><em>String</em>. <strong>Required to provide search suggestions</strong>. |
| This value must match the authority string provided in the {@code android:authorities} |
| attribute of the {@code <provider>} element.</dd> |
| <dt><code>android:searchSuggestPath</code></dt> |
| <dd><em>String</em>. This path will be used as a portion of the suggestions |
| query {@link android.net.Uri}, after the prefix and authority, but before |
| the standard suggestions path. |
| This is only required if you have a single content provider issuing different types |
| of suggestions (e.g. for different data types) and you need |
| a way to disambiguate the suggestions queries when they are received.</dd> |
| <dt><code>android:searchSuggestSelection</code></dt> |
| <dd><em>String</em>. This value will be passed into your |
| query function as the {@code selection} parameter. Typically this will be a WHERE clause |
| for your database, and should contain a single question mark, which is a place-holder for the |
| actual query string that has been typed by the user. However, you can also use any non-null |
| value to simply trigger the delivery of the query text via the {@code |
| selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd> |
| <dt><code>android:searchSuggestIntentAction</code></dt> |
| <dd><em>String</em>. The default Intent action to be used when a user |
| clicks on a search suggestion (such as {@code "android.intent.action.VIEW"}). |
| If not overridden by the selected suggestion (via the {@link |
| android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value will |
| be placed in the action field of the {@link android.content.Intent} when the |
| user clicks a suggestion.</dd> |
| <dt><code>android:searchSuggestIntentData</code></dt> |
| <dd><em>String</em>. The default Intent data to be used when a user |
| clicks on a search suggestion. |
| If not overridden by the selected suggestion (via the {@link |
| android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value will be |
| placed in the data field of the {@link android.content.Intent} when the user clicks |
| a suggestion.</dd> |
| <dt><code>android:searchSuggestThreshold</code></dt> |
| <dd><em>Integer</em>. The minimum number of characters needed to |
| trigger a suggestion look-up. Only guarantees that a source will not be |
| queried for anything shorter than the threshold. The default value is 0.</dd> |
| </dl> |
| |
| <p>For more information about the above attributes for search suggestions, see the guides for |
| <a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a> and |
| <a href="adding-custom-suggestions.html">Adding Custom Suggestions</a>.</p> |
| |
| <p>Beyond providing search suggestions while using your application's search dialog, you |
| can also configure your search suggestions to be made available to Quick Search Box, |
| which will allow users so receive search suggestions from your application content from outside |
| your application. When providing search suggestions to Quick Search Box, you'll need some of the |
| following {@code <searchable>} attributes:</p><br/> |
| |
| <dl class="atn-list"> |
| <dt><code>android:includeInGlobalSearch</code></dt> |
| <dd><em>Boolean</em>. <strong>Required to provide search suggestions in |
| Quick Search Box</strong>. "true" if you want your suggestions to be |
| included in the globally accessible Quick Search Box. Note that the user must |
| still enable your application as a searchable item in the system search settings in order |
| for your suggestions to appear in Quick Search Box.</dd> |
| <dt><code>android:searchSettingsDescription</code></dt> |
| <dd><em>String</em>. Provides a brief description of the search suggestions that you provide |
| to Quick Search Box, which will be displayed in the searchable items entry for your application. |
| Your description should concisely describe the content that is searchable. For example, "Artists, |
| albums, and tracks" for a music application, or "Saved notes" for a notepad application.</dd> |
| <dt><code>android:queryAfterZeroResults</code></dt> |
| <dd><em>Boolean</em>. "true" if you want your content provider to be invoked for |
| supersets of queries that have returned zero results for in the past. For example, if a |
| source returned zero results for "bo", it would be ignored for "bob". If "false", |
| this source will only be ignored for a single session; the next time the search dialog |
| is invoked, all sources will be queried. The default value is false.</dd> |
| </dl> |
| |
| <p>To enable voice search for your search dialog, you'll need some of the |
| following {@code <searchable>} attributes:</p><br/> |
| |
| <dl class="atn-list"> |
| <dt><code>android:voiceSearchMode</code></dt> |
| <dd><em>Keyword</em>. <strong>Required to provide voice search capabilities</strong>. |
| Enables voice search for the search dialog, with a specific mode for voice search. |
| (Voice search may not be provided by the device, in which case these flags will |
| have no effect.) The following mode values are accepted: |
| <table> |
| <tr><th>Value</th><th>Description</th></tr> |
| <tr> |
| <td><code>"showVoiceSearchButton"</code></td> |
| <td>Display a voice search button. This only |
| takes effect if voice search is available on the device. If set, then either |
| {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be set |
| (separated by the pipe | character).</td> |
| </tr> |
| <tr> |
| <td><code>"launchWebSearch"</code></td> |
| <td>The voice search button will take the user directly |
| to a built-in voice web search activity. Most applications will not use this flag, as |
| it will take the user away from the Activity in which search was invoked.</td> |
| </tr> |
| <tr> |
| <td><code>"launchRecognizer"</code></td> |
| <td>The voice search button will take |
| the user directly to a built-in voice recording activity. This Activity |
| will prompt the user to speak, transcribe the spoken text, and forward the resulting |
| query text to the searchable Activity, just as if the user had typed it into the |
| search UI and clicked the search button.</td> |
| </tr> |
| </table> |
| </dd> |
| <dt><code>android:voiceLanguageModel</code></dt> |
| <dd><em>Keyword</em>. The language model that |
| should be used by the voice recognition system. The following values are accepted: |
| <table> |
| <tr><th>Value</th><th>Description</th></tr> |
| <tr> |
| <td><code>"free_form"</code></td> |
| <td>Use a language model based on free-form speech recognition. This is the |
| default.</td> |
| </tr> |
| <tr> |
| <td><code>"web_search"</code></td> |
| <td>Use a language model based on web search terms.</td> |
| </tr> |
| </table> |
| <p>Also see |
| {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL} for more |
| information.</p></dd> |
| <dt><code>android:voicePromptText</code></dt> |
| <dd><em>String</em>. An additional message to display in the voice input dialog.</dd> |
| <dt><code>android:voiceLanguage</code></dt> |
| <dd><em>String</em>. The spoken language to be expected, expressed as the string value of |
| a constants in {@link java.util.Locale} (for example, {@code "de"} for German or {@code "fr"} for |
| French). This is only needed if it is different from the current value of {@link |
| java.util.Locale#getDefault() Locale.getDefault()}.</dd> |
| <dt><code>android:voiceMaxResults</code></dt> |
| <dd><em>Integer</em>. Forces the maximum number of results to return, |
| including the "best" result which will always be provided as the {@link |
| android.content.Intent#ACTION_SEARCH} Intent's primary |
| query. Must be 1 or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS} to |
| get the results from the Intent. |
| If not provided, the recognizer will choose how many results to return.</dd> |
| </dl> |
| </dd> <!-- end searchable element --> |
| |
| |
| <dt id="actionkey-element"><code><actionkey></code></dt> |
| <dd>Defines a shortcut key for a search action, in order to provide special behaviors at the touch |
| of a button, based on the current query or focused suggestion. For example, the Contacts |
| application enables the device call key for suggestions. So, when |
| the user focuses on a search suggestion using the directional controls and then presses the call |
| key, the application will immediately initiate a phone call to the suggested contact. |
| <p>Not all action keys are available on every device, and not |
| all keys are allowed to be overriden in this way. For example, the "Home" key cannot be used and |
| must always return to the home screen. Also be sure not to define an action |
| key for a key that's needed for typing a search query. This essentially limits the |
| available and reasonable action keys to the call button and menu button. Also note that action |
| keys are not generally discoverable, so you should not provide them as a core user feature.</p> |
| <p class="caps">attributes:</p> |
| <dl class="atn-list"> |
| <dt><code>android:keycode</code></dt> |
| <dd><em>String</em>. <strong>Required</strong>. A key code from {@link |
| android.view.KeyEvent} that represents the action key |
| you wish to respond to (for example {@code "KEYCODE_CALL"}). This will be added to the |
| {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your |
| searchable Activity. To examine the key code, use |
| {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. |
| In addition to the key code, you must also provide one or more of |
| the action specifier attributes below. Not all action keys |
| are actually supported using this mechanism, as many of them are used for typing, |
| navigation, or system functions. Note that although each of the action message elements are |
| optional, at least one must be present for the action key to have any effect.</dd> |
| <dt><code>android:queryActionMsg</code></dt> |
| <dd><em>String</em>. An action message to be sent if the action key is pressed while the |
| user is simply entering query text. This will be added to the |
| {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is |
| passed to your searchable Activity. To examine the string, use |
| {@link android.content.Intent#getStringExtra |
| getStringExtra(SearchManager.ACTION_MSG)}.</dd> |
| <dt><code>android:suggestActionMsg</code></dt> |
| <dd><em>String</em>. An action message to be sent if the action key is pressed while a |
| suggestion is focused. This will be added to the |
| Intent that is passed to your searchable Activity (using the action you've defined for |
| the suggestion). To examine the string, |
| use {@link android.content.Intent#getStringExtra |
| getStringExtra(SearchManager.ACTION_MSG)}. Note that this should only be used if all your |
| suggestions support this action key. If not all suggestions can handle the same action key, then |
| you must instead use the following {@code android:suggestActionMsgColumn} attribute.</dd> |
| <dt><code>android:suggestActionMsgColumn</code></dt> |
| <dd><em>String</em>. The name of the column in your content provider that defines the |
| action message for this action key, which is to be sent if the action key is pressed while a |
| suggestion is focused. This attribute lets you control the |
| action key on a suggestion-by-suggestion basis, because, instead of using the {@code |
| android:suggestActionMsg} attribute to define the action message for all suggestions, each entry in |
| your content provider provides its own action message. First, you must define a column in your |
| content provider for each suggestion to provide an action message, then provide the name of that |
| column in this attribute. The search manager will look at your suggestion cursor, |
| using the string provided here in order to select your action message column, and |
| then select the action message string from the cursor. That string will be added to the |
| Intent that is passed to your searchable Activity (using the action you've defined for |
| suggestions). To examine the string, use {@link |
| android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data |
| does not exist for the selected suggestion, the action key will be ignored.</dd> |
| </dl> |
| </dd><!-- end action key --> |
| </dl> |
| </dd><!-- end elements --> |
| |
| |
| <dt>example:</dt> |
| <dd>XML file saved at <code>res/xml/searchable.xml</code>: |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <searchable xmlns:android="http://schemas.android.com/apk/res/android" |
| android:label="@string/search_label" |
| android:hint="@string/search_hint" |
| android:searchSuggestAuthority="dictionary" |
| android:searchSuggestIntentAction="android.intent.action.VIEW" |
| android:includeInGlobalSearch="true" |
| android:searchSettingsDescription="@string/settings_description" > |
| </searchable> |
| </pre> |
| |
| </dd> <!-- end example --> |
| |
| |
| </dl> |
| |
| |
| |
| |