docs/html/resources/articles/qsb.jd

page.title=Quick Search Box
@jd:body


<div id="qv-wrapper">
<div id="qv">

  <h2>See also</h2>
  <ol>
    <li><a href="{@docRoot}guide/topics/search/index.html">Search</a></li>
    <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable Dictionary
sample</a></li>
  </ol>

</div>
</div>

<div class="figure" style="width:233px">
<img src="images/qsb_002.png" alt="" height="350" />
</div>

<p>Starting with Android 1.6, the platform includes support for Quick Search
Box (QSB), a powerful, system-wide search framework. Quick Search Box makes it
possible for users to quickly and easily find what they're looking for, both on
their devices and on the web. It suggests content on your device as you type,
like apps, contacts, browser history, and music. It also offers results from the
web search suggestions, local business listings, and other info from
Google, such as stock quotes, weather, and flight status. All of this is
available right from the home screen, by tapping on Quick Search Box.</p>

<p>What
we're most excited about with this new feature is the ability for you,
the developers, to leverage the QSB framework to provide quicker and
easier access to the content inside your apps. Your apps can provide
search suggestions that will surface to users in QSB alongside other
search results and suggestions. This makes it possible for users to
access your application's content from outside your application—for
example, from the home screen.</p>

<p class="note"><strong>Note:</strong> The code fragments in this document are
related to a sample app called <a
href="{@docRoot}resources/samples/SearchableDictionary/index.html"
title="Searchable Dictionary">Searchable Dictionary</a>. The app is
available for Android 1.6 and later platforms.</p>

<h3>The story before now: searching within your app</h3>

<p>Platform releases versions previous to Android 1.6 already provided a mechanism
that let you expose search and search suggestions in your app, as described in
the docs for {@link android.app.SearchManager}. That mechanism has not changed
and requires the following two things in your
<code>AndroidManifest.xml</code>:</p>

<p>1) In your <code>&lt;activity&gt;</code>, an intent filter, and a reference 
to a <code>searchable.xml</code> file (described below):</p>

<pre class="prettyprint">&lt;intent-filter&gt;
    &lt;action android:name="android.intent.action.SEARCH" /&gt;
    &lt;category android:name="android.intent.category.DEFAULT" /&gt;
&lt;/intent-filter&gt;
            
&lt;meta-data android:name="android.app.searchable"
       android:resource="@xml/searchable" /&gt;</pre>

<p>2) A content provider that can provide search suggestions according to the
URIs and column formats specified by the 
<a href="{@docRoot}reference/android/app/SearchManager.html#Suggestions">Search Suggestions</a>
section of the SearchManager docs:</p>

<pre class="prettyprint">&lt;!-- Provides search suggestions for words and their definitions. --&gt;
&lt;provider android:name="DictionaryProvider"
       android:authorities="dictionary"
       android:syncable="false" /&gt;</pre>

<p>In the <code>searchable.xml</code> file, you specify a few things about how
you want the search system to present search for your app, including the
authority of the content provider that provides suggestions for the user as they
type. Here's an example of the <code>searchable.xml</code> of an Android app
that provides search suggestions within its own activities:</p>

<pre class="prettyprint">&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/search_label"
        android:searchSuggestAuthority="dictionary"
        android:searchSuggestIntentAction="android.intent.action.VIEW"&gt;
&lt;/searchable&gt;</pre>

<p>Note that the <code>android:searchSuggestAuthority</code> attribute refers to
the authority of the content provider we declared in
<code>AndroidManifest.xml</code>.</p>

<p>For more details on this, see the 
<a href="{@docRoot}reference/android/app/SearchManager.html#SearchabilityMetadata">Searchability Metadata 
section</a> of the of the SearchManager docs.</p>

<h3>Including your app in Quick Search Box</h3>

<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Searchable Dictionary Sample App</h2>
<p>Quick Search Box provides a really cool way to make it easier and faster for
users to access your app's content. To help you get your app started with it,
we've created a sample app that simply provides access to a small dictionary of
words in QSB. The app is called Searchable Dictionary, and we encourage you to
<a href="{@docRoot}resources/samples/SearchableDictionary/index.html">check it
out</a>.</p>
</div>
</div>

<p>In Android 1.6, we added a new attribute to the metadata for searchables:
<code>android:includeInGlobalSearch</code>. By specifying this as
<code>"true"</code> in your <code>searchable.xml</code>, you allow QSB to pick
up your search suggestion content provider and include its suggestions along
with the rest (if the user enables your suggestions from the system search
settings).</p>

<p>You should also specify a string value for 
<code>android:searchSettingsDescription</code>, which describes to users what
sorts of suggestions your app provides in the system settings for search.</p>

<pre class="prettyprint">&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android"
       android:label="@string/search_label"
       <span style="background: rgb(255, 255, 0) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;">android:searchSettingsDescription="@string/settings_description"</span>
       <span style="background: rgb(255, 255, 0) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous;">android:includeInGlobalSearch="true"</span>
       android:searchSuggestAuthority="dictionary"
       android:searchSuggestIntentAction="android.intent.action.VIEW"&gt;
&lt;/searchable&gt;</pre>

<p>These new attributes are supported only in Android 1.6 and later.</p>

<h3>What to expect</h3>

<p>The
first and most important thing to note is that when a user installs an
app with a suggestion provider that participates in QSB, this new app
will <em>not</em> be enabled for QSB by default. The user can choose
to enable particular suggestion sources from the system settings for
search (by going to "Search" &gt; "Searchable items" in settings).</p>

<p>You
should consider how to handle this in your app. Perhaps show a notice
that instructs the user to visit system settings and enable your app's
suggestions.</p>

<p>Once the user enables your searchable item, the
app's suggestions will have a chance to show up in QSB, most likely
under the "more results" section to begin with. As your app's
suggestions are chosen more frequently, they can move up in the list.</p>

<img src="images/qsb.png" style="width: 233px; height: 349.5px;">  
<img id="k0vw" src="images/qsb_003.png" style="width: 233px; height: 349.5px;">

<h3>Shortcuts</h3>

<p>One
of our objectives with QSB is to make it faster for users to access the
things they access most often. One way we've done this is by
'shortcutting' some of the previously chosen search suggestions, so
they will be shown immediately as the user starts typing, instead of
waiting to query the content providers. Suggestions from your app may
be chosen as shortcuts when the user clicks on them.</p>

<p>For dynamic suggestions that may wish to change their content (or become invalid)
in the future, you can provide a 'shortcut id'. This tells QSB to query
your suggestion provider for up-to-date content for a suggestion after
it has been displayed. For more details on how to manage shortcuts, see
the Shortcuts section 
<a href="{@docRoot}reference/android/app/SearchManager.html#ExposingSearchSuggestionsToQuickSearchBox">within the SearchManager docs</a>.</p>