diff options
Diffstat (limited to 'docs/html/resources/articles/qsb.jd')
| -rw-r--r-- | docs/html/resources/articles/qsb.jd | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/html/resources/articles/qsb.jd b/docs/html/resources/articles/qsb.jd new file mode 100644 index 0000000..1249f21 --- /dev/null +++ b/docs/html/resources/articles/qsb.jd @@ -0,0 +1,151 @@ +page.title=Quick Search Box +@jd:body + +<img src="images/qsb_002.png" style="float: right; margin-left: 2em; margin-bottom: 1em; width: 233px; height: 349.5px;"></p> + +<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="http://developer.android.com/guide/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><activity></code>, an intent filter, and a reference +to a <code>searchable.xml</code> file (described below):</p> + +<pre class="prettyprint"><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" /></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"><!-- Provides search suggestions for words and their definitions. --> +<provider android:name="DictionaryProvider" + android:authorities="dictionary" + android:syncable="false" /></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"><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></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"><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"> +</searchable></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" > "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> |