From abdf0d533c292709e51cee2c1213d5e44baca963 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 8 Feb 2011 10:20:27 -0800 Subject: docs: update search dev guide with SearcView widget Change-Id: Ieb0ccdb78760a3c90df2381e647463f7532b0efc --- core/java/android/widget/SearchView.java | 16 +- docs/html/guide/guide_toc.cs | 2 +- .../topics/search/adding-custom-suggestions.jd | 184 +++-- .../search/adding-recent-query-suggestions.jd | 57 +- docs/html/guide/topics/search/index.jd | 49 +- docs/html/guide/topics/search/search-dialog.jd | 775 ++++++++++++++------- docs/html/guide/topics/search/searchable-config.jd | 66 +- docs/html/guide/topics/ui/actionbar.jd | 11 +- docs/html/sdk/android-3.0.jd | 9 +- 9 files changed, 737 insertions(+), 432 deletions(-) diff --git a/core/java/android/widget/SearchView.java b/core/java/android/widget/SearchView.java index f051b770ee0d..0a0dec9cd783 100644 --- a/core/java/android/widget/SearchView.java +++ b/core/java/android/widget/SearchView.java @@ -54,18 +54,16 @@ import android.widget.TextView.OnEditorActionListener; 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 - * 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. * - *

- * XML attributes - *

