Searchable Configuration

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 Search.

file location:

res/xml/filename.xml
The filename will be used as the resource ID.

syntax:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" >
</searchable>

elements:

<searchable>

Defines all search configurations used with the search dialog.

attributes:

android:label

String resource. Required. This is the name of your application. It should normally be the same as the name applied to the android:label attribute of your <activity> or <application> manifest element. This is only visible to the user when you set android:includeInGlobalSearch "true", in which case, this label is used to identify your application as a searchable item in the system's search settings.

android:hint

String resource. 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 android:hint as "Search <content-or-product>". For example, "Search songs and artists" or "Search YouTube".

android:searchMode

Keyword. 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:

Value	Description
"queryRewriteFromData"	If set, this causes the suggestion column SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query rewriting. This should only be used when the values in SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing - typically, HTTP/HTTPS Uri's.
"queryRewriteFromText"	If set, this causes the suggestion column 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 SUGGEST_COLUMN_INTENT_DATA values are not suitable for user inspection and editing.

For more information, see the discussion about rewriting the query text in Adding Custom Suggestions.

android:searchButtonText

String resource. 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.

android:inputType

Keyword. 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 inputType for a list of suitable values for this attribute.

android:imeOptions

Keyword. 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 imeOptions for a list of suitable values for this attribute.

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 <searchable> attributes:

android:searchSuggestAuthority

String. Required to provide search suggestions. This value must match the authority string provided in the android:authorities attribute of the <provider> element.

android:searchSuggestPath

String. This path will be used as a portion of the suggestions query 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.

android:searchSuggestSelection

String. This value will be passed into your query function as the 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 selectionArgs parameter (and then ignore the selection parameter).

android:searchSuggestIntentAction

String. The default Intent action to be used when a user clicks on a search suggestion (such as "android.intent.action.VIEW"). If not overridden by the selected suggestion (via the SUGGEST_COLUMN_INTENT_ACTION column), this value will be placed in the action field of the Intent when the user clicks a suggestion.

android:searchSuggestIntentData

String. The default Intent data to be used when a user clicks on a search suggestion. If not overridden by the selected suggestion (via the SUGGEST_COLUMN_INTENT_DATA column), this value will be placed in the data field of the Intent when the user clicks a suggestion.

android:searchSuggestThreshold

Integer. 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.

For more information about the above attributes for search suggestions, see the guides for Adding Recent Query Suggestions and Adding Custom Suggestions.

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 <searchable> attributes:

android:includeInGlobalSearch

Boolean. Required to provide search suggestions in Quick Search Box. "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.

android:searchSettingsDescription

String. 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.

android:queryAfterZeroResults

Boolean. "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.

To enable voice search for your search dialog, you'll need some of the following <searchable> attributes:

android:voiceSearchMode

Keyword. Required to provide voice search capabilities. 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:

Value	Description
"showVoiceSearchButton"	Display a voice search button. This only takes effect if voice search is available on the device. If set, then either "launchWebSearch" or "launchRecognizer" must also be set (separated by the pipe | character).
"launchWebSearch"	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.
"launchRecognizer"	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.

android:voiceLanguageModel

Keyword. The language model that should be used by the voice recognition system. The following values are accepted:

Value	Description
"free_form"	Use a language model based on free-form speech recognition. This is the default.
"web_search"	Use a language model based on web search terms.

Also see EXTRA_LANGUAGE_MODEL for more information.

android:voicePromptText

String. An additional message to display in the voice input dialog.

android:voiceLanguage

String. The spoken language to be expected, expressed as the string value of a constants in Locale (for example, "de" for German or "fr" for French). This is only needed if it is different from the current value of Locale.getDefault().

android:voiceMaxResults

Integer. Forces the maximum number of results to return, including the "best" result which will always be provided as the ACTION_SEARCH Intent's primary query. Must be 1 or greater. Use EXTRA_RESULTS to get the results from the Intent. If not provided, the recognizer will choose how many results to return.

<actionkey>

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.

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.

attributes:

android:keycode

String. Required. A key code from KeyEvent that represents the action key you wish to respond to (for example "KEYCODE_CALL"). This will be added to the ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the key code, use 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.

android:queryActionMsg

String. 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 ACTION_SEARCH Intent that is passed to your searchable Activity. To examine the string, use getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

String. 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 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 android:suggestActionMsgColumn attribute.

android:suggestActionMsgColumn

String. 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 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 getStringExtra(SearchManager.ACTION_MSG). If the data does not exist for the selected suggestion, the action key will be ignored.

example:

XML file saved at res/xml/searchable.xml:

<?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>