Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 1 | page.title=Quick Search Box |
Scott Main | 796ce77 | 2011-02-16 10:04:45 -0800 | [diff] [blame] | 2 | parent.title=Articles |
| 3 | parent.link=../browser.html?tag=article |
Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 4 | @jd:body |
| 5 | |
Scott Main | a225e3b | 2010-05-11 17:43:43 -0700 | [diff] [blame] | 6 | |
| 7 | <div id="qv-wrapper"> |
| 8 | <div id="qv"> |
| 9 | |
| 10 | <h2>See also</h2> |
| 11 | <ol> |
| 12 | <li><a href="{@docRoot}guide/topics/search/index.html">Search</a></li> |
| 13 | <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable Dictionary |
| 14 | sample</a></li> |
| 15 | </ol> |
| 16 | |
| 17 | </div> |
| 18 | </div> |
| 19 | |
| 20 | <div class="figure" style="width:233px"> |
| 21 | <img src="images/qsb_002.png" alt="" height="350" /> |
| 22 | </div> |
Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 23 | |
| 24 | <p>Starting with Android 1.6, the platform includes support for Quick Search |
| 25 | Box (QSB), a powerful, system-wide search framework. Quick Search Box makes it |
| 26 | possible for users to quickly and easily find what they're looking for, both on |
| 27 | their devices and on the web. It suggests content on your device as you type, |
| 28 | like apps, contacts, browser history, and music. It also offers results from the |
| 29 | web search suggestions, local business listings, and other info from |
| 30 | Google, such as stock quotes, weather, and flight status. All of this is |
| 31 | available right from the home screen, by tapping on Quick Search Box.</p> |
| 32 | |
| 33 | <p>What |
| 34 | we're most excited about with this new feature is the ability for you, |
| 35 | the developers, to leverage the QSB framework to provide quicker and |
| 36 | easier access to the content inside your apps. Your apps can provide |
| 37 | search suggestions that will surface to users in QSB alongside other |
| 38 | search results and suggestions. This makes it possible for users to |
| 39 | access your application's content from outside your application—for |
| 40 | example, from the home screen.</p> |
| 41 | |
| 42 | <p class="note"><strong>Note:</strong> The code fragments in this document are |
| 43 | related to a sample app called <a |
Scott Main | 90b04c5 | 2009-12-21 11:53:00 -0800 | [diff] [blame] | 44 | href="{@docRoot}resources/samples/SearchableDictionary/index.html" |
| 45 | title="Searchable Dictionary">Searchable Dictionary</a>. The app is |
Dirk Dougherty | 22558d0 | 2009-12-10 16:25:06 -0800 | [diff] [blame] | 46 | available for Android 1.6 and later platforms.</p> |
| 47 | |
| 48 | <h3>The story before now: searching within your app</h3> |
| 49 | |
| 50 | <p>Platform releases versions previous to Android 1.6 already provided a mechanism |
| 51 | that let you expose search and search suggestions in your app, as described in |
| 52 | the docs for {@link android.app.SearchManager}. That mechanism has not changed |
| 53 | and requires the following two things in your |
| 54 | <code>AndroidManifest.xml</code>:</p> |
| 55 | |
| 56 | <p>1) In your <code><activity></code>, an intent filter, and a reference |
| 57 | to a <code>searchable.xml</code> file (described below):</p> |
| 58 | |
| 59 | <pre class="prettyprint"><intent-filter> |
| 60 | <action android:name="android.intent.action.SEARCH" /> |
| 61 | <category android:name="android.intent.category.DEFAULT" /> |
| 62 | </intent-filter> |
| 63 | |
| 64 | <meta-data android:name="android.app.searchable" |
| 65 | android:resource="@xml/searchable" /></pre> |
| 66 | |
| 67 | <p>2) A content provider that can provide search suggestions according to the |
| 68 | URIs and column formats specified by the |
| 69 | <a href="{@docRoot}reference/android/app/SearchManager.html#Suggestions">Search Suggestions</a> |
| 70 | section of the SearchManager docs:</p> |
| 71 | |
| 72 | <pre class="prettyprint"><!-- Provides search suggestions for words and their definitions. --> |
| 73 | <provider android:name="DictionaryProvider" |
| 74 | android:authorities="dictionary" |
| 75 | android:syncable="false" /></pre> |
| 76 | |
| 77 | <p>In the <code>searchable.xml</code> file, you specify a few things about how |
| 78 | you want the search system to present search for your app, including the |
| 79 | authority of the content provider that provides suggestions for the user as they |
| 80 | type. Here's an example of the <code>searchable.xml</code> of an Android app |
| 81 | that provides search suggestions within its own activities:</p> |
| 82 | |
| 83 | <pre class="prettyprint"><searchable xmlns:android="http://schemas.android.com/apk/res/android" |
| 84 | android:label="@string/search_label" |
| 85 | android:searchSuggestAuthority="dictionary" |
| 86 | android:searchSuggestIntentAction="android.intent.action.VIEW"> |
| 87 | </searchable></pre> |
| 88 | |
| 89 | <p>Note that the <code>android:searchSuggestAuthority</code> attribute refers to |
| 90 | the authority of the content provider we declared in |
| 91 | <code>AndroidManifest.xml</code>.</p> |
| 92 | |
| 93 | <p>For more details on this, see the |
| 94 | <a href="{@docRoot}reference/android/app/SearchManager.html#SearchabilityMetadata">Searchability Metadata |
| 95 | section</a> of the of the SearchManager docs.</p> |
| 96 | |
| 97 | <h3>Including your app in Quick Search Box</h3> |
| 98 | |
| 99 | <div class="sidebox-wrapper"> |
| 100 | <div class="sidebox"> |
| 101 | <h2>Searchable Dictionary Sample App</h2> |
| 102 | <p>Quick Search Box provides a really cool way to make it easier and faster for |
| 103 | users to access your app's content. To help you get your app started with it, |
| 104 | we've created a sample app that simply provides access to a small dictionary of |
| 105 | words in QSB. The app is called Searchable Dictionary, and we encourage you to |
| 106 | <a href="{@docRoot}resources/samples/SearchableDictionary/index.html">check it |
| 107 | out</a>.</p> |
| 108 | </div> |
| 109 | </div> |
| 110 | |
| 111 | <p>In Android 1.6, we added a new attribute to the metadata for searchables: |
| 112 | <code>android:includeInGlobalSearch</code>. By specifying this as |
| 113 | <code>"true"</code> in your <code>searchable.xml</code>, you allow QSB to pick |
| 114 | up your search suggestion content provider and include its suggestions along |
| 115 | with the rest (if the user enables your suggestions from the system search |
| 116 | settings).</p> |
| 117 | |
| 118 | <p>You should also specify a string value for |
| 119 | <code>android:searchSettingsDescription</code>, which describes to users what |
| 120 | sorts of suggestions your app provides in the system settings for search.</p> |
| 121 | |
| 122 | <pre class="prettyprint"><searchable xmlns:android="http://schemas.android.com/apk/res/android" |
| 123 | android:label="@string/search_label" |
| 124 | <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> |
| 125 | <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> |
| 126 | android:searchSuggestAuthority="dictionary" |
| 127 | android:searchSuggestIntentAction="android.intent.action.VIEW"> |
| 128 | </searchable></pre> |
| 129 | |
| 130 | <p>These new attributes are supported only in Android 1.6 and later.</p> |
| 131 | |
| 132 | <h3>What to expect</h3> |
| 133 | |
| 134 | <p>The |
| 135 | first and most important thing to note is that when a user installs an |
| 136 | app with a suggestion provider that participates in QSB, this new app |
| 137 | will <em>not</em> be enabled for QSB by default. The user can choose |
| 138 | to enable particular suggestion sources from the system settings for |
| 139 | search (by going to "Search" > "Searchable items" in settings).</p> |
| 140 | |
| 141 | <p>You |
| 142 | should consider how to handle this in your app. Perhaps show a notice |
| 143 | that instructs the user to visit system settings and enable your app's |
| 144 | suggestions.</p> |
| 145 | |
| 146 | <p>Once the user enables your searchable item, the |
| 147 | app's suggestions will have a chance to show up in QSB, most likely |
| 148 | under the "more results" section to begin with. As your app's |
| 149 | suggestions are chosen more frequently, they can move up in the list.</p> |
| 150 | |
| 151 | <img src="images/qsb.png" style="width: 233px; height: 349.5px;"> |
| 152 | <img id="k0vw" src="images/qsb_003.png" style="width: 233px; height: 349.5px;"> |
| 153 | |
| 154 | <h3>Shortcuts</h3> |
| 155 | |
| 156 | <p>One |
| 157 | of our objectives with QSB is to make it faster for users to access the |
| 158 | things they access most often. One way we've done this is by |
| 159 | 'shortcutting' some of the previously chosen search suggestions, so |
| 160 | they will be shown immediately as the user starts typing, instead of |
| 161 | waiting to query the content providers. Suggestions from your app may |
| 162 | be chosen as shortcuts when the user clicks on them.</p> |
| 163 | |
| 164 | <p>For dynamic suggestions that may wish to change their content (or become invalid) |
| 165 | in the future, you can provide a 'shortcut id'. This tells QSB to query |
| 166 | your suggestion provider for up-to-date content for a suggestion after |
| 167 | it has been displayed. For more details on how to manage shortcuts, see |
| 168 | the Shortcuts section |
| 169 | <a href="{@docRoot}reference/android/app/SearchManager.html#ExposingSearchSuggestionsToQuickSearchBox">within the SearchManager docs</a>.</p> |