topics/search/searchable-config.jd

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">Creating a Search Interface</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 implement search with assistance from the Android system (to deliver search queries
to an activity and provide search suggestions), your application must provide a search configuration
in the form of an XML file.</p>

<p>This page describes the search configuration file in terms of its syntax and usage. For more
information about how to implement search features for your application, begin with the developer
guide about <a href="search-dialog.html">Creating a Search Interface</a>.</p>

<dl class="xml">

<dt>file location:</dt>
<dd><code>res/xml/<em>filename</em>.xml</code><br/>
Android uses the filename as the resource ID.</dd>

<dt>syntax:</dt>
<dd>
<pre class="stx">
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;<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>"
    &gt;
    &lt;<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>" &gt;
&lt;/searchable&gt;
</pre>
</dd>

<dt>elements:</dt>
<dd>
<dl class="tag-list">
  <dt id="searchable-element"><code>&lt;searchable&gt;</code></dt>
  <dd>Defines all search configurations used by the Android system to provide assisted search.
    <p class="caps">attributes:</p>
      <dl class="atn-list">
      <dt><code>android:label</code></dt>
      <dd><em>String resource</em>. (Required.) The name of your application.
It should 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 &lt;activity&gt;}</a> or
<a href="{@docRoot}guide/topics/manifest/application-element.html#label">{@code
&lt;application&gt;}</a> manifest element. This label is only visible to the user when you set
<code>android:includeInGlobalSearch</code> to "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>. (Recommended.) The text to display in the search text field when
no text has been entered. It provides a hint to the user about what
content is searchable. For consistency with other Android applications, you should format the
string for {@code android:hint} as "Search <em>&lt;content-or-product&gt;</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.
Currently available modes define how the query text should be rewritten when a custom suggestion
receives focus. The following mode values are accepted:
        <table>
          <tr><th>Value</th><th>Description</th></tr>
          <tr>
            <td><code>"queryRewriteFromText"</code></td>
            <td>Use the value from the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}
column to rewrite the query text.</td>
          </tr>
          <tr>
            <td><code>"queryRewriteFromData"</code></td>
            <td>Use the value from the
            {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column to rewrite the
query text. 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 URI's.</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 search. By
default, the button shows a search icon (a magnifying glass), which is ideal for
internationalization, so you should not use this attribute to change the button unless the
behavior is something other than a search (such as a URL request in a web browser).</dd>

      <dt><code>android:inputType</code></dt>
      <dd><em>Keyword</em>. Defines the type of input method (such as the type of soft keyboard)
to use. For most searches, in which free-form text is expected, you don't
need this attribute. 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, you don't need this attribute. The
default IME is "actionSearch" (provides the "search" button instead of a carriage
return in the soft keyboard). See {@link android.R.attr#imeOptions} for a list of suitable values
for this attribute.
      </dd>
    </dl>


    <h4>Search suggestion attributes</h4>

    <p>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
    {@code &lt;searchable>} attributes:</p><br/>

      <dl class="atn-list">
      <dt><code>android:searchSuggestAuthority</code></dt>
        <dd><em>String</em>. (Required to provide search suggestions.)
        This value must match the authority string provided in the {@code android:authorities}
attribute of the Android manifest {@code &lt;provider>} element.</dd>

      <dt><code>android:searchSuggestPath</code></dt>
        <dd><em>String</em>. This path is 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 (such as for different data types) and you need
        a way to disambiguate the suggestions queries when you receive them.</dd>

      <dt><code>android:searchSuggestSelection</code></dt>
        <dd><em>String</em>. This value is passed into your
        query function as the {@code selection} 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, {@code "query=?"}). However, you
can also use any non-null value to 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 custom search suggestion (such as {@code "android.intent.action.VIEW"}).
        If this is not overridden by the selected suggestion (via the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value is 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 custom search suggestion.
        If not overridden by the selected suggestion (via the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is
        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 the system will not query your
        content provider 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>


    <h4>Quick Search Box attributes</h4>

    <p>To make your custom search suggestions available to Quick Search Box, you need some of the
    following {@code &lt;searchable>} attributes:</p><br/>

      <dl class="atn-list">
      <dt><code>android:includeInGlobalSearch</code></dt>
        <dd><em>Boolean</em>. (Required to provide search suggestions in
        Quick Search Box.) Set to "true" if you want your suggestions to be
        included in the globally accessible Quick Search Box. The user must
        still enable your application as a searchable item in the system search settings before
        your suggestions will 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 is 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>. Set to "true" if you want your content provider to be invoked for
        supersets of queries that have returned zero results in the past. For example, if
your content provider returned zero results for "bo", it should be requiried for "bob". If set to
"false", supersets are ignored for a single session ("bob" does not invoke a requery). This lasts
only for the life of the search dialog or the life of the activity when using the search widget
(when the search dialog or activity is reopened, "bo" queries your
content provider again). The default value is false.</dd>
      </dl>


    <h4>Voice search attributes</h4>

    <p>To enable voice search, you'll need some of the
    following {@code &lt;searchable>} attributes:</p><br/>

      <dl class="atn-list">
        <dt><code>android:voiceSearchMode</code></dt>
        <dd><em>Keyword</em>. (Required to provide voice search capabilities.)
          Enables voice search, with a specific mode for voice search.
          (Voice search may not be provided by the device, in which case these flags
          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, 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 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.</td>
            </tr>
            <tr>
              <td><code>"launchRecognizer"</code></td>
              <td>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.</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 free-form speech recognition for dictating queries. This is primarily
optimized for English. This is the default.</td>
            </tr>
            <tr>
              <td><code>"web_search"</code></td>
              <td>Use web-search-term recognition for shorter, search-like phrases. This is
available in more languages than "free_form".</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} (such as {@code "de"} for German or {@code "fr"} for
French). This is needed only 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 is always 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 chooses how many results to return.</dd>
      </dl>
  </dd> <!-- end searchable element -->


  <dt id="actionkey-element"><code>&lt;actionkey&gt;</code></dt>
  <dd>Defines a device key and behavior for a search action. A search action provides a
special behavior at the touch of a button on the device, based on the current query or focused
suggestion. For example, the Contacts application provides a search action to initiate a phone call
to the currenly focused contact suggestion at the press of the CALL button.
    <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>You must define the <code>android:keycode</code> to define the key and at least one of the
other three attributes in order to define the search action.</p>
      <p class="caps">attributes:</p>
      <dl class="atn-list">
      <dt><code>android:keycode</code></dt>
        <dd><em>String</em>. (Required.) A key code from {@link
android.view.KeyEvent} that represents the action key
        you wish to respond to (for example {@code "KEYCODE_CALL"}). This is 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)}. Not all
keys are supported for a search action, as many of them are used for typing, navigation, or system
functions.</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 entering query text. This is added to the
        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that the system
        passes 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 in focus. This is added to the
        intent that that the system passes 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)}. 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 user presses the action key while a
        suggestion is in focus. 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.
        <p>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 system 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 system passes 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 is 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>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;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" >
&lt;/searchable>
</pre>

</dd> <!-- end example -->


</dl>