- * See {@link android.R.styleable#SearchView SearchView Attributes}, - * {@link android.R.styleable#View View Attributes} + *

For more information, see the Search + * documentation.

* * @attr ref android.R.styleable#SearchView_iconifiedByDefault * @attr ref android.R.styleable#SearchView_maxWidth + * @attr ref android.R.styleable#SearchView_queryHint */ public class SearchView extends LinearLayout { @@ -374,6 +372,8 @@ public class SearchView extends LinearLayout { * in the SearchableInfo. * * @param hint the hint text to display + * + * @attr ref android.R.styleable#SearchView_queryHint */ public void setQueryHint(CharSequence hint) { mQueryHint = hint; @@ -389,6 +389,8 @@ public class SearchView extends LinearLayout { *

The default value is true.

* * @param iconified whether the search field should be iconified by default + * + * @attr ref android.R.styleable#SearchView_iconifiedByDefault */ public void setIconifiedByDefault(boolean iconified) { if (mIconifiedByDefault == iconified) return; diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 24e4648bcb48..1259f5b8c656 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -310,7 +310,7 @@ Search @@ -142,7 +140,7 @@ to the {@code <searchable>} element in your searchable configuration file. </searchable> -

You might need some additional attributes, depending on the type of Intent you attach +

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 attributes are discussed in the following sections.

@@ -155,11 +153,11 @@ providers that's covered in the Content Provider developer 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 -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.

-

When the user starts typing into the search dialog, the Search Manager queries your content -provider for suggestions by calling {@link +

When the user starts typing into the search dialog or search widget, the system queries +your content provider for suggestions by calling {@link android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} each time a letter is typed. In your implementation of {@link 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:

Handling the suggestion query
-
How the Search Manager sends requests to your content provider and how to handle them
+
How the system sends requests to your content provider and how to handle them
Building a suggestion table
-
How to define the columns that the Search Manager expects in the {@link +
How to define the columns that the system expects in the {@link android.database.Cursor} returned with each query

Handling the suggestion query

-

When the Search Manager requests suggestions from your content provider, it calls your content +

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) query()} method. You must implement this method to search your suggestion data and return a {@link android.database.Cursor} pointing to the suggestions you deem relevant.

-

Here's a summary of the parameters that the Search Manager passes to your {@link +

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 (listed in order):

@@ -196,7 +194,7 @@ android.content.ContentProvider#query(Uri,String[],String,String[],String) query content://your.authority/optional.suggest.path/{@link android.app.SearchManager#SUGGEST_URI_PATH_QUERY} -

The default behavior is for Search Manager to pass this URI and append it with the query text. +

The default behavior is for system to pass this URI and append it with the query text. For example:

 content://your.authority/optional.suggest.path/{@link
@@ -233,7 +231,7 @@ about using this to get the query below.
   
Always null

 
 
-
The Search Manager can send you the search query text in two ways. The
+
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
 URI passed in the {@code uri} parameter. However, if you include a selection value in your
 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();
-

This returns the last segment of the {@link android.net.Uri}, which is the query text entered in -the search dialog.

+

This returns the last segment of the {@link android.net.Uri}, which is the query text entered +by the user.

@@ -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 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 -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 selection string as the {@code selection} parameter and the search query as the first element in the {@code selectionArgs} array.

@@ -278,15 +276,15 @@ create a full-text search statement:

android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" - android:searchSuggestIntentAction="android.Intent.action.VIEW" + android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestSelection="word MATCH ?"> </searchable>

With this configuration, your {@link android.content.ContentProvider#query(Uri,String[],String,String[],String) query()} method -delivers the {@code selection} parameter as "word MATCH ?" and the {@code selectionArgs} -parameter as whatever the user entered in the search dialog. When you pass these to an SQLite +delivers the {@code selection} parameter as {@code "word MATCH ?"} and the {@code selectionArgs} +parameter as the search query. When you pass these to an SQLite {@link android.database.sqlite.SQLiteDatabase#query(String,String[],String,String[],String,String, String) query()} method, as their respective arguments, they are synthesized together (the 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.

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 Declaring an Intent for -suggestions.

+Suggestions.

Tip: If you don't want to define a selection clause in the {@code android:searchSuggestSelection} attribute, but would still like to receive the query @@ -317,7 +315,7 @@ handle it.

Creating a Cursor without a table

If your search suggestions are not stored in a table format (such as an SQLite table) using 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} 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 @@ -326,18 +324,18 @@ android.content.ContentProvider#query(Uri,String[],String,String[],String) query -

When you return suggestions to the Search Manager with a {@link android.database.Cursor}, the -Search Manager expects specific columns in each row. So, regardless of whether you +

When you return suggestions to the system with a {@link android.database.Cursor}, the +system expects specific columns in each row. So, regardless of whether you decide to store 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 -present them with a {@link android.database.Cursor}. The Search -Manager understands several columns, but only two are required:

+present them with a {@link android.database.Cursor}. The system understands several columns, but +only two are required:

{@link android.provider.BaseColumns#_ID}
-
A unique integer row ID for each suggestion. The search dialog requires this in order -to present suggestions in a ListView.
+
A unique integer row ID for each suggestion. The system requires this in order +to present suggestions in a {@link android.widget.ListView}.
{@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}
The string that is presented as a suggestion.
@@ -359,35 +357,35 @@ This can be null or zero to indicate no icon in this row. 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.
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION}
-
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 +
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 provided, the action is taken from the {@code android:searchSuggestIntentAction} field in your searchable configuration. If your action is the same for all suggestions, it is more efficient to specify the action using {@code android:searchSuggestIntentAction} and omit this column.
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA}
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 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 android:searchSuggestIntentData} and omit this column.
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID}
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 by the {@code android:searchSuggestIntentData} attribute in the searchable configuration has already been set to an appropriate base string.
{@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_EXTRA_DATA}
Arbitrary data. If this column exists and contains a value at a given row, this is the -extra 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 -included as an extra in the Intent's {@link android.app.SearchManager#EXTRA_DATA_KEY} key.
+extra 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 +included as an extra in the intent's {@link android.app.SearchManager#EXTRA_DATA_KEY} key.
{@link android.app.SearchManager#SUGGEST_COLUMN_QUERY}
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.content.Intent#ACTION_SEARCH}, optional otherwise.
{@link android.app.SearchManager#SUGGEST_COLUMN_SHORTCUT_ID}
@@ -410,22 +408,22 @@ while the shortcut of this suggestion is being refreshed in Quick Search Box.Declaring an Intent for suggestions +

Declaring an Intent for Suggestions

-

When the user selects a suggestion from the list that appears below the search dialog, the Search -Manager sends a custom {@link android.content.Intent} to your searchable Activity. You must define -the action and data for the Intent.

+

When the user selects a suggestion from the list that appears below the search dialog or widget, +the system sends a custom {@link android.content.Intent} to your searchable activity. You +must define the action and data for the intent.

-

Declaring the Intent action

+

Declaring the intent action

-

The most common Intent action for a custom suggestion is {@link +

The most common intent action for a custom suggestion is {@link 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 -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.

-

Depending on whether you want all suggestions to use the same Intent action, you +

Depending on whether you want all suggestions to use the same intent action, you can define the action in two ways:

    @@ -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 {@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 -Intent provided in the {@code android:searchSuggestIntentAction} attribute is used.

    +intent provided in the {@code android:searchSuggestIntentAction} attribute is used.

    Note: If you do not include the {@code android:searchSuggestIntentAction} attribute in your searchable configuration, then you must include a value in the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} -column for every suggestion, or the Intent will fail.

    +column for every suggestion, or the intent will fail.

    -

    Declaring Intent data

    +

    Declaring intent data

    -

    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 -data in order for your Activity to identify which suggestion was selected. Specifically, +

    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 +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 -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 android.content.Intent#getDataString()}.

    -

    You can define the data included with the Intent in two ways:

    +

    You can define the data included with the intent in two ways:

    1. Define the data for each suggestion inside the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column of your suggestions table. -

      Provide all necessary data information for each Intent in the suggestions table by including the +

      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 -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 android.content.Intent#getData()} or {@link android.content.Intent#getDataString()}.

      @@ -498,7 +496,7 @@ projection map of column names to aliases.

    2. 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 android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID} column of your suggestions table, respectively. @@ -512,14 +510,14 @@ android:searchSuggestIntentData} attribute of your searchable configuration. For android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" - android:searchSuggestIntentAction="android.Intent.action.VIEW" + android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestIntentData="content://com.example/datatable" > </searchable>

      Then include the final path for each suggestion (the unique part) in the {@link 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 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 @@ -530,20 +528,20 @@ android.content.Intent#getData()}.

      Add more data

      -

      If you need to express even more information with your Intent, you can add another table column, +

      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 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.

      +android.app.SearchManager#EXTRA_DATA_KEY} of the intent's extra Bundle.

      Handling the Intent

      -

      Now that your search dialog provides custom search suggestions with custom Intents, you -need your searchable Activity to handle these Intents when the user selects a +

      Now that you provide custom search suggestions with custom intents, you +need your searchable activity to handle these intents when the user selects a suggestion. This is in addition to handling the {@link -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 +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 android.app.Activity#onCreate(Bundle) onCreate()} callback:

      @@ -559,25 +557,25 @@ if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
 }
      -

      In this example, the Intent action is {@link +

      In this example, the intent action is {@link 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 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.

      -

      Note: You do not need to add an Intent filter to your -Android manifest file for the Intent action you defined with the {@code +

      Note: You do not need to add an intent filter to your +Android manifest file for the intent action you defined with the {@code android:searchSuggestIntentAction} attribute or {@link -android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column. The Search Manager opens your -searchable Activity by name to deliver the suggestion's Intent, so the Activity does not need to +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 declare the accepted action.

      Rewriting the query text

      -

      If the user navigates through the suggestions list using the directional controls (trackball or -d-pad), the text in the search dialog won't change, by default. However, you can temporarily rewrite -the user's query text as it appears in the text box with +

      If the user navigates through the suggestions list using the directional controls (such +as with a trackball or d-pad), the query text does not update, by default. However, you +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 being suggested (if appropriate) and then select the search box and edit the query before dispatching it as a search.

      @@ -654,7 +652,7 @@ android:searchSettingsDescription} attribute to your searchable configuration. F android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" - android:searchSuggestIntentAction="android.Intent.action.VIEW" + android:searchSuggestIntentAction="android.intent.action.VIEW" android:includeInGlobalSearch="true" android:searchSettingsDescription="@string/search_description" > </searchable> @@ -676,7 +674,7 @@ them how to enable search suggestions for Quick Search Box.

      Managing Quick Search Box suggestion shortcuts

      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.

      By default, this is enabled for all suggestions retrieved by Quick Search Box, but if your diff --git a/docs/html/guide/topics/search/adding-recent-query-suggestions.jd b/docs/html/guide/topics/search/adding-recent-query-suggestions.jd index cb063a13fcac..2c9a4617d8e4 100644 --- a/docs/html/guide/topics/search/adding-recent-query-suggestions.jd +++ b/docs/html/guide/topics/search/adding-recent-query-suggestions.jd @@ -28,13 +28,15 @@ Configuration

      3. -

      When using the Android search dialog, you can provide search suggestions based on recent search +

      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 suggestion once he or she begins typing the same query. Figure 1 shows an example of a search dialog with recent query suggestions.

      -

      Before you begin, you need to implement the search dialog for basic searches in your application. -If you haven't, see Using the Android Search Dialog.

      +

      Before you begin, you need to implement the search dialog or a search widget for basic searches +in your application. +If you haven't, see Creating a Search Interface.

      @@ -47,16 +49,16 @@ suggestions.

      Recent query suggestions are simply saved searches. When the user selects one of -the suggestions, your searchable Activity receives a {@link -android.content.Intent#ACTION_SEARCH} Intent with the suggestion as the search query, which your -searchable Activity already handles (as described in Using the Android -Search Dialog).

      +the suggestions, your searchable activity receives a {@link +android.content.Intent#ACTION_SEARCH} intent with the suggestion as the search query, which your +searchable activity already handles (as described in Creating a Search +Interface).

      To provide recent queries suggestions, you need to:

        -
      • Implement a searchable Activity, using the Android Search Dialog.
        • +
      • Implement a searchable activity, as described in Creating a Search Interface.
      • Create a content provider that extends {@link android.content.SearchRecentSuggestionsProvider} and declare it in your application manifest.
      • Modify the searchable configuration with information about the content provider that @@ -64,20 +66,19 @@ provides search suggestions.
      • Save queries to your content provider each time a search is executed.
      -

      Just as the Search Manager 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 -retrieved.

      +

      Just as the Android system displays the search dialog, it also displays the +search suggestions below the dialog or search widget. All you need to do is provide a source from +which the system can retrieve suggestions.

      -

      When the Search Manager identifies that your Activity is searchable and provides search -suggestions, the following procedure takes place as soon as the user types into the search -dialog:

      +

      When the system identifies that your activity is searchable and provides search +suggestions, the following procedure takes place as soon as the user begins typing a query:

        -
      1. Search Manager takes the search query text (whatever has been typed so far) and performs a +
      2. 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.
      3. Your content provider returns a {@link android.database.Cursor} that points to all suggestions that match the search query text.
        4. -
      4. Search Manager displays the list of suggestions provided by the Cursor.
        5. +
      5. The system displays the list of suggestions provided by the Cursor.

      Once the recent query suggestions are displayed, the following might happen:

      @@ -86,10 +87,10 @@ suggestions that match the search query text.
    3. If the user types another key, or changes the query in any way, the aforementioned steps are repeated and the suggestion list is updated.
    4. 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} -Intent.
      5. +to your searchable activity using the normal {@link android.content.Intent#ACTION_SEARCH} +intent.
    5. 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.
      6. @@ -151,7 +152,7 @@ searchable configuration). For example:

      Modifying the Searchable Configuration

      -

      To configure your search dialog to use your suggestions provider, you need to add +

      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 <searchable>} element in your searchable configuration file. For example:

      @@ -179,12 +180,12 @@ automatically replaced by the query text entered by the user).

      Saving Queries

      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.provider.SearchRecentSuggestions} and call {@link 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 Activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:

      +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:

       @Override
@@ -192,10 +193,10 @@ public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.main);
 
-    Intent Intent  = getIntent();
+    Intent intent  = getIntent();
 
-    if (Intent.ACTION_SEARCH.equals(Intent .getAction())) {
-        String query = Intent .getStringExtra(SearchManager.QUERY);
+    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
+        String query = intent.getStringExtra(SearchManager.QUERY);
         SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                 MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
         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
 two-line mode for the search suggestions with {@link
 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.
      
 
 
diff --git a/docs/html/guide/topics/search/index.jd b/docs/html/guide/topics/search/index.jd
index f563715690d5..7ac5ff1455bb 100644
--- a/docs/html/guide/topics/search/index.jd
+++ b/docs/html/guide/topics/search/index.jd
@@ -5,7 +5,7 @@ page.title=Search
 
      
 
      Topics
      
 
        
-
      1. Using the Android Search Dialog
        2. 
+
      2. Creating a Search Interface
        3. 
 
      3. Adding Recent Query Suggestions
        4. 
 
      4. Adding Custom Suggestions
        5. 
 
      
@@ -24,9 +24,8 @@ Dictionary
 
 
      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
-the Internet. The search experience should be seamless and consistent across the entire
-system, which is why Android provides a search framework to help you provide users with
-a familiar search dialog and a great search experience.
      
+the Internet. To help create a consistent search experience for users, Android provides a
+search framework that helps you implement search for your application.
      
 
 
      
 
@@ -34,16 +33,14 @@ a familiar search dialog and a great search experience.
      
 search suggestions.
      
 
      
 
-
      Android's search framework provides a user interface in which users can perform a search and
-an interaction layer that communicates with your application, so you don't have to build
-your own search Activity. Instead, a search dialog appears at the top of the screen at the user's
-command without interrupting the current Activity.
      
+
      The search framework offers two modes of search input: a search dialog at the top of the
+screen or a search widget ({@link android.widget.SearchView}) that you can embed in your activity
+layout. In either case, the Android system will assist your search implementation by
+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.
      
 
-
      The search framework manages the life of the search dialog. When users execute a search, the
-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.
      
-
-
      Once your application is set up to use the search dialog, you can:
      
+
      Once you've set up either the search dialog or the search widget, you can:
      
 
 
        
 
      • Enable voice search
        • 
@@ -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}
 APIs to perform searches.
        
 
-
        The following documents show you how to use the search dialog in your application:
        
+
        The following documents show you how to use Android's framework to implement search:
        
 
 
        
-  
        Using the Android Search Dialog
        
-  
        How to set up your application to use the search dialog. 
        
+  
        Creating a Search Interface
        
+  
        How to set up your application to use the search dialog or search widget. 
        
   
        Adding Recent Query
 Suggestions
        
-  
        How to show suggestions based on queries previously used in the search dialog.
        
+  
        How to provide suggestions based on queries previously used.
        
   
        Adding Custom Suggestions
        
-  
        How to show suggestions based on custom data from your application and offer your suggestions
+  
        How to provide suggestions based on custom data from your application and also offer them
 in the system-wide Quick Search Box.
        
   
        Searchable Configuration
        
-  
        A reference for the searchable configuration file (though the other
+  
        A reference document for the searchable configuration file (though the other
 documents also discuss the configuration file in terms of specific behaviors).
        
 
        
 
@@ -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
 very carefully and erase it as soon as possible.
        
 
-
      • Provide the user with a way to clear their search history.
+
      • Provide users with a way to clear their search history.
 
        The search framework helps your application provide context-specific suggestions while the user
 types. Sometimes these
 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
-instance, if they share their phone with a friend. If your application provides suggestions that can
-reveal previous activities, you should implement the ability for the user to clear the search
-history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply call the
-{@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing
-custom suggestions, you'll need to provide a similar "clear history" method in your provider that
-the user can execute.
        
+instance, if the user shares the device with a friend. If your application provides suggestions that
+can reveal previous search activities, you should implement the ability for the user to clear the
+search history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply
+call the {@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are
+implementing custom suggestions, you'll need to provide a similar "clear history" method in your
+content provider that the user can execute.
        
 
        • 
 
      
 
diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd
index 6699fe17291c..af6c8f2a82da 100644
--- a/docs/html/guide/topics/search/search-dialog.jd
+++ b/docs/html/guide/topics/search/search-dialog.jd
@@ -1,38 +1,61 @@
-page.title=Using the Android Search Dialog
+page.title=Creating a Search Interface
 parent.title=Search
 parent.link=index.html
 @jd:body
 
 
      
 
      
+
+  
      Quickview
      
+  
        
+    
      • The Android system sends search queries from the search dialog or widget to an activity you
+specify to perform searches and present results
        • 
+    
      • You can put the search widget in the Action Bar, as an "action view," for quick
+access
        • 
+  
      
+
+
 
      In this document
      
 
        
 
      1. The Basics
        2. 
 
      2. Creating a Searchable Configuration
        3. 
 
      3. Creating a Searchable Activity
   
          
-    
        1. Declaring a searchable Activity
          2. 
+    
        2. Declaring a searchable activity
          3. 
+    
        3. Enabling the search dialog and search widget
          4. 
     
        4. Performing a search
          5. 
   
        
 
        4. 
-
      4. Invoking the Search Dialog
+
      5. Using the Search Dialog
+  
          
+    
        1. The impact of the search dialog on your activity lifecycle
          2. 
+    
        2. Passing search context data
          3. 
+  
        
+
        6. 
+
      6. Using the Search Widget
   
          
-    
        1. The impact of the search dialog on your Activity life-cycle
          2. 
+    
        2. Configuring the search widget
          3. 
+    
        3. Other search widget features
          4. 
   
        
 
        7. 
-
      7. Passing Search Context Data
        8. 
 
      8. Adding Voice Search
        9. 
+
      9. Adding Search Suggestions
        10. 
 
      
 
 
      Key classes
      
 
        
 
      1. {@link android.app.SearchManager}
        2. 
+
      2. {@link android.widget.SearchView}
        3. 
 
      
 
 
      Related samples
      
 
        
 
      1. Searchable
 Dictionary
        2. 
+
      2. SearchView
+    in the Action Bar
        3. 
+
      3. SearchView
+    filter mode
        4. 
 
      
 
 
      Downloads
      
@@ -50,16 +73,24 @@ Dictionary
 
      
 
      
 
-
      When you want to implement search in your application, the last thing you should have to worry
-about is where to put the search box. When you implement search with the Android search framework,
-you don't have to. When the user invokes search, a search dialog appears at the top of the screen
-with your application icon to the left of the search box. When the user executes the search, your
-application receives the query so it can search your application's data. An example of the search
-dialog is shown in figure 1.
      
+
      When you're ready to add search functionality to your application, Android helps you implement
+the user interface with either a search dialog that appears at the top of the activity window or a
+search widget that you can insert in your layout. Both the search dialog and the widget can deliver
+the user's search query to a specific activity in your application. This way, the user can initiate
+a search from any activity where the search dialog or widget is available, and the system starts the
+appropriate activity to perform the search and present results.
      
+
+
      Other features available for the search dialog and widget include:
      
 
-
      This guide shows you how to set up your application to provide search in the search
-dialog. When you use the search dialog, you provide a standardized search
-experience and can add features such as voice search and search suggestions.
      
+
        
+  
      • Voice search
        • 
+  
      • Search suggestions based on recent queries
        • 
+  
      • Search suggestions that match actual results in your application data
        • 
+
      
+
+
      This guide shows you how to set up your application to provide a search interface
+that's assisted by the Android system to deliver search queries, using either the
+search dialog or the search widget.
      
 
 
 
      The Basics
      
@@ -69,40 +100,78 @@ experience and can add features such as voice search and search suggestions.
      
 
      Figure 1. Screenshot of an application's search dialog.
      
 
      
 
-
      The Android search framework manages the search dialog for your application. You never need
-to draw it or worry about where it is, and your Activity is not interrupted when the search dialog
-appears. The Search Manager ({@link android.app.SearchManager}) is the component that does this work
-for you. It manages the life of the search dialog and sends your application the user's search
-query.
      
-
-
      When the user executes a search, the Search Manager creates an {@link android.content.Intent} to
-pass the search query to the Activity that you've declared to handle searches. Basically, all you
-need is an Activity that receives the search Intent, performs the search, and presents the results.
-Specifically, you need the following:
      
-
-
      
-  
      A searchable configuration
      
-  
      An XML file that configures the search dialog and includes settings for features such as voice
-search, search suggestion, and the hint text.
      
-  
      A searchable Activity
      
-  
      The {@link android.app.Activity} that receives the search query, then searches your data and
-displays the search results.
      
-  
      A mechanism by which the user can invoke search
      
-  
      The device search key invokes the search dialog, by default. However, a dedicated search key
-is not guaranteed on all devices, so provide another means by which the user can invoke a search,
-such as a search button in the Options Menu or elsewhere in the Activity UI.
      
-
      
-
+
      Before you begin, you should decide whether you'll implement your search interface using the
+search dialog or the search widget. Both provide the same search features, but in slightly different
+ways:
      
+
+
        
+  
      • The search dialog is a UI component that's controlled by the Android system.
+When activated by the user, the search dialog appears at the top of the activity, as shown in figure
+1.
+    
        The Android system controls all events in the search dialog. When the user
+submits a query, the system delivers the query to the activity that you specify to
+handle searches. The dialog can also provide search suggestions while the user types.
        • 
+
+  
      • The search widget is an instance of {@link android.widget.SearchView} that
+you can place anywhere in your layout. By default, the search widget behaves like a standard {@link
+android.widget.EditText} widget and doesn't do anything, but you can configure it so that the
+Android system handles all input events, delivers queries to the appropriate activity, and provides
+search suggestions (just like the search dialog). However, the search widget is available only in
+Android 3.0 (API Level 11) and higher.
+
+
        Note: If you want, you can handle all user input into the
+search widget yourself, using various callback methods and listeners. This document, however,
+focuses on how to integrate the search widget with the system for an assisted search
+implementation. If you want to handle all user input yourself, read the reference documentation for
+{@link android.widget.SearchView} and its nested interfaces. 
        • 
+
      
+
+
      When the user executes a search from the search dialog or a search widget, the system creates an
+{@link android.content.Intent} and stores the user query in it. The system then starts the activity
+that you've declared to handle searches (the "searchable activity") and delivers it the intent. To
+set up your application for this kind of assisted search, you need the following:
      
+
+
        
+  
      • A searchable configuration
+  
        An XML file that configures some settings for the search dialog or widget. It includes settings
+for features such as voice search, search suggestion, and hint text for the search box.
        • 
+  
      • A searchable activity
+  
        The {@link android.app.Activity} that receives the search query, searches your
+data, and displays the search results.
        • 
+  
      • A search interface, provided by either:
+    
          
+      
        • The search dialog
+        
          By default, the search dialog is hidden, but appears at the top of the screen when the 
+user presses the device SEARCH button (when available) or another button in your user interface.
          
+      
          • 
+      
        • Or, a {@link android.widget.SearchView} widget
+        
          Using the search widget allows you to put the search box anywhere in your activity.
+Instead of putting it in your activity layout, however, it's usually more convenient for users as an
+action view in the Action Bar.
          
+      
          • 
+    
        
+  
        • 
+
      
+
+
      The rest of this document shows you how to create the searchable configuration, searchable
+activity, and implement a search interface with either the search dialog or search widget.
      
 
 
 
      Creating a Searchable Configuration
      
 
-
      The searchable configuration is an XML file that defines several settings for the search
-dialog in your application. This file is traditionally named {@code searchable.xml} and must be
-saved in the {@code res/xml/} project directory.
      
+
      The first thing you need is an XML file called the searchable configuration. It configures
+certain UI aspects of the search dialog or widget and defines how features such as suggestions and
+voice search behave. This file is traditionally named {@code searchable.xml} and must be saved in
+the {@code res/xml/} project directory.
      
+
+
      Note: The system uses this file to instantiate a {@link
+android.app.SearchableInfo} object, but you cannot create this object yourself at
+runtime—you must declare the searchable configuration in XML.
      
 
-
      The file must consist of the {@code <searchable>} element as the root node and specify one
-or more attributes that configure your search dialog. For example:
      
+
      The searchable configuration file must include the {@code
+<searchable>} element as the root node and specify one
+or more attributes. For example:
      
 
 
       <?xml version="1.0" encoding="utf-8"?>
@@ -112,51 +181,61 @@ or more attributes that configure your search dialog. For example:
      
 </searchable>
 
      
 
-
      The {@code android:label} attribute is the only required attribute and points to a string
-resource, which should be the same as the application name. This label isn't actually visible to the
-user until you enable suggestions for Quick Search Box, at which point, this label is visible in the
-list of Searchable items in the system Settings.
      
+
      The {@code android:label} attribute is the only required attribute. It points to a string
+resource, which should be the application name. This label isn't actually visible to the
+user until you enable search suggestions for Quick Search Box. At that point, this label is visible
+in the list of Searchable items in the system Settings.
      
 
 
      Though it's not required, we recommend that you always include the {@code android:hint}
-attribute, which provides a hint string in the search dialog's text box before the user
-enters their query. The hint is important because it provides important clues to users about what
+attribute, which provides a hint string in the search box before users
+enters a query. The hint is important because it provides important clues to users about what
 they can search.
      
 
 
      Tip: For consistency among other
 Android applications, you should format the string for {@code android:hint} as "Search
-<content-or-product>". For example, "Search songs and artists" or "Search
+<content-or-product>". For example, "Search songs and artists" or "Search
 YouTube".
      
 
-
      The {@code <searchable>} element accepts several other attributes. Most attributes apply
-only when configuring features such as search suggestions and voice search.
      
-
-
      For more details about the searchable configuration file, see the Searchable Configuration
-reference.
      
+
      The {@code
+<searchable>} element accepts several other attributes. However, you don't need
+most attributes until you add features such as search suggestions
+and voice search. For detailed information about the searchable
+configuration file, see the Searchable Configuration reference
+document.
      
 
 
 
 
      Creating a Searchable Activity
      
 
-
      When the user executes a search from the search dialog, the Search Manager takes the query
-and sends it to your searchable {@link android.app.Activity} in the {@link
-android.content.Intent#ACTION_SEARCH} {@link android.content.Intent}. Your searchable Activity
-then searches your data using the query and presents the results to the user.
      
+
      A searchable activity is the {@link android.app.Activity} in your application that performs
+searches based on a query string and presents the search results.
      
+
+
      When the user executes a search in the search dialog or widget, the system starts your
+searchable activity and delivers it the search query in an {@link
+android.content.Intent} with the  {@link android.content.Intent#ACTION_SEARCH} action. Your
+searchable activity retrieves the query from the intent's {@link android.app.SearchManager#QUERY
+QUERY} extra, then searches your data and presents the results.
      
 
-
      In order for the Search Manager to know where to deliver the search query, you must declare your
-searchable Activity in the Android manifest file.
      
+
      Because you may include the search dialog or widget in any other activity in your application,
+the system must know which activity is your searchable activity, so it can properly deliver the
+search query. So, you must first declare your searchable activity in the Android manifest file.
      
 
 
-
      Declaring a searchable Activity
      
+
      Declaring a searchable activity
      
 
-
      If you don't have one already, create an {@link android.app.Activity} that performs
-searches and present search results. To set up this Activity as your searchable Activity:
      
+
      If you don't have one already, create an {@link android.app.Activity} that will perform
+searches and present results. You don't need to implement the search functionality yet—just
+create an activity that you can declare in the manifest. Inside the manifest's {@code <activity>}
+element:
      
 
        
-  
      1. Declare the Activity to accept the {@link android.content.Intent#ACTION_SEARCH} {@link
-android.content.Intent}, in an {@code <intent-filter>}
+  
      2. Declare the activity to accept the {@link android.content.Intent#ACTION_SEARCH} intent, in an
+{@code
+<intent-filter>}
 element.
        3. 
-  
      3. Apply the searchable configuration, in a Specify the searchable configuration to use, in a {@code <meta-data>}
 element.
        4. 
 
      
@@ -165,7 +244,7 @@ element.
 
 
       <application ... >
-    <activity android:name=".MySearchableActivity" >
+    <activity android:name=".SearchableActivity" >
         <intent-filter>
             <action android:name="android.intent.action.SEARCH" />
         </intent-filter>
@@ -181,71 +260,22 @@ value of {@code "android.app.searchable"} and the {@code android:resource} attri
 reference to the searchable configuration file (in this example, it
 refers to the {@code res/xml/searchable.xml} file).
      
 
-
      Note: The {@code <intent-filter>} does not need a Note: The {@code
+<intent-filter>} does not need a {@code <category>} with the
-{@code DEFAULT} value, because the Search Manager delivers the {@link
-android.content.Intent#ACTION_SEARCH} Intent explicitly to your searchable Activity by name.
      
-
-
      The search dialog is not, by default, available from every Activity of your
-application. Rather, the search dialog is presented to users only when they
-invoke search from a searchable context of your application. A searchable context is any Activity
-for which you have
-declared searchable meta-data in the manifest file. For example, the searchable Activity itself
-(declared in the manifest snippet above) is
-a searchable context because it includes meta-data that defines the
-searchable configuration. Any other Activity in your application is not a searchable context, by
-default, and thus, does not reveal the search dialog. However, you probably do want the search
-dialog available from your other activities (and to launch the searchable Activity when the user
-executes a search). You can do exactly that.
      
-
-
      If you want all of your activities to provide the search dialog, add another {@code
-<meta-data>} element inside the {@code
-<application>} element. Use this element to declare the existing searchable Activity as the
-default searchable Activity. For example:
      
-
-
      -<application ... >
-    <activity android:name=".MySearchableActivity" >
-        <intent-filter>
-            <action android:name="android.intent.action.SEARCH" />
-        </intent-filter>
-        <meta-data android:name="android.app.searchable"
-                   android:resource="@xml/searchable"/>
-    </activity>
-    <activity android:name=".AnotherActivity" ... >
-    </activity>
-    <!-- declare the default searchable Activity for the whole app -->
-    <meta-data android:name="android.app.default_searchable"
-               android:value=".MySearchableActivity" />
-    ...
-</application>
-
      
+{@code DEFAULT} value (which you usually see in {@code <activity>} elements),
+because the system delivers the {@link android.content.Intent#ACTION_SEARCH} intent explicitly to
+your searchable activity, using its component name.
      
 
-
      The {@code <meta-data>} element with the {@code android:name} attribute value of
-{@code "android.app.default_searchable"} specifies a default searchable Activity for the context in
-which it is placed (which, in this case, is the entire application). The searchable Activity to
-use is specified with the {@code android:value} attribute. All other activities in the
-application, such as {@code AnotherActivity}, are now considered a searchable context and can invoke
-the search dialog. When a search is executed, {@code MySearchableActivity} is launched to handle
-the search query.
      
-
-
      You can also control which activities provide search at a more granular level.
-To specify only an individual Activity as a searchable context, place the {@code
-<meta-data>} with the {@code
-"android.app.default_searchable"} name inside the respective {@code <activity>}
-element (rather than inside the {@code <application>} element). While uncommon, you
-can also create more than one searchable Activity and provide each one in different contexts of your
-application, either by declaring a different searchable Activity in each {@code <activity>}
-element, or by declaring a default searchable Activity for the entire application and then
-overriding it with a {@code <meta-data>} element inside certain activities. (You might do
-this if you want to search different sets of data that cannot be handled by the same
-searchable Activity, depending on the currently open Activity.)
      
 
 
 
      Performing a search
      
 
-
      Once you have declared your searchable Activity, performing a search for the user involves
-three steps:
      
+
      Once you have declared your searchable activity in the manifest, performing a search in your
+searchable activity involves three steps:
      
+
 
        
   
      1. Receiving the query
        2. 
   
      2. Searching your data
        3. 
@@ -253,20 +283,19 @@ three steps:
        
 
      
 
 
      Traditionally, your search results should be presented in a {@link android.widget.ListView}, so
-you might want your searchable Activity to extend {@link android.app.ListActivity}, which
-provides easy access to {@link android.widget.ListView} APIs. (See the List View Tutorial for a simple
-{@link android.app.ListActivity} sample.)
      
+you might want your searchable activity to extend {@link android.app.ListActivity}. It includes
+a default layout with a single {@link android.widget.ListView} and provides several
+convenience methods for working with the {@link android.widget.ListView}.
      
 
 
 
      Receiving the query
      
 
-
      When a user executes a search from the search dialog, the Search Manager sends the {@link
-android.content.Intent#ACTION_SEARCH} {@link android.content.Intent} to your searchable Activity.
-This Intent carries the search query in the
+
      When a user executes a search from the search dialog or widget, the system starts your
+searchable activity and sends it a {@link android.content.Intent#ACTION_SEARCH} intent. This intent
+carries the search query in the
 {@link android.app.SearchManager#QUERY QUERY} string extra. You must check for
-this Intent when the Activity starts and extract the string. For example, here's how you can get the
-query when your Activity starts:
      
+this intent when the activity starts and extract the string. For example, here's how you can get the
+search query when your searchable activity starts:
      
 
 
       @Override
@@ -274,8 +303,8 @@ public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.search);
 
+    // Get the intent, verify the action and get the query
     Intent intent = getIntent();
-
     if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
       String query = intent.getStringExtra(SearchManager.QUERY);
       doMySearch(query);
@@ -284,7 +313,7 @@ public void onCreate(Bundle savedInstanceState) {
 
      
 
 
      The {@link android.app.SearchManager#QUERY QUERY} string is always included with
-the {@link android.content.Intent#ACTION_SEARCH} Intent. In this example, the query is
+the {@link android.content.Intent#ACTION_SEARCH} intent. In this example, the query is
 retrieved and passed to a local {@code doMySearch()} method where the actual search operation
 is done.
      
 
@@ -294,12 +323,13 @@ is done.
      
 
      The process of storing and searching your data is unique to your application.
 You can store and search your data in many ways, but this guide does not show you how to store your
 data and search it. Storing and searching your data is something you should carefully consider in
-terms of your needs and your data. However, here are some tips you might be able to apply:
      
+terms of your needs and your data format. However, here are some tips you might be able to
+apply:
      
 
   
        
     
      • If your data is stored in a SQLite database on the device, performing a full-text search
-(using FTS3, rather than a LIKE query) can provide a more robust search across text data and can
-produce results significantly faster. See sqlite.org
+(using FTS3, rather than a {@code LIKE} query) can provide a more robust search across text data and
+can produce results significantly faster. See sqlite.org
 for information about FTS3 and the {@link android.database.sqlite.SQLiteDatabase} class for
 information about SQLite on Android. Also look at the Searchable Dictionary sample
@@ -307,43 +337,45 @@ application to see a complete SQLite implementation that performs searches with
     
      • If your data is stored online, then the perceived search performance might be
 inhibited by the user's data connection. You might want to display a spinning progress wheel until
 your search returns. See {@link android.net} for a reference of network APIs and Creating a Progress Dialog to see
-how you can display a progress wheel.
        • 
+href="{@docRoot}guide/topics/ui/dialogs.html#ProgressDialog">Creating a Progress Dialog
+for information about how to display a progress wheel.
   
      
 
 
 
      
 
      
 
      About Adapters
      
-
      An Adapter binds individual items from a set of data into individual {@link
-android.view.View} objects. When the Adapter
-is applied to a {@link android.widget.ListView}, the Views are injected as individual items of the
-list. {@link
-android.widget.Adapter} is simply an interface, so implementations such as {@link
+
      An {@link android.widget.Adapter} binds each item from a set of data into a
+{@link android.view.View} object. When the {@link android.widget.Adapter}
+is applied to a {@link android.widget.ListView}, each piece of data is inserted as an individual
+view into the list. {@link
+android.widget.Adapter} is just an interface, so implementations such as {@link
 android.widget.CursorAdapter} (for binding data from a {@link android.database.Cursor}) are needed.
-If none of the existing implementations work for your data, then you should implement your own from
+If none of the existing implementations work for your data, then you can implement your own from
 {@link android.widget.BaseAdapter}. Install the SDK Samples package for API Level 4 to see the
-original version of the Searchable Dictionary, which creates a custom BaseAdapter.
      
+original version of the Searchable Dictionary, which creates a custom adapter to read data from
+a file.
      
 
      
 
      
 
 
      Regardless of where your data lives and how you search it, we recommend that you return search
-results to your searchable Activity with an {@link android.widget.Adapter}. This way, you can easily
+results to your searchable activity with an {@link android.widget.Adapter}. This way, you can easily
 present all the search results in a {@link android.widget.ListView}. If your data comes from a
-SQLite database query, then you can apply your results to a {@link android.widget.ListView}
+SQLite database query, you can apply your results to a {@link android.widget.ListView}
 using a {@link android.widget.CursorAdapter}. If your data comes in some other type of format, then
-you can create an extension of the {@link android.widget.BaseAdapter}.
      
+you can create an extension of {@link android.widget.BaseAdapter}.
      
+
 
 
      Presenting the results
      
 
-
      Presenting your search results is mostly a UI detail that is not handled by the search APIs.
-However, one option is to create your searchable Activity to extend {@link
-android.app.ListActivity} and call {@link
-android.app.ListActivity#setListAdapter(ListAdapter)}, passing it an {@link
+
      As discussed above, the recommended UI for your search results is a {@link
+android.widget.ListView}, so you might want your searchable activity to extend {@link
+android.app.ListActivity}. You can then call {@link
+android.app.ListActivity#setListAdapter(ListAdapter) setListAdapter()}, passing it an {@link
 android.widget.Adapter} that is bound to your data. This injects all the
-results into the Activity {@link android.widget.ListView}.
      
+search results into the activity {@link android.widget.ListView}.
      
 
-
      For more help presenting your results, see the {@link android.app.ListActivity}
+
      For more help presenting your results in a list, see the {@link android.app.ListActivity}
 documentation.
      
 
 
      Also see the Invoking the Search Dialog
 
-
      Once you have a searchable Activity, invoking the search dialog is easy. Many Android
-devices provide a dedicated SEARCH key, which reveals the search dialog when the user presses it
-from a searchable context of your application. However, you should not assume that a SEARCH
-key is available on the user's device and should always provide a search button in your UI that
-invokes search.
      
 
-
      To invoke search from your Activity, call {@link android.app.Activity#onSearchRequested()}.
      
+
      Using the Search Dialog
      
+
+
      
+
      
+  
      Should I use the search dialog or the widget?
      
+  
      The answer depends mostly on whether you are developing for Android 3.0 (API Level 11 or
+higher), because the {@link android.widget.SearchView} widget was introduced in Android 3.0. So,
+if you are developing your application for a version of Android lower than 3.0, the search widget is
+not an option and you should use the search dialog to implement your search interface.
      
+  
      If you are developing for Android 3.0 or higher, then the decision depends more on
+your needs. In most cases, we recommend that you use the search widget as an "action view" in the
+Action Bar. However, it might not be an option for you to put the search
+widget in the Action Bar for some reason (perhaps there's not enough space or you don't use the
+Action Bar). So, you might instead want to put the search widget somewhere in your activity layout.
+And if all else fails, you can still use the search dialog if you prefer to keep the search box
+hidden. In fact, you might want to offer both the dialog and the widget in some cases. For more
+information about the widget, skip to Using the Search Widget.
      
+
      
+
      
+
+
      The search dialog provides a floating search box at the top of the screen, with the application
+icon on the left. The search dialog can provide search suggestions as the user types and, when
+the user executes a search, the system sends the search query to a
+searchable activity that performs the search. However, if you are developing
+your application for devices running Android 3.0, you should consider using the search widget
+instead (see the side box).
      
+
+
      The search dialog is always hidden by default, until the user activates it. If the user's device
+includes a SEARCH button, pressing it will activate the search dialog by default. Your application
+can also activate the search dialog on demand by calling {@link
+android.app.Activity#onSearchRequested onSearchRequested()}. However, neither of these work
+until you enable the search dialog for the activity.
      
+
+
      To enable the search dialog, you must indicate to the system which searchable activity should
+receive search queries from the search dialog, in order to perform searches. For example, in the
+previous section about Creating a Searchable Activity, a
+searchable activity named {@code SearchableActivity} was created. If you want a separate activity,
+named {@code OtherActivity}, to show the search dialog and deliver searches to {@code
+SearchableActivity}, you must declare in the manifest that {@code SearchableActivity} is the
+searchable activity to use for the search dialog in {@code OtherActivity}.
      
+
+
      To declare the searchable activity for an activity's search dialog,
+add a {@code <meta-data>}
+element inside the respective activity's {@code <activity>} element.
+The {@code <meta-data>}
+element must include the {@code android:value} attribute that specifies the searchable activity's
+class name and the {@code android:name} attribute with a value of {@code
+"android.app.default_searchable"}.
      
+
+
      For example, here is the declaration for
+both a searchable activity, {@code SearchableActivity}, and another activity, {@code
+OtherActivity}, which uses {@code SearchableActivity} to perform searches executed from its
+search dialog:
      
+
+
      +<application ... >
+    <!-- this is the searchable activity; it performs searches -->
+    <activity android:name=".SearchableActivity" >
+        <intent-filter>
+            <action android:name="android.intent.action.SEARCH" />
+        </intent-filter>
+        <meta-data android:name="android.app.searchable"
+                   android:resource="@xml/searchable"/>
+    </activity>
+
+    <!-- this activity enables the search dialog to initiate searches
+         in the SearchableActivity -->
+    <activity android:name=".OtherActivity" ... >
+        <!-- enable the search dialog to send searches to SearchableActivity -->
+        <meta-data android:name="android.app.default_searchable"
+                   android:value=".SearchableActivity" />
+    </activity>
+    ...
+</application>
+
      
+
+
      Because the {@code OtherActivity} now includes a {@code <meta-data>}
+element to declare which searchable activity to use for searches, the activity has enabled the
+search dialog.
+While the user is in this activity, the device SEARCH button (if available) and the {@link
+android.app.Activity#onSearchRequested onSearchRequested()} method will activate the search dialog.
+When the user executes the search, the system starts {@code SearchableActivity} and delivers it
+the {@link android.content.Intent#ACTION_SEARCH} intent.
      
+
+
      Note: The searchable activity itself provides the search dialog
+by default, so you don't need to add this declaration to {@code SearchableActivity}.
      
+
+
      If you want every activity in your application to provide the search dialog, insert the above {@code <meta-data>}
+element as a child of the {@code <application>}
+element, instead of each {@code <activity>}. This
+way, every activity inherits the value, provides the search dialog, and delivers searches to
+the same searchable activity. (If you have multiple searchable activities, you can override the
+default searchable activity by placing a different {@code <meta-data>}
+declaration inside individual activities.)
      
+
+
      With the search dialog now enabled for your activities, your application is ready to perform
+searches.
      
+
+
+
      Invoking the search dialog
      
+
+
      As mentioned above, the device SEARCH button and {@link android.app.Activity#onSearchRequested
+onSearchRequested()} method will open the search dialog, as long as the current activity
+has declared the searchable activity to use, as shown in the previous section.
      
+
+
      However, you should not assume that a SEARCH button is available on the user's device. You
+should always provide another search button in your UI that activates the search dialog by calling
+{@link android.app.Activity#onSearchRequested()}.
      
 
-
      For instance, you should provide a menu item in your Options Menu or a button in your UI to
-invoke search with this method. The For instance, you should either provide a menu item in your Options Menu or a button in your
+activity layout that
+activates search by calling {@link android.app.Activity#onSearchRequested()}. The search_icons.zip file includes icons for
-medium and high density screens, which you can use for your search menu item or button (low density
-screens automatically scale-down the hdpi image by one half). 
      
+medium and high density screens, which you can use for your search menu item or button (low-density
+screens scale-down the hdpi image by one half). 
      
 
 
 
-
      You can also enable "type-to-search" functionality, which reveals the search dialog when the
-user starts typing on the keyboard and the keystrokes are inserted into the search dialog. You can
-enable type-to-search in your Activity by calling
+
      You can also enable "type-to-search" functionality, which activates the search dialog when the
+user starts typing on the keyboard—the keystrokes are inserted into the search dialog. You can
+enable type-to-search in your activity by calling
 {@link android.app.Activity#setDefaultKeyMode(int) setDefaultKeyMode}({@link
-android.app.Activity#DEFAULT_KEYS_SEARCH_LOCAL}) during your Activity's
+android.app.Activity#DEFAULT_KEYS_SEARCH_LOCAL}) during your activity's
 {@link android.app.Activity#onCreate(Bundle) onCreate()} method.
      
 
 
-
      The impact of the search dialog on your Activity lifecycle
      
+
      The impact of the search dialog on your activity lifecycle
      
 
 
      The search dialog is a {@link android.app.Dialog} that floats at the top of the
-screen. It does not cause any change in the Activity stack, so when the search dialog appears, no
-lifecycle methods for the currently open Activity (such as {@link
-android.app.Activity#onPause()}) are called. Your Activity just loses input focus as it is given to
-the search dialog.
+screen. It does not cause any change in the activity stack, so when the search dialog appears, no
+lifecycle methods (such as {@link android.app.Activity#onPause()}) are called. Your activity just
+loses input focus, as input focus is given to the search dialog.
 
      
 
-
      If you want to be notified when search is invoked, override the {@link
-android.app.Activity#onSearchRequested()} method. When the system calls this method, you can do any
-work you want to when your Activity looses input focus to the search dialog (such as pause
-animations). Unless you are passing search context data
+
      If you want to be notified when the search dialog is activated, override the {@link
+android.app.Activity#onSearchRequested()} method. When the system calls this method, it is an
+indication that your activity has lost input focus to the search dialog, so you can do any
+work appropriate for the event (such as pause
+a game). Unless you are passing search context data
 (discussed below), you should end the method by calling the super class implementation. For
 example:
      
 
@@ -408,8 +549,8 @@ public boolean onSearchRequested() {
 }
 
      
 
-
      If the user cancels search by pressing the BACK key, the Activity in which search was
-invoked re-gains input focus. You can register to be notified when the search dialog is
+
      If the user cancels search by pressing the BACK button, the search dialog closes and the activity
+regains input focus. You can register to be notified when the search dialog is
 closed with {@link android.app.SearchManager#setOnDismissListener(SearchManager.OnDismissListener)
 setOnDismissListener()}
 and/or {@link android.app.SearchManager#setOnCancelListener(SearchManager.OnCancelListener)
@@ -420,25 +561,26 @@ android.app.SearchManager.OnCancelListener OnCancelListener} only pertains to ev
 user explicitly exited the search dialog, so it is not called when a search is executed (in which
 case, the search dialog naturally disappears).
      
 
-
      If the current Activity is not the searchable Activity, then the normal Activity lifecycle
-events are triggered once the user executes a search (the current Activity receives {@link
+
      If the current activity is not the searchable activity, then the normal activity lifecycle
+events are triggered once the user executes a search (the current activity receives {@link
 android.app.Activity#onPause()} and so forth, as
-described in Activities
-document). If, however, the current Activity is the searchable Activity, then one of two
+described in the Activities
+document). If, however, the current activity is the searchable activity, then one of two
 things happens:
      
 
 
        
-  
      1. By default, the searchable Activity receives the {@link
-android.content.Intent#ACTION_SEARCH} Intent with a call to {@link
+  
      2. By default, the searchable activity receives the {@link
+android.content.Intent#ACTION_SEARCH} intent with a call to {@link
 android.app.Activity#onCreate(Bundle) onCreate()} and a new instance of the
-Activity is brought to the top of the Activity stack. There are now two instances of your
-searchable Activity in the Activity stack (so pressing the BACK key goes back to the previous
-instance of the searchable Activity, rather than exiting the searchable Activity).
        3. 
-  
      3. If you set {@code android:launchMode} to "singleTop", then the
-searchable Activity receives the {@link android.content.Intent#ACTION_SEARCH} Intent with a call
+activity is brought to the top of the activity stack. There are now two instances of your
+searchable activity in the activity stack (so pressing the BACK button goes back to the previous
+instance of the searchable activity, rather than exiting the searchable activity).
        4. 
+  
      4. If you set {@code android:launchMode} to "singleTop", then the
+searchable activity receives the {@link android.content.Intent#ACTION_SEARCH} intent with a call
 to {@link android.app.Activity#onNewIntent(Intent)}, passing the new {@link
-android.content.Intent#ACTION_SEARCH} Intent here. For example, here's how you might handle
-this case, in which the searchable Activity's launch mode is "singleTop":
+android.content.Intent#ACTION_SEARCH} intent here. For example, here's how you might handle
+this case, in which the searchable activity's launch mode is "singleTop":
 
         @Override
 public void onCreate(Bundle savedInstanceState) {
@@ -463,29 +605,29 @@ private void handleIntent(Intent intent) {
 
 
        Compared to the example code in the section about Performing a
 Search, all the code to handle the
-search Intent is now in the {@code handleIntent()} method, so that both {@link
+search intent is now in the {@code handleIntent()} method, so that both {@link
 android.app.Activity#onCreate(Bundle)
 onCreate()} and {@link android.app.Activity#onNewIntent(Intent) onNewIntent()} can execute it.
        
 
-
        When the system calls {@link android.app.Activity#onNewIntent(Intent)}, the Activity has
+
        When the system calls {@link android.app.Activity#onNewIntent(Intent)}, the activity has
 not been restarted, so the {@link android.app.Activity#getIntent()} method
-returns the same Intent that was received with {@link
+returns the same intent that was received with {@link
 android.app.Activity#onCreate(Bundle) onCreate()}. This is why you should call {@link
 android.app.Activity#setIntent(Intent)} inside {@link
-android.app.Activity#onNewIntent(Intent)} (so that the Intent saved by the Activity is updated in
+android.app.Activity#onNewIntent(Intent)} (so that the intent saved by the activity is updated in
 case you call {@link android.app.Activity#getIntent()} in the future).
        
 
 
        5. 
 
      
 
-
      The second scenario using "singleTop" launch mode is usually ideal, because chances are good that
-once a search is done, the user will perform additional searches and it's a bad experience if your
-application creates multiple instances of the searchable Activity. So, we recommend that you set
-your searchable Activity to "singleTop" launch mode in the application
-manifest. For example:
      
+
      The second scenario using "singleTop" launch mode is usually ideal, because chances
+are good that once a search is done, the user will perform additional searches and it's a bad
+experience if your application creates multiple instances of the searchable activity. So, we
+recommend that you set your searchable activity to "singleTop" launch mode in the
+application manifest. For example:
      
 
 
      -<activity android:name=".MySearchableActivity"
+<activity android:name=".SearchableActivity"
           android:launchMode="singleTop" >
     <intent-filter>
         <action android:name="android.intent.action.SEARCH" />
@@ -497,57 +639,192 @@ manifest. For example:
      
 
 
 
-
      Passing Search Context Data
      
+
      Passing search context data
      
 
-
      To refine your search criteria from the current Activity instead of depending only on the user's
-search query, you can provide additional data in the Intent that the Search Manager sends to your
-searchable Activity. In a simple case, you can make your refinements inside the searchable
-Activity, for every search made, but if your
-search criteria varies from one searchable context to another, then you can pass whatever data
-is necessary to refine your search in the {@link android.app.SearchManager#APP_DATA} {@link
-android.os.Bundle}, which is included in the {@link android.content.Intent#ACTION_SEARCH}
-Intent.
      
+
      In some cases, you can make necessary refinements to the search query inside the searchable
+activity, for every search made. However, if you want to refine your search criteria based on the
+activity from which the user is performing a search, you can provide additional data in the intent
+that the system sends to your searchable activity. You can pass the additional data in the {@link
+android.app.SearchManager#APP_DATA} {@link android.os.Bundle}, which is included in the {@link
+android.content.Intent#ACTION_SEARCH} intent.
      
 
-
      To pass this kind of data to your searchable Activity, override  {@link
-android.app.Activity#onSearchRequested()} method for the Activity in which search can be invoked.
+
      To pass this kind of data to your searchable activity, override the {@link
+android.app.Activity#onSearchRequested()} method for the activity from which the user can perform a
+search, create a {@link android.os.Bundle} with the additional data, and call {@link
+android.app.Activity#startSearch startSearch()} to activate the search dialog.
 For example:
      
 
 
       @Override
 public boolean onSearchRequested() {
      Bundle appData = new Bundle();
-     appData.putBoolean(MySearchableActivity.JARGON, true);
+     appData.putBoolean(SearchableActivity.JARGON, true);
      startSearch(null, false, appData, false);
      return true;
  }
 
      
 
-
      Returning "true" indicates that you have successfully handled this callback event. Then in your
-searchable Activity, you can extract the data placed inside {@code appdata} from the {@link
+
      Returning "true" indicates that you have successfully handled this callback event and
+called {@link android.app.Activity#startSearch startSearch()} to activate
+the search dialog. Once the user submits a query, it's delivered to your
+searchable activity along with the data you've added. You can extract the extra data from the {@link
 android.app.SearchManager#APP_DATA} {@link android.os.Bundle} to refine the search. For example:
      
 
 
       Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
 if (appData != null) {
-    boolean jargon = appData.getBoolean(MySearchableActivity.JARGON);
+    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
 }
 
      
 
 
      Caution: Never call the {@link
 android.app.Activity#startSearch(String,boolean,Bundle,boolean) startSearch()} method from outside
-the {@link android.app.Activity#onSearchRequested()} callback method. To invoke the search dialog
-in your Activity, always call {@link android.app.Activity#onSearchRequested()}. Otherwise, {@link
+the {@link android.app.Activity#onSearchRequested()} callback method. To activate the search dialog
+in your activity, always call {@link android.app.Activity#onSearchRequested()}. Otherwise, {@link
 android.app.Activity#onSearchRequested()} is not called and customizations (such as the addition of
 {@code appData} in the above example) are missed.
      
 
 
+
+
      Using the Search Widget
      
+
+
      
+  
+  
      Figure 2. The {@link
+android.widget.SearchView} widget as an "action view" in the Action Bar.
      
+
      
+
+
      The {@link android.widget.SearchView} widget is available in Android 3.0 and higher. If
+you're developing your application for Android 3.0 and have decided to use the search widget, we
+recommend that you insert the search widget as an action view in the Action Bar,
+instead of using the search dialog (and instead of placing the search widget in your activity
+layout). For example, figure 2 shows the search widget in the Action Bar.
      
+
+
      The search widget provides the same functionality as the search dialog. It starts the appropriate
+activity when the user executes a search, and it can provide search suggestions and perform voice
+search.
      
+
+
      Note: When you use the search widget as an action view, you
+still might need to support using the search dialog, for cases in which the search widget does
+not fit in the Action Bar. See the following section about Using both
+the widget and the dialog.
      
+
+
+
      Configuring the search widget
      
+
+
      After you've created a  searchable configuration and a searchable activity, as discussed above, you need to enable assisted
+search for each {@link android.widget.SearchView}. You can do so by calling {@link
+android.widget.SearchView#setSearchableInfo setSearchableInfo()} and passing it the {@link
+android.app.SearchableInfo} object that represents your searchable configuration.
      
+
+
      You can get a reference to the {@link android.app.SearchableInfo} by calling {@link
+android.app.SearchManager#getSearchableInfo getSearchableInfo()} on {@link
+android.app.SearchManager}.
      
+
+
      For example, if you're using a {@link android.widget.SearchView} as an action view in the Action Bar, you should enable the widget
+during the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback:
      
+
+
      +@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    // Inflate the options menu from XML
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.options_menu, menu);
+
+    // Get the SearchView and set the searchable configuration
+    SearchManager searchManager = (SearchManager) {@link android.app.Activity#getSystemService getSystemService}(Context.SEARCH_SERVICE);
+    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
+    searchView.setSearchableInfo(searchManager.getSearchableInfo({@link android.app.Activity#getComponentName()}));
+    searchView.setIconifiedByDefault(false); // Do not iconify the widget; expand it by default
+
+    return true;
+}
+
      
+
+
      That's all you need. The search widget is now configured and the system will deliver search
+queries to your searchable activity. You can also enable search
+suggestions for the search widget.
      
+
+
      Note: If you want to handle all user input yourself, you can do so
+with some callback methods and event listeners. For more information, see the reference
+documentation for {@link android.widget.SearchView} and its nested interfaces for the
+appropriate event listeners.
      
+
+
      For more information about action views in the Action Bar, read Using the Action Bar (which
+includes sample code for adding a search widget as an action view).
      
+
+
+
      Other search widget features
      
+
+
      The {@link android.widget.SearchView} widget allows for a few additional features you might
+want:
      
+
+
      
+  
      A submit button
      
+  
      By default, there's no button to submit a search query, so the user must press the
+"Return" key on the keyboard to initiate a search. You can add a "submit" button by calling
+{@link android.widget.SearchView#setSubmitButtonEnabled setSubmitButtonEnabled(true)}.
      
+  
      Query refinement for search suggestions
      
+  
      When you've enabled search suggestions, you usually expect users to simply select a
+suggestion, but they might also want to refine the suggested search query. You can add a button
+alongside each suggestion that inserts the suggestion in the search box for refinement by the
+user, by calling {@link android.widget.SearchView#setQueryRefinementEnabled
+setQueryRefinementEnabled(true)}.
      
+  
      The ability to toggle the search box visibility
      
+  
      By default, the search widget is "iconified," meaning that it is represented only by a
+search icon (a magnifying glass), and expands to show the search box when the user touches it.
+As shown above, you can show the search box by default, by calling {@link
+android.widget.SearchView#setIconifiedByDefault setIconifiedByDefault(false)}. You can also
+toggle the search widget appearance by calling {@link android.widget.SearchView#setIconified
+setIconified()}.
      
+
      
+
+
      There are several other APIs in the {@link android.widget.SearchView} class that allow you to
+customize the search widget. However, most of them are used only when you handle all
+user input yourself, instead of using the Android system to deliver search queries and display
+search suggestions.
      
+
+
+
      Using both the widget and the dialog
      
+
+
      If you insert the search widget in the Action Bar as an action view, and you enable it to
+appear in the Action Bar "if there is room" (by setting {@code
+android:showAsAction="ifRoom"}), then there is a chance that the search widget will not appear
+as an action view, but the menu item will appear in the overflow menu. For example, when your
+application runs on a smaller screen, there might not be enough room in the Action Bar to display
+the search widget along with other action items or navigation elements, so the menu item will
+instead appear in the overflow menu. When placed in the overflow menu, the item works like an
+ordinary menu item and does not display the action view (the search widget).
      
+
+
      To handle this situation, the menu item to which you've attached the search widget should
+activate the search dialog when the user selects it from the overflow menu. In order for it to do
+so, you must implement {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} to
+handle the "Search" menu item and open the search dialog by calling {@link
+android.app.Activity#onSearchRequested onSearchRequested()}.
      
+
+
      For more information about how items in the Action Bar work and how to handle this situation, see
+the documentation for Using the Action
+Bar.
      
+
+
      Also see the Searchable Dictionary for an example implementation using
+both the dialog and the widget.
      
+
+
+
 
      Adding Voice Search
      
 
-
      You can add voice search functionality to your search dialog by adding the {@code
+
      You can add voice search functionality to your search dialog or widget by adding the {@code
 android:voiceSearchMode} attribute to your searchable configuration. This adds a voice search
-button in the search dialog that launches a voice prompt. When the user
+button that launches a voice prompt. When the user
 has finished speaking, the transcribed search query is sent to your searchable
-Activity.
      
+activity.
      
 
 
      For example:
      
 
@@ -562,7 +839,7 @@ Activity.
      
 
 
      The value {@code showVoiceSearchButton} is required to enable voice
 search, while the second value, {@code launchRecognizer}, specifies that the voice search button
-should launch a recognizer that returns the transcribed text to the searchable Activity.
      
+should launch a recognizer that returns the transcribed text to the searchable activity.
      
 
 
      You can provide additional attributes to specify the voice search behavior, such
 as the language to be expected and the maximum number of results to return. See the 
 
 
      Note: Carefully consider whether voice search is appropriate for
 your application. All searches performed with the voice search button are immediately sent to
-your searchable Activity without a chance for the user to review the transcribed query. Sufficiently
+your searchable activity without a chance for the user to review the transcribed query. Sufficiently
 test the voice recognition and ensure that it understands the types of queries that
 the user might submit inside your application.
      
+
+
+
+
      Adding Search Suggestions
      
+
+
      
+
+
      Figure 3. Screenshot of a search dialog with custom
+search suggestions.
      
+
      
+
+
      Both the search dialog and the search widget can provide search suggestions as the user
+types, with assistance from the Android system. The system manages the list of suggestions and
+handles the event when the user selects a suggestion.
      
+
+
      You can provide two kinds of search suggestions:
      
+
+
      
+  
      Recent query search suggestions
      
+  
      These suggestions are simply words that the user previously used as search queries in
+your application.
+  
      See Adding Recent Query
+Suggestions.
      
+  
      Custom search suggestions
      
+  
      These are search suggestions that you provide from your own data source, to help users
+immediately select the correct spelling or item they are searching for. Figure 3 shows an
+example of custom suggestions for a dictionary application—the user can select a suggestion
+to instantly go to the definition.
+  
      See Adding Custom
+Suggestions
      
+
      
+
diff --git a/docs/html/guide/topics/search/searchable-config.jd b/docs/html/guide/topics/search/searchable-config.jd
index 2aa2db6219cb..fb689f9705f2 100644
--- a/docs/html/guide/topics/search/searchable-config.jd
+++ b/docs/html/guide/topics/search/searchable-config.jd
@@ -7,19 +7,20 @@ parent.link=index.html
 
 
 
-
      To utilize the Android search framework and provide a custom search dialog, your
-application must provide a search
-configuration in the form of an XML resource. This document describes the search configuration XML
-in terms of its syntax and usage. For more information about how to implement search
-features for your application, see the developer guide about Search.
      
+
      In order to implement search with assistance from the Android system (to deliver search queries
+to an activity and provide search suggestions), your application must provide a search configuration
+in the form of an XML file.
      
+
+
      This page describes the search configuration file in terms of its syntax and usage. For more
+information about how to implement search features for your application, begin with the developer
+guide about Creating a Search Interface.
      
 
 
      
 
@@ -66,7 +67,7 @@ Android uses the filename as the resource ID.
 
      
 
      
   
      <searchable>
      
-  
      Defines all search configurations used with the search dialog.
+  
      Defines all search configurations used by the Android system to provide assisted search.
     
      attributes:
      
       
      
       
      android:label
      
@@ -86,21 +87,21 @@ string for {@code android:hint} as "Search <content-or-product>".
 "Search songs and artists" or "Search YouTube".
      
 
       
      android:searchMode
      
-      
      Keyword. Sets additional modes that control the search dialog presentation.
-Currently available modes define how the query text that appears in the search dialog
-should be rewritten when a custom suggestion receives focus. The following mode values are accepted:
+      
      Keyword. Sets additional modes that control the search presentation.
+Currently available modes define how the query text should be rewritten when a custom suggestion
+receives focus. The following mode values are accepted:
         
+column to rewrite the query text.
@@ -117,7 +118,7 @@ behavior is something other than a search (such as a URL request in a web browse
 
       
      android:inputType
      Keyword. 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
 attribute.
      
 
@@ -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).
      android:searchSuggestIntentAction
      
-        
      String. The default Intent action to be used when a user
+        
      String. The default intent action to be used when a user
         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
 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.
      android:searchSuggestIntentData
      
-        
      String. The default Intent data to be used when a user
+        
      String. The default intent data to be used when a user
         clicks on a custom search suggestion.
         If not overridden by the selected suggestion (via the {@link
 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
 
       
      android:searchSuggestThreshold
      Integer. 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.
      
 
@@ -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
 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
-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.
      Voice search attributes
      
 
-    
      To enable voice search for your search dialog, you'll need some of the
+    
      To enable voice search, you'll need some of the
     following {@code <searchable>} attributes:

      
         
      android:voiceSearchMode
      
         
      Keyword. (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
           have no effect.) The following mode values are accepted:
           
      
           
      ValueDescription
      
           
      
             "queryRewriteFromText"
             Use the value from the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1}
-colum to rewrite the query text in the search dialog.
           
      
           
      
             "queryRewriteFromData"
             Use the value from 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
 inspection and editing, typically HTTP URI's.
           
      
       
 
       
 
       
         
       
       
 
 
     
 
       
      
@@ -238,14 +240,14 @@ then either {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be
               
+              it takes the user away from the activity in which search was invoked.
      "launchWebSearch"
               The voice search button takes the user directly
               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.
             
      
             
      
               "launchRecognizer"
               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
-              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.
             
      
           
      
@@ -283,9 +285,9 @@ java.util.Locale#getDefault() Locale.getDefault()}.
      
         
      android:voiceMaxResults
      
           
      Integer. Forces the maximum number of results to return,
           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
-get the results from the Intent.
+get the results from the intent.
           If not provided, the recognizer chooses how many results to return.
      
       
      
   
       
@@ -311,8 +313,8 @@ other three attributes in order to define the search action.
      
         
      String. (Required.) A key code from {@link
 android.view.KeyEvent} that represents the action key
         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
-        searchable Activity. To examine the key code, use
+        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that is passed to your
+        searchable activity. To examine the key code, use
         {@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
 functions.
      
@@ -320,15 +322,15 @@ functions.
       
      android:queryActionMsg
      
         
      String. An action message to be sent if the action key is pressed while the
 user is entering query text. This is added to the
-        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that the Search Manager
-        passes to your searchable Activity. To examine the string, use
+        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that the system
+        passes to your searchable activity. To examine the string, use
         {@link android.content.Intent#getStringExtra
         getStringExtra(SearchManager.ACTION_MSG)}.
      
 
       
      android:suggestActionMsg
      
         
      String. An action message to be sent if the action key is pressed while a
         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,
         use {@link android.content.Intent#getStringExtra 
         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.
         
      First, you must define a column in your
 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
         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
 android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data
 does not exist for the selected suggestion, the action key is ignored.
      
diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd
index 065f95a28158..d8898ae3e542 100644
--- a/docs/html/guide/topics/ui/actionbar.jd
+++ b/docs/html/guide/topics/ui/actionbar.jd
@@ -323,8 +323,7 @@ the item is enabled as an action item.
      
 
 
      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
-perform a search should, by default, bring up the search dialog, but if the item is
+perform a search should, by default, bring up the Android search dialog, but if the item is
 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
 view.
      
@@ -369,9 +368,7 @@ always appear as an action view by setting {@code android:showAsAction} to {@cod
 
      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
 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
-guide to providing search functionality, see the Search documentation.)
      
+android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.
      
 
 
      When the activity first starts, the system populates the Action Bar and overflow menu by calling
 {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()}.
@@ -392,8 +389,8 @@ public boolean onCreateOptionsMenu(Menu menu) {
 }
 
      
 
-
      For more information about enabling search in the Action Bar, see the Search developer guide.
      
+
      For more information about using the search widget, see Creating a Search Interface.
      
 
 
 
diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd
index 6c087bb41b7c..f88c3a6e6192 100644
--- a/docs/html/sdk/android-3.0.jd
+++ b/docs/html/sdk/android-3.0.jd
@@ -556,11 +556,10 @@ keyboard) is visible, the popup does not overlap the IME it until the user touch
 menu.
      
     
     
    6. {@link android.widget.SearchView}
-    
      Provides a search box that works in conjunction with the Search Manager (in the same manner
-as the traditional search dialog). It
-can also display recent query suggestions or custom suggestions as configured by the search
-provider. This widget is particularly useful for offering search in the Action Bar.
      7. 
+    
      Provides a search box that you can configure to deliver search queries to a specified
+activity and display search suggestions (in the same manner as the traditional search dialog). This
+widget is particularly useful for offering a search widget in the Action Bar. For more information,
+see Creating a Search Interface
      .
     
     
    7. {@link android.widget.StackView}
     
      A view that displays its children in a 3D stack and allows users to swipe through
-- 
cgit v1.2.3-59-g8ed1b