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 more information about how to implement search features for your application, see the developer guide about Search.
res/xml/filename.xml<?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>
<searchable>attributes:
android:labelandroid:label attribute of your <activity> or
<application> manifest element. This label is only visible to the user when you set
android:includeInGlobalSearch to "true", in which case, this label is used to identify
your application as a searchable item in the system's search settings.android:hintandroid:hint as "Search <content-or-product>". For example,
"Search songs and artists" or "Search YouTube".android:searchMode| Value | Description |
|---|---|
"queryRewriteFromText" | Use the value from the SUGGEST_COLUMN_TEXT_1
colum to rewrite the query text in the search dialog. |
"queryRewriteFromData" | Use the value from the
SUGGEST_COLUMN_INTENT_DATA column to rewrite the
query text in the search dialog. This should only be used when the values in
SUGGEST_COLUMN_INTENT_DATA are suitable for user
inspection and editing, typically HTTP URI's. |
For more information, see the discussion about rewriting the query text in Adding Custom Suggestions.
android:searchButtonTextandroid:inputTypeinputType for a list of suitable values for this
attribute.android:imeOptionsimeOptions 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 that configure communications with the content
provider. When providing search suggestions, you need some of the following
<searchable> attributes:
android:searchSuggestAuthorityandroid:authorities
attribute of the Android manifest <provider> element.android:searchSuggestPathUri, 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 (such as for different data types) and you need
a way to disambiguate the suggestions queries when you receive them.android:searchSuggestSelectionselection parameter. Typically this is a WHERE clause
for your database, and should contain a single question mark, which is a placeholder for the
actual query string that has been typed by the user (for example, "query=?"). However, you
can also use any non-null value to trigger the delivery of the query text via the selectionArgs parameter (and then ignore the selection parameter).android:searchSuggestIntentAction"android.intent.action.VIEW").
If this is not overridden by the selected suggestion (via the SUGGEST_COLUMN_INTENT_ACTION column), this value is placed in the action
field of the Intent when the user clicks a suggestion.android:searchSuggestIntentDataSUGGEST_COLUMN_INTENT_DATA column), this value is
placed in the data field of the Intent when the user clicks
a suggestion.android:searchSuggestThresholdFor more information about the above attributes for search suggestions, see the guides for Adding Recent Query Suggestions and Adding Custom Suggestions.
To make your custom search suggestions available to Quick Search Box, you need some of the
following <searchable> attributes:
android:includeInGlobalSearchandroid:searchSettingsDescriptionandroid:queryAfterZeroResultsTo enable voice search for your search dialog, you'll need some of the
following <searchable> attributes:
android:voiceSearchMode| Value | Description |
|---|---|
"showVoiceSearchButton" | Display a voice search button, 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 takes the user directly to a built-in voice web search activity. Most applications don't need this flag, as it takes the user away from the Activity in which search was invoked. |
"launchRecognizer" | The voice search button takes the user directly to a built-in voice recording activity. This Activity prompts the user to speak, transcribes the spoken text, and forwards the resulting query text to the searchable Activity, just as if the user typed it into the search UI and clicked the search button. |
android:voiceLanguageModel| Value | Description |
|---|---|
"free_form" | Use free-form speech recognition for dictating queries. This is primarily optimized for English. This is the default. |
"web_search" | Use web-search-term recognition for shorter, search-like phrases. This is available in more languages than "free_form". |
Also see
EXTRA_LANGUAGE_MODEL for more
information.
android:voicePromptTextandroid:voiceLanguageLocale (such as "de" for German or "fr" for
French). This is needed only if it is different from the current value of Locale.getDefault().android:voiceMaxResultsACTION_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 chooses how many results to return.<actionkey>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.
You must define the android:keycode to define the key and at least one of the
other three attributes in order to define the search action.
attributes:
android:keycodeKeyEvent that represents the action key
you wish to respond to (for example "KEYCODE_CALL"). This is added to the
ACTION_SEARCH Intent that is passed to your
searchable Activity. To examine the key code, use
getIntExtra(SearchManager.ACTION_KEY). Not all
keys are supported for a search action, as many of them are used for typing, navigation, or system
functions.android:queryActionMsgACTION_SEARCH Intent that the Search Manager
passes to your searchable Activity. To examine the string, use
getStringExtra(SearchManager.ACTION_MSG).android:suggestActionMsggetStringExtra(SearchManager.ACTION_MSG). 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:suggestActionMsgColumnandroid: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 looks at your suggestion cursor,
using the string provided here to select your action message column, and
then select the action message string from the Cursor. That string is added to the
Intent that the Search Manager passes 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 is ignored.
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>