Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am abdf0d53: docs: update search dev guide with SearcView widget

Browse Source 
* commit 'abdf0d533c292709e51cee2c1213d5e44baca963':
  docs: update search dev guide with SearcView widget
This commit is contained in:
Scott Main
2011-03-14 14:36:56 -07:00
committed by Android Git Automerger
parent 175121a513 abdf0d533c
commit 462012db70
9 changed files with 734 additions and 429 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
core/java/android/widget/SearchView.java
View File

@@ -54,18 +54,16 @@ import android.widget.TextView.OnEditorActionListener;
import java.util.WeakHashMap; import java.util.WeakHashMap;
/** /**
* Provides the user interface elements for the user to enter a search query and submit a * A widget that provides a user interface for the user to enter a search query and submit a
* request to a search provider. Shows a list of query suggestions or results, if * request to a search provider. Shows a list of query suggestions or results, if
* available and allows the user to pick a suggestion or result to launch into. * available, and allows the user to pick a suggestion or result to launch into.
* *
* <p> * <p>For more information, see the <a href="{@docRoot}guide/topics/search/index.html">Search</a>
* <b>XML attributes</b> * documentation.<p>
* <p>
* See {@link android.R.styleable#SearchView SearchView Attributes},
* {@link android.R.styleable#View View Attributes}
* *
* @attr ref android.R.styleable#SearchView_iconifiedByDefault * @attr ref android.R.styleable#SearchView_iconifiedByDefault
* @attr ref android.R.styleable#SearchView_maxWidth * @attr ref android.R.styleable#SearchView_maxWidth
* @attr ref android.R.styleable#SearchView_queryHint
*/ */
public class SearchView extends LinearLayout { public class SearchView extends LinearLayout {
@@ -387,6 +385,8 @@ public class SearchView extends LinearLayout {
* in the SearchableInfo. * in the SearchableInfo.
* *
* @param hint the hint text to display * @param hint the hint text to display
*
* @attr ref android.R.styleable#SearchView_queryHint
*/ */
public void setQueryHint(CharSequence hint) { public void setQueryHint(CharSequence hint) {
mQueryHint = hint; mQueryHint = hint;
@@ -402,6 +402,8 @@ public class SearchView extends LinearLayout {
* <p>The default value is true.</p> * <p>The default value is true.</p>
* *
* @param iconified whether the search field should be iconified by default * @param iconified whether the search field should be iconified by default
*
* @attr ref android.R.styleable#SearchView_iconifiedByDefault
*/ */
public void setIconifiedByDefault(boolean iconified) { public void setIconifiedByDefault(boolean iconified) {
if (mIconifiedByDefault == iconified) return; if (mIconifiedByDefault == iconified) return;

2
docs/html/guide/guide_toc.cs
View File

@@ -310,7 +310,7 @@
<span class="en">Search</span> <span class="en">Search</span>
</a></div> </a></div>
<ul> <ul>
<li><a href="<?cs var:toroot?>guide/topics/search/search-dialog.html">Using the Android Search Dialog</a></li> <li><a href="<?cs var:toroot?>guide/topics/search/search-dialog.html">Creating a Search Interface</a></li>
<li><a href="<?cs var:toroot?>guide/topics/search/adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li> <li><a href="<?cs var:toroot?>guide/topics/search/adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>
<li><a href="<?cs var:toroot?>guide/topics/search/adding-custom-suggestions.html">Adding Custom Suggestions</a></li> <li><a href="<?cs var:toroot?>guide/topics/search/adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
<li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li> <li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li>

184
docs/html/guide/topics/search/adding-custom-suggestions.jd
View File

@@ -17,8 +17,8 @@ parent.link=index.html
</li> </li>
<li><a href="#IntentForSuggestions">Declaring an Intent for Suggestions</a> <li><a href="#IntentForSuggestions">Declaring an Intent for Suggestions</a>
<ol> <ol>
<li><a href="#IntentAction">Declaring the Intent action</a></li> <li><a href="#IntentAction">Declaring the intent action</a></li>
<li><a href="#IntentData">Declaring the Intent data</a></li> <li><a href="#IntentData">Declaring the intent data</a></li>
</ol> </ol>
</li> </li>
<li><a href="#HandlingIntent">Handling the Intent</a></li> <li><a href="#HandlingIntent">Handling the Intent</a></li>
@@ -47,8 +47,8 @@ Dictionary</a></li>
</div> </div>
</div> </div>
<p>When using the Android search dialog, you can provide custom search suggestions that are <p>When using the Android search dialog or search widget, you can provide custom search suggestions
created from data in your application. For example, if your application is a word that are created from data in your application. For example, if your application is a word
dictionary, you can suggest words from the dictionary, you can suggest words from the
dictionary that match the text entered so far. These are the most valuable suggestions, because you dictionary that match the text entered so far. These are the most valuable suggestions, because you
can effectively predict what the user wants and provide instant access to it. Figure 1 shows can effectively predict what the user wants and provide instant access to it. Figure 1 shows
@@ -58,9 +58,8 @@ an example of a search dialog with custom suggestions.</p>
Search Box, providing access to your content from outside your application.</p> Search Box, providing access to your content from outside your application.</p>
<p>Before you begin with this guide to add custom suggestions, you need to have implemented the <p>Before you begin with this guide to add custom suggestions, you need to have implemented the
Android search dialog for searches in your Android search dialog or a search widget for searches in your
application. If you haven't, see <a href="search-dialog.html">Using the Android Search application. If you haven't, see <a href="search-dialog.html">Creating a Search Interface</a>.</p>
Dialog</a>.</p>
<h2 id="TheBasics">The Basics</h2> <h2 id="TheBasics">The Basics</h2>
@@ -71,11 +70,11 @@ Dialog</a>.</p>
search suggestions.</p> search suggestions.</p>
</div> </div>
<p>When the user selects a custom suggestion, the Search Manager sends an {@link <p>When the user selects a custom suggestion, the Android system sends an {@link
android.content.Intent} to android.content.Intent} to
your searchable Activity. Whereas a normal search query sends an Intent with the {@link your searchable activity. Whereas a normal search query sends an intent with the {@link
android.content.Intent#ACTION_SEARCH} action, you can instead define your custom suggestions to use android.content.Intent#ACTION_SEARCH} action, you can instead define your custom suggestions to use
{@link android.content.Intent#ACTION_VIEW} (or any other Intent action), and also include data {@link android.content.Intent#ACTION_VIEW} (or any other intent action), and also include data
that's relevant to the selected suggestion. Continuing that's relevant to the selected suggestion. Continuing
the dictionary example, when the user selects a suggestion, your application can immediately the dictionary example, when the user selects a suggestion, your application can immediately
open the definition for that word, instead of searching the dictionary for matches.</p> open the definition for that word, instead of searching the dictionary for matches.</p>
@@ -83,8 +82,8 @@ open the definition for that word, instead of searching the dictionary for match
<p>To provide custom suggestions, do the following:</p> <p>To provide custom suggestions, do the following:</p>
<ul> <ul>
<li>Implement a basic searchable Activity, as described in <a <li>Implement a basic searchable activity, as described in <a
href="search-dialog.html">Using the Android Search Dialog</a>.</li> href="search-dialog.html">Creating a Search Interface</a>.</li>
<li>Modify the searchable configuration with information about the content provider that <li>Modify the searchable configuration with information about the content provider that
provides custom suggestions.</li> provides custom suggestions.</li>
<li>Build a table (such as in an {@link android.database.sqlite.SQLiteDatabase}) for your <li>Build a table (such as in an {@link android.database.sqlite.SQLiteDatabase}) for your
@@ -96,22 +95,21 @@ in your manifest.</li>
suggestion (including a custom action and custom data). </li> suggestion (including a custom action and custom data). </li>
</ul> </ul>
<p>Just like the Search Manager displays the search dialog, it also displays your search <p>Just as the Android system displays the search dialog, it also displays your search
suggestions. All you need is a content provider from which the Search Manager can retrieve your suggestions. All you need is a content provider from which the system can retrieve your
suggestions. If you're not familiar with creating content suggestions. If you're not familiar with creating content
providers, read the <a href="{@docRoot}guide/topics/providers/content-providers.html">Content providers, read the <a href="{@docRoot}guide/topics/providers/content-providers.html">Content
Providers</a> developer guide before you continue.</p> Providers</a> developer guide before you continue.</p>
<p>When the Search Manager identifies that your Activity is searchable and provides search <p>When the system identifies that your activity is searchable and provides search
suggestions, the following procedure takes place as soon as the user enters text into the suggestions, the following procedure takes place when the user types a query:</p>
search dialog:</p>
<ol> <ol>
<li>Search Manager takes the search query text (whatever has been typed so far) and performs a <li>The system takes the search query text (whatever has been typed so far) and performs a
query to your content provider that manages your suggestions.</li> query to your content provider that manages your suggestions.</li>
<li>Your content provider returns a {@link android.database.Cursor} that points to all <li>Your content provider returns a {@link android.database.Cursor} that points to all
suggestions that are relevant to the search query text.</li> suggestions that are relevant to the search query text.</li>
<li>Search Manager displays the list of suggestions provided by the Cursor.</li> <li>The system displays the list of suggestions provided by the Cursor.</li>
</ol> </ol>
<p>Once the custom suggestions are displayed, the following might happen:</p> <p>Once the custom suggestions are displayed, the following might happen:</p>
@@ -120,9 +118,9 @@ suggestions that are relevant to the search query text.</li>
<li>If the user types another key, or changes the query in any way, the above steps are repeated <li>If the user types another key, or changes the query in any way, the above steps are repeated
and the suggestion list is updated as appropriate. </li> and the suggestion list is updated as appropriate. </li>
<li>If the user executes the search, the suggestions are ignored and the search is delivered <li>If the user executes the search, the suggestions are ignored and the search is delivered
to your searchable Activity using the normal {@link android.content.Intent#ACTION_SEARCH} to your searchable activity using the normal {@link android.content.Intent#ACTION_SEARCH}
Intent.</li> intent.</li>
<li>If the user selects a suggestion, an Intent is sent to your searchable Activity, carrying a <li>If the user selects a suggestion, an intent is sent to your searchable activity, carrying a
custom action and custom data so that your application can open the suggested content.</li> custom action and custom data so that your application can open the suggested content.</li>
</ul> </ul>
@@ -142,7 +140,7 @@ to the {@code &lt;searchable&gt;} element in your searchable configuration file.
&lt;/searchable&gt; &lt;/searchable&gt;
</pre> </pre>
<p>You might need some additional attributes, depending on the type of Intent you attach <p>You might need some additional attributes, depending on the type of intent you attach
to each suggestion and how you want to format queries to your content provider. The other optional to each suggestion and how you want to format queries to your content provider. The other optional
attributes are discussed in the following sections.</p> attributes are discussed in the following sections.</p>
@@ -155,11 +153,11 @@ providers that's covered in the <a
href="{@docRoot}guide/topics/providers/content-providers.html">Content Provider</a> developer href="{@docRoot}guide/topics/providers/content-providers.html">Content Provider</a> developer
guide. For the most part, a content provider for custom suggestions is the guide. For the most part, a content provider for custom suggestions is the
same as any other content provider. However, for each suggestion you provide, the respective row in same as any other content provider. However, for each suggestion you provide, the respective row in
the {@link android.database.Cursor} must include specific columns that the Search Manager the {@link android.database.Cursor} must include specific columns that the system
understands and uses to format the suggestions.</p> understands and uses to format the suggestions.</p>
<p>When the user starts typing into the search dialog, the Search Manager queries your content <p>When the user starts typing into the search dialog or search widget, the system queries
provider for suggestions by calling {@link your content provider for suggestions by calling {@link
android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} each time android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} each time
a letter is typed. In your implementation of {@link a letter is typed. In your implementation of {@link
android.content.ContentProvider#query(Uri,String[],String,String[],String) query()}, your android.content.ContentProvider#query(Uri,String[],String,String[],String) query()}, your
@@ -170,22 +168,22 @@ android.database.Cursor} that points to the rows you have determined to be good
two sections:</p> two sections:</p>
<dl> <dl>
<dt><a href="#HandlingSuggestionQuery">Handling the suggestion query</a></dt> <dt><a href="#HandlingSuggestionQuery">Handling the suggestion query</a></dt>
<dd>How the Search Manager sends requests to your content provider and how to handle them</dd> <dd>How the system sends requests to your content provider and how to handle them</dd>
<dt><a href="#SuggestionTable">Building a suggestion table</a></dt> <dt><a href="#SuggestionTable">Building a suggestion table</a></dt>
<dd>How to define the columns that the Search Manager expects in the {@link <dd>How to define the columns that the system expects in the {@link
android.database.Cursor} returned with each query</dd> android.database.Cursor} returned with each query</dd>
</dl> </dl>
<h3 id="HandlingSuggestionQuery">Handling the suggestion query</h3> <h3 id="HandlingSuggestionQuery">Handling the suggestion query</h3>
<p>When the Search Manager requests suggestions from your content provider, it calls your content <p>When the system requests suggestions from your content provider, it calls your content
provider's {@link android.content.ContentProvider#query(Uri,String[],String,String[],String) provider's {@link android.content.ContentProvider#query(Uri,String[],String,String[],String)
query()} method. You must query()} method. You must
implement this method to search your suggestion data and return a implement this method to search your suggestion data and return a
{@link android.database.Cursor} pointing to the suggestions you deem relevant.</p> {@link android.database.Cursor} pointing to the suggestions you deem relevant.</p>
<p>Here's a summary of the parameters that the Search Manager passes to your {@link <p>Here's a summary of the parameters that the system passes to your {@link
android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} method android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} method
(listed in order):</p> (listed in order):</p>
@@ -196,7 +194,7 @@ android.content.ContentProvider#query(Uri,String[],String,String[],String) query
content://<em>your.authority</em>/<em>optional.suggest.path</em>/<em>{@link content://<em>your.authority</em>/<em>optional.suggest.path</em>/<em>{@link
android.app.SearchManager#SUGGEST_URI_PATH_QUERY}</em> android.app.SearchManager#SUGGEST_URI_PATH_QUERY}</em>
</pre> </pre>
<p>The default behavior is for Search Manager to pass this URI and append it with the query text. <p>The default behavior is for system to pass this URI and append it with the query text.
For example:</p> For example:</p>
<pre class="no-pretty-print"> <pre class="no-pretty-print">
content://<em>your.authority</em>/<em>optional.suggest.path</em>/<em>{@link content://<em>your.authority</em>/<em>optional.suggest.path</em>/<em>{@link
@@ -233,7 +231,7 @@ about using this to <a href="#GetTheQuery">get the query</a> below.</dd>
<dd>Always null</dd> <dd>Always null</dd>
</dl> </dl>
<p>The Search Manager can send you the search query text in two ways. The <p>The system can send you the search query text in two ways. The
default manner is for the query text to be included as the last path of the content default manner is for the query text to be included as the last path of the content
URI passed in the {@code uri} parameter. However, if you include a selection value in your URI passed in the {@code uri} parameter. However, if you include a selection value in your
searchable configuration's {@code searchable configuration's {@code
@@ -251,8 +249,8 @@ parameter (a {@link android.net.Uri} object). To retrieve the query text in this
String query = uri.getLastPathSegment().toLowerCase(); String query = uri.getLastPathSegment().toLowerCase();
</pre> </pre>
<p>This returns the last segment of the {@link android.net.Uri}, which is the query text entered in <p>This returns the last segment of the {@link android.net.Uri}, which is the query text entered
the search dialog.</p> by the user.</p>
@@ -264,7 +262,7 @@ receive everything it needs to perform the look-up and you want the
{@code selection} and {@code selectionArgs} parameters to carry the appropriate values. In such a {@code selection} and {@code selectionArgs} parameters to carry the appropriate values. In such a
case, add the {@code android:searchSuggestSelection} attribute to your searchable configuration with case, add the {@code android:searchSuggestSelection} attribute to your searchable configuration with
your SQLite selection string. In the selection string, include a question mark ("?") as your SQLite selection string. In the selection string, include a question mark ("?") as
a placeholder for the actual search query. The Search Manager calls {@link a placeholder for the actual search query. The system calls {@link
android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} with the android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} with the
selection string as the {@code selection} parameter and the search query as the first selection string as the {@code selection} parameter and the search query as the first
element in the {@code selectionArgs} array.</p> element in the {@code selectionArgs} array.</p>
@@ -278,15 +276,15 @@ create a full-text search statement:</p>
android:label="@string/app_label" android:label="@string/app_label"
android:hint="@string/search_hint" android:hint="@string/search_hint"
android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
android:searchSuggestIntentAction="android.Intent.action.VIEW" android:searchSuggestIntentAction="android.intent.action.VIEW"
<b>android:searchSuggestSelection="word MATCH ?"</b>&gt; <b>android:searchSuggestSelection="word MATCH ?"</b>&gt;
&lt;/searchable&gt; &lt;/searchable&gt;
</pre> </pre>
<p>With this configuration, your {@link <p>With this configuration, your {@link
android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} method android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} method
delivers the {@code selection} parameter as "word MATCH ?" and the {@code selectionArgs} delivers the {@code selection} parameter as {@code "word MATCH ?"} and the {@code selectionArgs}
parameter as whatever the user entered in the search dialog. When you pass these to an SQLite parameter as the search query. When you pass these to an SQLite
{@link android.database.sqlite.SQLiteDatabase#query(String,String[],String,String[],String,String, {@link android.database.sqlite.SQLiteDatabase#query(String,String[],String,String[],String,String,
String) query()} method, as their respective arguments, they are synthesized together (the String) query()} method, as their respective arguments, they are synthesized together (the
question mark is replaced with the query question mark is replaced with the query
@@ -296,9 +294,9 @@ parameter, because this value is wrapped in quotes and inserted in place of the
question mark.</p> question mark.</p>
<p>Another new attribute in the example above is {@code android:searchSuggestIntentAction}, which <p>Another new attribute in the example above is {@code android:searchSuggestIntentAction}, which
defines the Intent action sent with each Intent when the user selects a suggestion. It is defines the intent action sent with each intent when the user selects a suggestion. It is
discussed further in the section about <a href="#IntentForSuggestions">Declaring an Intent for discussed further in the section about <a href="#IntentForSuggestions">Declaring an Intent for
suggestions</a>.</p> Suggestions</a>.</p>
<p class="note"><strong>Tip:</strong> If you don't want to define a selection clause in <p class="note"><strong>Tip:</strong> If you don't want to define a selection clause in
the {@code android:searchSuggestSelection} attribute, but would still like to receive the query the {@code android:searchSuggestSelection} attribute, but would still like to receive the query
@@ -317,7 +315,7 @@ handle it.</p>
<h2>Creating a Cursor without a table</h2> <h2>Creating a Cursor without a table</h2>
<p>If your search suggestions are not stored in a table format (such as an SQLite table) using the <p>If your search suggestions are not stored in a table format (such as an SQLite table) using the
columns required by the columns required by the
Search Manager, then you can search your suggestion data for matches and then format them system, then you can search your suggestion data for matches and then format them
into the necessary table on each request. To do so, create a {@link android.database.MatrixCursor} into the necessary table on each request. To do so, create a {@link android.database.MatrixCursor}
using the required column names and then add a row for each suggestion using {@link using the required column names and then add a row for each suggestion using {@link
android.database.MatrixCursor#addRow(Object[])}. Return the final product from your Content android.database.MatrixCursor#addRow(Object[])}. Return the final product from your Content
@@ -326,18 +324,18 @@ android.content.ContentProvider#query(Uri,String[],String,String[],String) query
</div> </div>
</div> </div>
<p>When you return suggestions to the Search Manager with a {@link android.database.Cursor}, the <p>When you return suggestions to the system with a {@link android.database.Cursor}, the
Search Manager expects specific columns in each row. So, regardless of whether you system expects specific columns in each row. So, regardless of whether you
decide to store decide to store
your suggestion data in an SQLite database on the device, a database on a web server, or another your suggestion data in an SQLite database on the device, a database on a web server, or another
format on the device or web, you must format the suggestions as rows in a table and format on the device or web, you must format the suggestions as rows in a table and
present them with a {@link android.database.Cursor}. The Search present them with a {@link android.database.Cursor}. The system understands several columns, but
Manager understands several columns, but only two are required:</p> only two are required:</p>
<dl> <dl>
<dt>{@link android.provider.BaseColumns#_ID}</dt> <dt>{@link android.provider.BaseColumns#_ID}</dt>
<dd>A unique integer row ID for each suggestion. The search dialog requires this in order <dd>A unique integer row ID for each suggestion. The system requires this in order
to present suggestions in a ListView.</dd> to present suggestions in a {@link android.widget.ListView}.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}</dt>
<dd>The string that is presented as a suggestion.</dd> <dd>The string that is presented as a suggestion.</dd>
</dl> </dl>
@@ -359,35 +357,35 @@ This can be null or zero to indicate no icon in this row.</dd>
all suggestions are provided in an icon-plus-text format with the icon on the right side. This can all suggestions are provided in an icon-plus-text format with the icon on the right side. This can
be null or zero to indicate no icon in this row.</dd> be null or zero to indicate no icon in this row.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION}</dt>
<dd>An Intent action string. If this column exists and contains a value at the given row, the <dd>An intent action string. If this column exists and contains a value at the given row, the
action defined here is used when forming the suggestion's Intent. If the element is not action defined here is used when forming the suggestion's intent. If the element is not
provided, the action is taken from the {@code android:searchSuggestIntentAction} field in your provided, the action is taken from the {@code android:searchSuggestIntentAction} field in your
searchable configuration. If your action is the same for all searchable configuration. If your action is the same for all
suggestions, it is more efficient to specify the action using {@code suggestions, it is more efficient to specify the action using {@code
android:searchSuggestIntentAction} and omit this column.</dd> android:searchSuggestIntentAction} and omit this column.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA}</dt>
<dd>A data URI string. If this column exists and contains a value at the given row, this is the <dd>A data URI string. If this column exists and contains a value at the given row, this is the
data that is used when forming the suggestion's Intent. If the element is not provided, the data is data that is used when forming the suggestion's intent. If the element is not provided, the data is
taken from the {@code android:searchSuggestIntentData} field in your searchable configuration. If taken from the {@code android:searchSuggestIntentData} field in your searchable configuration. If
neither source is provided, neither source is provided,
the Intent's data field is null. If your data is the same for all suggestions, or can be the intent's data field is null. If your data is the same for all suggestions, or can be
described using a constant part and a specific ID, it is more efficient to specify it using {@code described using a constant part and a specific ID, it is more efficient to specify it using {@code
android:searchSuggestIntentData} and omit this column. android:searchSuggestIntentData} and omit this column.
</dd> </dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID}</dt>
<dd>A URI path string. If this column exists and contains a value at the given row, then "/" and <dd>A URI path string. If this column exists and contains a value at the given row, then "/" and
this value is appended to the data field in the Intent. This should only be used if the data field this value is appended to the data field in the intent. This should only be used if the data field
specified specified
by the {@code android:searchSuggestIntentData} attribute in the searchable configuration has already by the {@code android:searchSuggestIntentData} attribute in the searchable configuration has already
been set to an appropriate base string.</dd> been set to an appropriate base string.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_EXTRA_DATA}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_EXTRA_DATA}</dt>
<dd>Arbitrary data. If this column exists and contains a value at a given row, this is the <dd>Arbitrary data. If this column exists and contains a value at a given row, this is the
<em>extra</em> data used when forming the suggestion's Intent. If not provided, the <em>extra</em> data used when forming the suggestion's intent. If not provided, the
Intent's extra data field is null. This column allows suggestions to provide additional data that is intent's extra data field is null. This column allows suggestions to provide additional data that is
included as an extra in the Intent's {@link android.app.SearchManager#EXTRA_DATA_KEY} key.</dd> included as an extra in the intent's {@link android.app.SearchManager#EXTRA_DATA_KEY} key.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_QUERY}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_QUERY}</dt>
<dd>If this column exists and this element exists at the given row, this is the data that is <dd>If this column exists and this element exists at the given row, this is the data that is
used when forming the suggestion's query, included as an extra in the Intent's {@link used when forming the suggestion's query, included as an extra in the intent's {@link
android.app.SearchManager#QUERY} key. Required if suggestion's action is {@link android.app.SearchManager#QUERY} key. Required if suggestion's action is {@link
android.content.Intent#ACTION_SEARCH}, optional otherwise.</dd> android.content.Intent#ACTION_SEARCH}, optional otherwise.</dd>
<dt>{@link android.app.SearchManager#SUGGEST_COLUMN_SHORTCUT_ID}</dt> <dt>{@link android.app.SearchManager#SUGGEST_COLUMN_SHORTCUT_ID}</dt>
@@ -410,22 +408,22 @@ while the shortcut of this suggestion is being refreshed in Quick Search Box.</d
<h2 id="IntentForSuggestions">Declaring an Intent for suggestions</h2> <h2 id="IntentForSuggestions">Declaring an Intent for Suggestions</h2>
<p>When the user selects a suggestion from the list that appears below the search dialog, the Search <p>When the user selects a suggestion from the list that appears below the search dialog or widget,
Manager sends a custom {@link android.content.Intent} to your searchable Activity. You must define the system sends a custom {@link android.content.Intent} to your searchable activity. You
the action and data for the Intent.</p> must define the action and data for the intent.</p>
<h3 id="IntentAction">Declaring the Intent action</h3> <h3 id="IntentAction">Declaring the intent action</h3>
<p>The most common Intent action for a custom suggestion is {@link <p>The most common intent action for a custom suggestion is {@link
android.content.Intent#ACTION_VIEW}, which is appropriate when android.content.Intent#ACTION_VIEW}, which is appropriate when
you want to open something, like the definition for a word, a person's contact information, or a web you want to open something, like the definition for a word, a person's contact information, or a web
page. However, the Intent action can be any other action and can even be different for each page. However, the intent action can be any other action and can even be different for each
suggestion.</p> suggestion.</p>
<p>Depending on whether you want all suggestions to use the same Intent action, you <p>Depending on whether you want all suggestions to use the same intent action, you
can define the action in two ways:</p> can define the action in two ways:</p>
<ol type="a"> <ol type="a">
@@ -457,34 +455,34 @@ android:searchSuggestIntentAction} attribute with an action to be used with all
default, then override this action for some suggestions by declaring a different action in the default, then override this action for some suggestions by declaring a different action in the
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column. If you do not include {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column. If you do not include
a value in the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column, then the a value in the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column, then the
Intent provided in the {@code android:searchSuggestIntentAction} attribute is used.</p> intent provided in the {@code android:searchSuggestIntentAction} attribute is used.</p>
<p class="note"><strong>Note</strong>: If you do not include the <p class="note"><strong>Note</strong>: If you do not include the
{@code android:searchSuggestIntentAction} attribute in your searchable configuration, then you {@code android:searchSuggestIntentAction} attribute in your searchable configuration, then you
<em>must</em> include a value in the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} <em>must</em> include a value in the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION}
column for every suggestion, or the Intent will fail.</p> column for every suggestion, or the intent will fail.</p>
<h3 id="IntentData">Declaring Intent data</h3> <h3 id="IntentData">Declaring intent data</h3>
<p>When the user selects a suggestion, your searchable Activity receives the Intent with the <p>When the user selects a suggestion, your searchable activity receives the intent with the
action you've defined (as discussed in the previous section), but the Intent must also carry action you've defined (as discussed in the previous section), but the intent must also carry
data in order for your Activity to identify which suggestion was selected. Specifically, data in order for your activity to identify which suggestion was selected. Specifically,
the data should be something unique for each suggestion, such as the row ID for the suggestion in the data should be something unique for each suggestion, such as the row ID for the suggestion in
your SQLite table. When the Intent is received, your SQLite table. When the intent is received,
you can retrieve the attached data with {@link android.content.Intent#getData()} or {@link you can retrieve the attached data with {@link android.content.Intent#getData()} or {@link
android.content.Intent#getDataString()}.</p> android.content.Intent#getDataString()}.</p>
<p>You can define the data included with the Intent in two ways:</p> <p>You can define the data included with the intent in two ways:</p>
<ol type="a"> <ol type="a">
<li>Define the data for each suggestion inside the {@link <li>Define the data for each suggestion inside the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column of your suggestions table. android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column of your suggestions table.
<p>Provide all necessary data information for each Intent in the suggestions table by including the <p>Provide all necessary data information for each intent in the suggestions table by including the
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column and then populating it with {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column and then populating it with
unique data for each row. The data from this column is attached to the Intent exactly as you unique data for each row. The data from this column is attached to the intent exactly as you
define it in this column. You can then retrieve it with with {@link define it in this column. You can then retrieve it with with {@link
android.content.Intent#getData()} or {@link android.content.Intent#getDataString()}.</p> android.content.Intent#getData()} or {@link android.content.Intent#getDataString()}.</p>
@@ -498,7 +496,7 @@ projection map of column names to aliases.</p>
</li> </li>
<li>Fragment a data URI into two pieces: the portion common to all suggestions and the portion <li>Fragment a data URI into two pieces: the portion common to all suggestions and the portion
unique to each suggestion. Place these parts into the {@code android:searchSuggestIntentData} unique to each suggestion. Place these parts into the {@code android:searchSuggestintentData}
attribute of the searchable configuration and the {@link attribute of the searchable configuration and the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column of your android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column of your
suggestions table, respectively. suggestions table, respectively.
@@ -512,14 +510,14 @@ android:searchSuggestIntentData} attribute of your searchable configuration. For
android:label="@string/app_label" android:label="@string/app_label"
android:hint="@string/search_hint" android:hint="@string/search_hint"
android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
android:searchSuggestIntentAction="android.Intent.action.VIEW" android:searchSuggestIntentAction="android.intent.action.VIEW"
<b>android:searchSuggestIntentData="content://com.example/datatable"</b> > <b>android:searchSuggestIntentData="content://com.example/datatable"</b> >
&lt;/searchable> &lt;/searchable>
</pre> </pre>
<p>Then include the final path for each suggestion (the unique part) in the {@link <p>Then include the final path for each suggestion (the unique part) in the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID}
column of your suggestions table. When the user selects a suggestion, the Search Manager takes column of your suggestions table. When the user selects a suggestion, the system takes
the string from {@code android:searchSuggestIntentData}, appends a slash ("/") and then adds the the string from {@code android:searchSuggestIntentData}, appends a slash ("/") and then adds the
respective value from the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column to respective value from the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column to
form a complete content URI. You can then retrieve the {@link android.net.Uri} with with {@link form a complete content URI. You can then retrieve the {@link android.net.Uri} with with {@link
@@ -530,20 +528,20 @@ android.content.Intent#getData()}.</p>
<h4>Add more data</h4> <h4>Add more data</h4>
<p>If you need to express even more information with your Intent, you can add another table column, <p>If you need to express even more information with your intent, you can add another table column,
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_EXTRA_DATA}, which can store additional {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_EXTRA_DATA}, which can store additional
information about the suggestion. The data saved in this column is placed in {@link information about the suggestion. The data saved in this column is placed in {@link
android.app.SearchManager#EXTRA_DATA_KEY} of the Intent's extra Bundle.</p> android.app.SearchManager#EXTRA_DATA_KEY} of the intent's extra Bundle.</p>
<h2 id="HandlingIntent">Handling the Intent</h2> <h2 id="HandlingIntent">Handling the Intent</h2>
<p>Now that your search dialog provides custom search suggestions with custom Intents, you <p>Now that you provide custom search suggestions with custom intents, you
need your searchable Activity to handle these Intents when the user selects a need your searchable activity to handle these intents when the user selects a
suggestion. This is in addition to handling the {@link suggestion. This is in addition to handling the {@link
android.content.Intent#ACTION_SEARCH} Intent, which your searchable Activity already does. android.content.Intent#ACTION_SEARCH} intent, which your searchable activity already does.
Here's an example of how you can handle the Intents during your Activity {@link Here's an example of how you can handle the intents during your activity {@link
android.app.Activity#onCreate(Bundle) onCreate()} callback:</p> android.app.Activity#onCreate(Bundle) onCreate()} callback:</p>
<pre> <pre>
@@ -559,25 +557,25 @@ if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
} }
</pre> </pre>
<p>In this example, the Intent action is {@link <p>In this example, the intent action is {@link
android.content.Intent#ACTION_VIEW} and the data carries a complete URI pointing to the suggested android.content.Intent#ACTION_VIEW} and the data carries a complete URI pointing to the suggested
item, as synthesized by the {@code android:searchSuggestIntentData} string and {@link item, as synthesized by the {@code android:searchSuggestIntentData} string and {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column. The URI is then passed to the local android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column. The URI is then passed to the local
{@code showResult()} method that queries the content provider for the item specified by the URI.</p> {@code showResult()} method that queries the content provider for the item specified by the URI.</p>
<p class="note"><strong>Note:</strong> You do <em>not</em> need to add an Intent filter to your <p class="note"><strong>Note:</strong> You do <em>not</em> need to add an intent filter to your
Android manifest file for the Intent action you defined with the {@code Android manifest file for the intent action you defined with the {@code
android:searchSuggestIntentAction} attribute or {@link android:searchSuggestIntentAction} attribute or {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column. The Search Manager opens your android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column. The system opens your
searchable Activity by name to deliver the suggestion's Intent, so the Activity does not need to searchable activity by name to deliver the suggestion's intent, so the activity does not need to
declare the accepted action.</p> declare the accepted action.</p>
<h2 id="RewritingQueryText">Rewriting the query text</h2> <h2 id="RewritingQueryText">Rewriting the query text</h2>
<p>If the user navigates through the suggestions list using the directional controls (trackball or <p>If the user navigates through the suggestions list using the directional controls (such
d-pad), the text in the search dialog won't change, by default. However, you can temporarily rewrite as with a trackball or d-pad), the query text does not update, by default. However, you
the user's query text as it appears in the text box with can temporarily rewrite the user's query text as it appears in the text box with
a query that matches the suggestion currently in focus. This enables the user to see what query is a query that matches the suggestion currently in focus. This enables the user to see what query is
being suggested (if appropriate) and then select the search box and edit the query before being suggested (if appropriate) and then select the search box and edit the query before
dispatching it as a search.</p> dispatching it as a search.</p>
@@ -654,7 +652,7 @@ android:searchSettingsDescription} attribute to your searchable configuration. F
android:label="@string/app_label" android:label="@string/app_label"
android:hint="@string/search_hint" android:hint="@string/search_hint"
android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
android:searchSuggestIntentAction="android.Intent.action.VIEW" android:searchSuggestIntentAction="android.intent.action.VIEW"
android:includeInGlobalSearch="true" android:includeInGlobalSearch="true"
<b>android:searchSettingsDescription="@string/search_description"</b> > <b>android:searchSettingsDescription="@string/search_description"</b> >
&lt;/searchable> &lt;/searchable>
@@ -676,7 +674,7 @@ them how to enable search suggestions for Quick Search Box.</p>
<h3 id="ManagingShortcuts">Managing Quick Search Box suggestion shortcuts</h3> <h3 id="ManagingShortcuts">Managing Quick Search Box suggestion shortcuts</h3>
<p>Suggestions that the user selects from Quick Search Box can be automatically made into shortcuts. <p>Suggestions that the user selects from Quick Search Box can be automatically made into shortcuts.
These are suggestions that the Search Manager has copied from your content provider so it can These are suggestions that the system has copied from your content provider so it can
quickly access the suggestion without the need to re-query your content provider. </p> quickly access the suggestion without the need to re-query your content provider. </p>
<p>By default, this is enabled for all suggestions retrieved by Quick Search Box, but if your <p>By default, this is enabled for all suggestions retrieved by Quick Search Box, but if your

57
docs/html/guide/topics/search/adding-recent-query-suggestions.jd
View File

@@ -28,13 +28,15 @@ Configuration</a></li>
</div> </div>
</div> </div>
<p>When using the Android search dialog, you can provide search suggestions based on recent search <p>When using the Android search dialog or search widget, you can provide search suggestions based
on recent search
queries. For example, if a user previously searched for "puppies," then that query appears as a queries. For example, if a user previously searched for "puppies," then that query appears as a
suggestion once he or she begins typing the same query. Figure 1 shows an example of a search dialog suggestion once he or she begins typing the same query. Figure 1 shows an example of a search dialog
with recent query suggestions.</p> with recent query suggestions.</p>
<p>Before you begin, you need to implement the search dialog for basic searches in your application. <p>Before you begin, you need to implement the search dialog or a search widget for basic searches
If you haven't, see <a href="search-dialog.html">Using the Android Search Dialog</a>.</p> in your application.
If you haven't, see <a href="search-dialog.html">Creating a Search Interface</a>.</p>
@@ -47,16 +49,16 @@ suggestions.</p>
</div> </div>
<p>Recent query suggestions are simply saved searches. When the user selects one of <p>Recent query suggestions are simply saved searches. When the user selects one of
the suggestions, your searchable Activity receives a {@link the suggestions, your searchable activity receives a {@link
android.content.Intent#ACTION_SEARCH} Intent with the suggestion as the search query, which your android.content.Intent#ACTION_SEARCH} intent with the suggestion as the search query, which your
searchable Activity already handles (as described in <a href="search-dialog.html">Using the Android searchable activity already handles (as described in <a href="search-dialog.html">Creating a Search
Search Dialog</a>).</p> Interface</a>).</p>
<p>To provide recent queries suggestions, you need to:</p> <p>To provide recent queries suggestions, you need to:</p>
<ul> <ul>
<li>Implement a searchable Activity, <a <li>Implement a searchable activity, as described in <a
href="{@docRoot}guide/topics/search/search-dialog.html">using the Android Search Dialog</a>.</li> href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</li>
<li>Create a content provider that extends {@link <li>Create a content provider that extends {@link
android.content.SearchRecentSuggestionsProvider} and declare it in your application manifest.</li> android.content.SearchRecentSuggestionsProvider} and declare it in your application manifest.</li>
<li>Modify the searchable configuration with information about the content provider that <li>Modify the searchable configuration with information about the content provider that
@@ -64,20 +66,19 @@ provides search suggestions.</li>
<li>Save queries to your content provider each time a search is executed.</li> <li>Save queries to your content provider each time a search is executed.</li>
</ul> </ul>
<p>Just as the Search Manager displays the search dialog, it also displays the <p>Just as the Android system displays the search dialog, it also displays the
search suggestions. All you need to do is provide a source from which the suggestions can be search suggestions below the dialog or search widget. All you need to do is provide a source from
retrieved.</p> which the system can retrieve suggestions.</p>
<p>When the Search Manager identifies that your Activity is searchable and provides search <p>When the system identifies that your activity is searchable and provides search
suggestions, the following procedure takes place as soon as the user types into the search suggestions, the following procedure takes place as soon as the user begins typing a query:</p>
dialog:</p>
<ol> <ol>
<li>Search Manager takes the search query text (whatever has been typed so far) and performs a <li>The system takes the search query text (whatever has been typed so far) and performs a
query to the content provider that contains your suggestions.</li> query to the content provider that contains your suggestions.</li>
<li>Your content provider returns a {@link android.database.Cursor} that points to all <li>Your content provider returns a {@link android.database.Cursor} that points to all
suggestions that match the search query text.</li> suggestions that match the search query text.</li>
<li>Search Manager displays the list of suggestions provided by the Cursor.</li> <li>The system displays the list of suggestions provided by the Cursor.</li>
</ol> </ol>
<p>Once the recent query suggestions are displayed, the following might happen:</p> <p>Once the recent query suggestions are displayed, the following might happen:</p>
@@ -86,10 +87,10 @@ suggestions that match the search query text.</li>
<li>If the user types another key, or changes the query in any way, the aforementioned steps are <li>If the user types another key, or changes the query in any way, the aforementioned steps are
repeated and the suggestion list is updated.</li> repeated and the suggestion list is updated.</li>
<li>If the user executes the search, the suggestions are ignored and the search is delivered <li>If the user executes the search, the suggestions are ignored and the search is delivered
to your searchable Activity using the normal {@link android.content.Intent#ACTION_SEARCH} to your searchable activity using the normal {@link android.content.Intent#ACTION_SEARCH}
Intent.</li> intent.</li>
<li>If the user selects a suggestion, an <li>If the user selects a suggestion, an
{@link android.content.Intent#ACTION_SEARCH} Intent is delivered to your searchable Activity using {@link android.content.Intent#ACTION_SEARCH} intent is delivered to your searchable activity using
the suggested text as the query.</li> the suggested text as the query.</li>
</ul> </ul>
@@ -151,7 +152,7 @@ searchable configuration). For example:</p>
<h2 id="RecentQuerySearchableConfiguration">Modifying the Searchable Configuration</h2> <h2 id="RecentQuerySearchableConfiguration">Modifying the Searchable Configuration</h2>
<p>To configure your search dialog to use your suggestions provider, you need to add <p>To configure the system to use your suggestions provider, you need to add
the {@code android:searchSuggestAuthority} and {@code android:searchSuggestSelection} attributes to the {@code android:searchSuggestAuthority} and {@code android:searchSuggestSelection} attributes to
the {@code &lt;searchable&gt;} element in your searchable configuration file. For example:</p> the {@code &lt;searchable&gt;} element in your searchable configuration file. For example:</p>
@@ -179,12 +180,12 @@ automatically replaced by the query text entered by the user).</p>
<h2 id="SavingQueries">Saving Queries</h2> <h2 id="SavingQueries">Saving Queries</h2>
<p>To populate your collection of recent queries, add each query <p>To populate your collection of recent queries, add each query
received by your searchable Activity to your {@link received by your searchable activity to your {@link
android.content.SearchRecentSuggestionsProvider}. To do this, create an instance of {@link android.content.SearchRecentSuggestionsProvider}. To do this, create an instance of {@link
android.provider.SearchRecentSuggestions} and call {@link android.provider.SearchRecentSuggestions} and call {@link
android.provider.SearchRecentSuggestions#saveRecentQuery(String,String) saveRecentQuery()} each time android.provider.SearchRecentSuggestions#saveRecentQuery(String,String) saveRecentQuery()} each time
your searchable Activity receives a query. For example, here's how you can save the query during your searchable activity receives a query. For example, here's how you can save the query during
your Activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p> your activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p>
<pre> <pre>
&#64;Override &#64;Override
@@ -192,10 +193,10 @@ public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState); super.onCreate(savedInstanceState);
setContentView(R.layout.main); setContentView(R.layout.main);
Intent Intent = getIntent(); Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(Intent .getAction())) { if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
String query = Intent .getStringExtra(SearchManager.QUERY); String query = intent.getStringExtra(SearchManager.QUERY);
SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this, SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE); MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
suggestions.saveRecentQuery(query, null); suggestions.saveRecentQuery(query, null);
@@ -212,7 +213,7 @@ the search query string as the first parameter and, optionally, a second string
second line of the suggestion (or null). The second parameter is only used if you've enabled second line of the suggestion (or null). The second parameter is only used if you've enabled
two-line mode for the search suggestions with {@link two-line mode for the search suggestions with {@link
android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}. If you have enabled android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}. If you have enabled
two-line mode, then the query text is also matched against this second line when the Search Manager two-line mode, then the query text is also matched against this second line when the system
looks for matching suggestions.</p> looks for matching suggestions.</p>

49
docs/html/guide/topics/search/index.jd
View File

@@ -5,7 +5,7 @@ page.title=Search
<div id="qv"> <div id="qv">
<h2>Topics</h2> <h2>Topics</h2>
<ol> <ol>
<li><a href="search-dialog.html">Using the Android Search Dialog</a></li> <li><a href="search-dialog.html">Creating a Search Interface</a></li>
<li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</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> <li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
</ol> </ol>
@@ -24,9 +24,8 @@ Dictionary</a></li>
<p>Search is a core user feature on Android. Users should be able <p>Search is a core user feature on Android. Users should be able
to search any data that is available to them, whether the content is located on the device or to search any data that is available to them, whether the content is located on the device or
the Internet. The search experience should be seamless and consistent across the entire the Internet. To help create a consistent search experience for users, Android provides a
system, which is why Android provides a search framework to help you provide users with search framework that helps you implement search for your application.</p>
a familiar search dialog and a great search experience.</p>
<div class="figure" style="width:250px"> <div class="figure" style="width:250px">
<img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" /> <img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" />
@@ -34,16 +33,14 @@ a familiar search dialog and a great search experience.</p>
search suggestions.</p> search suggestions.</p>
</div> </div>
<p>Android's search framework provides a user interface in which users can perform a search and <p>The search framework offers two modes of search input: a search dialog at the top of the
an interaction layer that communicates with your application, so you don't have to build screen or a search widget ({@link android.widget.SearchView}) that you can embed in your activity
your own search Activity. Instead, a search dialog appears at the top of the screen at the user's layout. In either case, the Android system will assist your search implementation by
command without interrupting the current Activity.</p> delivering search queries to a specific activity that performs searchs. You can also enable either
the search dialog or widget to provide search suggestions as the user types. Figure 1 shows an
example of the search dialog with optional search suggestions.</p>
<p>The search framework manages the life of the search dialog. When users execute a search, the <p>Once you've set up either the search dialog or the search widget, you can:</p>
search framework passes the query text to your application so your application can perform a
search. Figure 1 shows an example of the search dialog with optional search suggestions.</p>
<p>Once your application is set up to use the search dialog, you can:</p>
<ul> <ul>
<li>Enable voice search</li> <li>Enable voice search</li>
@@ -57,19 +54,19 @@ search your data. To perform a search, you need to use APIs appropriate for your
if your data is stored in an SQLite database, you should use the {@link android.database.sqlite} if your data is stored in an SQLite database, you should use the {@link android.database.sqlite}
APIs to perform searches.</p> APIs to perform searches.</p>
<p>The following documents show you how to use the search dialog in your application:</p> <p>The following documents show you how to use Android's framework to implement search:</p>
<dl> <dl>
<dt><strong><a href="search-dialog.html">Using the Android Search Dialog</a></strong></dt> <dt><strong><a href="search-dialog.html">Creating a Search Interface</a></strong></dt>
<dd>How to set up your application to use the search dialog. </dd> <dd>How to set up your application to use the search dialog or search widget. </dd>
<dt><strong><a href="adding-recent-query-suggestions.html">Adding Recent Query <dt><strong><a href="adding-recent-query-suggestions.html">Adding Recent Query
Suggestions</a></strong></dt> Suggestions</a></strong></dt>
<dd>How to show suggestions based on queries previously used in the search dialog.</dd> <dd>How to provide suggestions based on queries previously used.</dd>
<dt><strong><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></strong></dt> <dt><strong><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></strong></dt>
<dd>How to show suggestions based on custom data from your application and offer your suggestions <dd>How to provide suggestions based on custom data from your application and also offer them
in the system-wide Quick Search Box.</dd> in the system-wide Quick Search Box.</dd>
<dt><strong><a href="searchable-config.html">Searchable Configuration</a></strong></dt> <dt><strong><a href="searchable-config.html">Searchable Configuration</a></strong></dt>
<dd>A reference for the searchable configuration file (though the other <dd>A reference document for the searchable configuration file (though the other
documents also discuss the configuration file in terms of specific behaviors).</dd> documents also discuss the configuration file in terms of specific behaviors).</dd>
</dl> </dl>
@@ -92,17 +89,17 @@ you don't need to send the user ID as well; send only the zip code to the server
send the personal information, you should not log it. If you must log it, protect that data send the personal information, you should not log it. If you must log it, protect that data
very carefully and erase it as soon as possible.</p> very carefully and erase it as soon as possible.</p>
</li> </li>
<li><strong>Provide the user with a way to clear their search history.</strong> <li><strong>Provide users with a way to clear their search history.</strong>
<p>The search framework helps your application provide context-specific suggestions while the user <p>The search framework helps your application provide context-specific suggestions while the user
types. Sometimes these types. Sometimes these
suggestions are based on previous searches or other actions taken by the user in an earlier suggestions are based on previous searches or other actions taken by the user in an earlier
session. A user might not wish for previous searches to be revealed to other device users, for session. A user might not wish for previous searches to be revealed to other device users, for
instance, if they share their phone with a friend. If your application provides suggestions that can instance, if the user shares the device with a friend. If your application provides suggestions that
reveal previous activities, you should implement the ability for the user to clear the search can reveal previous search activities, you should implement the ability for the user to clear the
history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply call the search history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply
{@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing call the {@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are
custom suggestions, you'll need to provide a similar "clear history" method in your provider that implementing custom suggestions, you'll need to provide a similar "clear history" method in your
the user can execute.</p> content provider that the user can execute.</p>
</li> </li>
</ul> </ul>

769
docs/html/guide/topics/search/search-dialog.jd
View File

File diff suppressed because it is too large Load Diff

66
docs/html/guide/topics/search/searchable-config.jd
View File

@@ -7,19 +7,20 @@ parent.link=index.html
<div id="qv"> <div id="qv">
<h2>See also</h2> <h2>See also</h2>
<ol> <ol>
<li><a href="search-dialog.html">Using the Android Search Dialog</a></li> <li><a href="search-dialog.html">Creating a Search Interface</a></li>
<li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</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> <li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li>
</ol> </ol>
</div> </div>
</div> </div>
<p>To utilize the Android search framework and provide a custom search dialog, your <p>In order to implement search with assistance from the Android system (to deliver search queries
application must provide a search to an activity and provide search suggestions), your application must provide a search configuration
configuration in the form of an XML resource. This document describes the search configuration XML in the form of an XML file.</p>
in terms of its syntax and usage. For more information about how to implement search
features for your application, see the developer guide about <a <p>This page describes the search configuration file in terms of its syntax and usage. For more
href="index.html">Search</a>.</p> information about how to implement search features for your application, begin with the developer
guide about <a href="search-dialog.html">Creating a Search Interface</a>.</p>
<dl class="xml"> <dl class="xml">
@@ -66,7 +67,7 @@ Android uses the filename as the resource ID.</dd>
<dd> <dd>
<dl class="tag-list"> <dl class="tag-list">
<dt id="searchable-element"><code>&lt;searchable&gt;</code></dt> <dt id="searchable-element"><code>&lt;searchable&gt;</code></dt>
<dd>Defines all search configurations used with the search dialog. <dd>Defines all search configurations used by the Android system to provide assisted search.
<p class="caps">attributes:</p> <p class="caps">attributes:</p>
<dl class="atn-list"> <dl class="atn-list">
<dt><code>android:label</code></dt> <dt><code>android:label</code></dt>
@@ -86,21 +87,21 @@ string for {@code android:hint} as "Search <em>&lt;content-or-product&gt;</em>".
"Search songs and artists" or "Search YouTube".</dd> "Search songs and artists" or "Search YouTube".</dd>
<dt><code>android:searchMode</code></dt> <dt><code>android:searchMode</code></dt>
<dd><em>Keyword</em>. Sets additional modes that control the search dialog presentation. <dd><em>Keyword</em>. Sets additional modes that control the search presentation.
Currently available modes define how the query text that appears in the search dialog Currently available modes define how the query text should be rewritten when a custom suggestion
should be rewritten when a custom suggestion receives focus. The following mode values are accepted: receives focus. The following mode values are accepted:
<table> <table>
<tr><th>Value</th><th>Description</th></tr> <tr><th>Value</th><th>Description</th></tr>
<tr> <tr>
<td><code>"queryRewriteFromText"</code></td> <td><code>"queryRewriteFromText"</code></td>
<td>Use the value from the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1} <td>Use the value from the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}
colum to rewrite the query text in the search dialog.</td> column to rewrite the query text.</td>
</tr> </tr>
<tr> <tr>
<td><code>"queryRewriteFromData"</code></td> <td><code>"queryRewriteFromData"</code></td>
<td>Use the value from the <td>Use the value from the
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column to rewrite the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column to rewrite the
query text in the search dialog. This should only be used when the values in query text. This should only be used when the values in
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user
inspection and editing, typically HTTP URI's.</td> inspection and editing, typically HTTP URI's.</td>
</tr> </tr>
@@ -117,7 +118,7 @@ behavior is something other than a search (such as a URL request in a web browse
<dt><code>android:inputType</code></dt> <dt><code>android:inputType</code></dt>
<dd><em>Keyword</em>. Defines the type of input method (such as the type of soft keyboard) <dd><em>Keyword</em>. Defines the type of input method (such as the type of soft keyboard)
to use with the search dialog. For most searches, in which free-form text is expected, you don't to use. For most searches, in which free-form text is expected, you don't
need this attribute. See {@link android.R.attr#inputType} for a list of suitable values for this need this attribute. See {@link android.R.attr#inputType} for a list of suitable values for this
attribute.</dd> attribute.</dd>
@@ -161,14 +162,14 @@ can also use any non-null value to trigger the delivery of the query text via th
selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd> selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd>
<dt><code>android:searchSuggestIntentAction</code></dt> <dt><code>android:searchSuggestIntentAction</code></dt>
<dd><em>String</em>. The default Intent action to be used when a user <dd><em>String</em>. The default intent action to be used when a user
clicks on a custom search suggestion (such as {@code "android.intent.action.VIEW"}). clicks on a custom search suggestion (such as {@code "android.intent.action.VIEW"}).
If this is not overridden by the selected suggestion (via the {@link If this is not overridden by the selected suggestion (via the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value is placed in the action android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value is placed in the action
field of the {@link android.content.Intent} when the user clicks a suggestion.</dd> field of the {@link android.content.Intent} when the user clicks a suggestion.</dd>
<dt><code>android:searchSuggestIntentData</code></dt> <dt><code>android:searchSuggestIntentData</code></dt>
<dd><em>String</em>. The default Intent data to be used when a user <dd><em>String</em>. The default intent data to be used when a user
clicks on a custom search suggestion. clicks on a custom search suggestion.
If not overridden by the selected suggestion (via the {@link If not overridden by the selected suggestion (via the {@link
android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is
@@ -177,7 +178,7 @@ android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is
<dt><code>android:searchSuggestThreshold</code></dt> <dt><code>android:searchSuggestThreshold</code></dt>
<dd><em>Integer</em>. The minimum number of characters needed to <dd><em>Integer</em>. The minimum number of characters needed to
trigger a suggestion look-up. Only guarantees that the Search Manager will not query your trigger a suggestion look-up. Only guarantees that the system will not query your
content provider for anything shorter than the threshold. The default value is 0.</dd> content provider for anything shorter than the threshold. The default value is 0.</dd>
</dl> </dl>
@@ -210,20 +211,21 @@ albums, and tracks" for a music application, or "Saved notes" for a notepad appl
supersets of queries that have returned zero results in the past. For example, if supersets of queries that have returned zero results in the past. For example, if
your content provider returned zero results for "bo", it should be requiried for "bob". If set to your content provider returned zero results for "bo", it should be requiried for "bob". If set to
"false", supersets are ignored for a single session ("bob" does not invoke a requery). This lasts "false", supersets are ignored for a single session ("bob" does not invoke a requery). This lasts
only for the life of the search dialog (when the search dialog is reopened, "bo" queries your only for the life of the search dialog or the life of the activity when using the search widget
(when the search dialog or activity is reopened, "bo" queries your
content provider again). The default value is false.</dd> content provider again). The default value is false.</dd>
</dl> </dl>
<h4>Voice search attributes</h4> <h4>Voice search attributes</h4>
<p>To enable voice search for your search dialog, you'll need some of the <p>To enable voice search, you'll need some of the
following {@code &lt;searchable>} attributes:</p><br/> following {@code &lt;searchable>} attributes:</p><br/>
<dl class="atn-list"> <dl class="atn-list">
<dt><code>android:voiceSearchMode</code></dt> <dt><code>android:voiceSearchMode</code></dt>
<dd><em>Keyword</em>. (Required to provide voice search capabilities.) <dd><em>Keyword</em>. (Required to provide voice search capabilities.)
Enables voice search for the search dialog, with a specific mode for voice search. Enables voice search, with a specific mode for voice search.
(Voice search may not be provided by the device, in which case these flags (Voice search may not be provided by the device, in which case these flags
have no effect.) The following mode values are accepted: have no effect.) The following mode values are accepted:
<table> <table>
@@ -238,14 +240,14 @@ then either {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be
<td><code>"launchWebSearch"</code></td> <td><code>"launchWebSearch"</code></td>
<td>The voice search button takes the user directly <td>The voice search button takes the user directly
to a built-in voice web search activity. Most applications don't need this flag, as to a built-in voice web search activity. Most applications don't need this flag, as
it takes the user away from the Activity in which search was invoked.</td> it takes the user away from the activity in which search was invoked.</td>
</tr> </tr>
<tr> <tr>
<td><code>"launchRecognizer"</code></td> <td><code>"launchRecognizer"</code></td>
<td>The voice search button takes <td>The voice search button takes
the user directly to a built-in voice recording activity. This Activity the user directly to a built-in voice recording activity. This activity
prompts the user to speak, transcribes the spoken text, and forwards the resulting prompts the user to speak, transcribes the spoken text, and forwards the resulting
query text to the searchable Activity, just as if the user typed it into the query text to the searchable activity, just as if the user typed it into the
search UI and clicked the search button.</td> search UI and clicked the search button.</td>
</tr> </tr>
</table> </table>
@@ -283,9 +285,9 @@ java.util.Locale#getDefault() Locale.getDefault()}.</dd>
<dt><code>android:voiceMaxResults</code></dt> <dt><code>android:voiceMaxResults</code></dt>
<dd><em>Integer</em>. Forces the maximum number of results to return, <dd><em>Integer</em>. Forces the maximum number of results to return,
including the "best" result which is always provided as the {@link including the "best" result which is always provided as the {@link
android.content.Intent#ACTION_SEARCH} Intent's primary android.content.Intent#ACTION_SEARCH} intent's primary
query. Must be 1 or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS} to query. Must be 1 or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS} to
get the results from the Intent. get the results from the intent.
If not provided, the recognizer chooses how many results to return.</dd> If not provided, the recognizer chooses how many results to return.</dd>
</dl> </dl>
</dd> <!-- end searchable element --> </dd> <!-- end searchable element -->
@@ -311,8 +313,8 @@ other three attributes in order to define the search action.</p>
<dd><em>String</em>. (Required.) A key code from {@link <dd><em>String</em>. (Required.) A key code from {@link
android.view.KeyEvent} that represents the action key android.view.KeyEvent} that represents the action key
you wish to respond to (for example {@code "KEYCODE_CALL"}). This is added to the you wish to respond to (for example {@code "KEYCODE_CALL"}). This is added to the
{@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that is passed to your
searchable Activity. To examine the key code, use searchable activity. To examine the key code, use
{@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. Not all {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. Not all
keys are supported for a search action, as many of them are used for typing, navigation, or system keys are supported for a search action, as many of them are used for typing, navigation, or system
functions.</dd> functions.</dd>
@@ -320,15 +322,15 @@ functions.</dd>
<dt><code>android:queryActionMsg</code></dt> <dt><code>android:queryActionMsg</code></dt>
<dd><em>String</em>. An action message to be sent if the action key is pressed while the <dd><em>String</em>. An action message to be sent if the action key is pressed while the
user is entering query text. This is added to the user is entering query text. This is added to the
{@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that the Search Manager {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that the system
passes to your searchable Activity. To examine the string, use passes to your searchable activity. To examine the string, use
{@link android.content.Intent#getStringExtra {@link android.content.Intent#getStringExtra
getStringExtra(SearchManager.ACTION_MSG)}.</dd> getStringExtra(SearchManager.ACTION_MSG)}.</dd>
<dt><code>android:suggestActionMsg</code></dt> <dt><code>android:suggestActionMsg</code></dt>
<dd><em>String</em>. An action message to be sent if the action key is pressed while a <dd><em>String</em>. An action message to be sent if the action key is pressed while a
suggestion is in focus. This is added to the suggestion is in focus. This is added to the
Intent that that the Search Manager passes to your searchable Activity (using the action intent that that the system passes to your searchable activity (using the action
you've defined for the suggestion). To examine the string, you've defined for the suggestion). To examine the string,
use {@link android.content.Intent#getStringExtra use {@link android.content.Intent#getStringExtra
getStringExtra(SearchManager.ACTION_MSG)}. This should only be used if all your getStringExtra(SearchManager.ACTION_MSG)}. This should only be used if all your
@@ -344,10 +346,10 @@ android:suggestActionMsg} attribute to define the action message for all suggest
your content provider provides its own action message. your content provider provides its own action message.
<p>First, you must define a column in your <p>First, you must define a column in your
content provider for each suggestion to provide an action message, then provide the name of that content provider for each suggestion to provide an action message, then provide the name of that
column in this attribute. The Search Manager looks at your suggestion cursor, column in this attribute. The system looks at your suggestion cursor,
using the string provided here to select your action message column, and using the string provided here to select your action message column, and
then select the action message string from the Cursor. That string is added to the then select the action message string from the Cursor. That string is added to the
Intent that the Search Manager passes to your searchable Activity (using the action you've intent that the system passes to your searchable activity (using the action you've
defined for suggestions). To examine the string, use {@link defined for suggestions). To examine the string, use {@link
android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data
does not exist for the selected suggestion, the action key is ignored.</dd> does not exist for the selected suggestion, the action key is ignored.</dd>

11
docs/html/guide/topics/ui/actionbar.jd
View File

@@ -323,8 +323,7 @@ the item is enabled as an action item.</p>
<p>When adding an action view for a menu item, it's important that you still allow the item to <p>When adding an action view for a menu item, it's important that you still allow the item to
behave as a normal menu item when it does not appear in the Action Bar. For example, a menu item to behave as a normal menu item when it does not appear in the Action Bar. For example, a menu item to
perform a search should, by default, bring up the <a perform a search should, by default, bring up the Android search dialog, but if the item is
href="{@docRoot}guide/topics/search/search-dialog.html">search dialog</a>, but if the item is
placed in the Action Bar, the action view appears with a {@link android.widget.SearchView} placed in the Action Bar, the action view appears with a {@link android.widget.SearchView}
widget. Figure 4 shows an example of the {@link android.widget.SearchView} widget in an action widget. Figure 4 shows an example of the {@link android.widget.SearchView} widget in an action
view.</p> view.</p>
@@ -369,9 +368,7 @@ always appear as an action view by setting {@code android:showAsAction} to {@cod
<p>Now, when the menu item is displayed as an action item, it's action view appears instead of <p>Now, when the menu item is displayed as an action item, it's action view appears instead of
the icon and/or title text. However, if there's not enough room in the Action Bar, the item appears the icon and/or title text. However, if there's not enough room in the Action Bar, the item appears
in the overflow menu as a normal menu item and you must respond to it from the {@link in the overflow menu as a normal menu item and you must respond to it from the {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method. (For a android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p>
guide to providing search functionality, see the <a
href="{@docRoot}guide/topics/search/index.html">Search</a> documentation.)</p>
<p>When the activity first starts, the system populates the Action Bar and overflow menu by calling <p>When the activity first starts, the system populates the Action Bar and overflow menu by calling
{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()}. {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()}.
@@ -392,8 +389,8 @@ public boolean onCreateOptionsMenu(Menu menu) {
} }
</pre> </pre>
<p>For more information about enabling search in the Action Bar, see the <a <p>For more information about using the search widget, see <a
href="{@docRoot}guide/topics/search/index.html">Search</a> developer guide.</p> href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</p>

9
docs/html/sdk/android-3.0.jd
View File

@@ -556,11 +556,10 @@ keyboard) is visible, the popup does not overlap the IME it until the user touch
menu.</p></li> menu.</p></li>
<li>{@link android.widget.SearchView} <li>{@link android.widget.SearchView}
<p>Provides a search box that works in conjunction with the Search Manager (in the same manner <p>Provides a search box that you can configure to deliver search queries to a specified
as the traditional <a href="{@docRoot}guide/topics/search/search-dialog.html">search dialog</a>). It activity and display search suggestions (in the same manner as the traditional search dialog). This
can also display recent query suggestions or custom suggestions as configured by the search widget is particularly useful for offering a search widget in the Action Bar. For more information,
provider. This widget is particularly useful for offering search in the <a see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</p>.</li>
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>.</p></li>
<li>{@link android.widget.StackView} <li>{@link android.widget.StackView}
<p>A view that displays its children in a 3D stack and allows users to swipe through <p>A view that displays its children in a 3D stack and allows users to swipe through