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">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">
&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 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 &lt;activity&gt;}</a> or
<a href="{@docRoot}guide/topics/manifest/application-element.html#label">{@code
&lt;application&gt;}</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>&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.
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 &lt;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 &lt;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 &lt;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 &lt;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>&lt;actionkey&gt;</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>
&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>