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.
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.
Note: The code fragments in this document are related to a sample app called Searchable Dictionary. The app is available for Android 1.6 and later platforms.
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
AndroidManifest.xml:
1) In your <activity>, an intent filter, and a reference
to a searchable.xml file (described below):
<intent-filter>
<action android:name="android.intent.action.SEARCH" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<meta-data android:name="android.app.searchable"
android:resource="@xml/searchable" />
2) A content provider that can provide search suggestions according to the URIs and column formats specified by the Search Suggestions section of the SearchManager docs:
<!-- Provides search suggestions for words and their definitions. -->
<provider android:name="DictionaryProvider"
android:authorities="dictionary"
android:syncable="false" />
In the searchable.xml 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 searchable.xml of an Android app
that provides search suggestions within its own activities:
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
android:label="@string/search_label"
android:searchSuggestAuthority="dictionary"
android:searchSuggestIntentAction="android.intent.action.VIEW">
</searchable>
Note that the android:searchSuggestAuthority attribute refers to
the authority of the content provider we declared in
AndroidManifest.xml.
For more details on this, see the Searchability Metadata section of the of the SearchManager docs.
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 check it out.
In Android 1.6, we added a new attribute to the metadata for searchables:
android:includeInGlobalSearch. By specifying this as
"true" in your searchable.xml, 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).
You should also specify a string value for
android:searchSettingsDescription, which describes to users what
sorts of suggestions your app provides in the system settings for search.
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
android:label="@string/search_label"
android:searchSettingsDescription="@string/settings_description"
android:includeInGlobalSearch="true"
android:searchSuggestAuthority="dictionary"
android:searchSuggestIntentAction="android.intent.action.VIEW">
</searchable>
These new attributes are supported only in Android 1.6 and later.
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 not 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" > "Searchable items" in settings).
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.
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.
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.
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 within the SearchManager docs.