am 2213a4ac: am 462012db: am abdf0d53: docs: update search dev guide with SearcView widget

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.

 *

 * <p>

 * <b>XML attributes</b>

 * <p>

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

 * {@link android.R.styleable#View View Attributes}

 * <p>For more information, see the <a href="{@docRoot}guide/topics/search/index.html">Search</a>

 * documentation.<p>

 *

 * @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 {

     * in the SearchableInfo.

     *

     * @param hint the hint text to display

     *

     * @attr ref android.R.styleable#SearchView_queryHint

     */

    public void setQueryHint(CharSequence hint) {

        mQueryHint = hint;

     * <p>The default value is true.</p>

     *

     * @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;

            <span class="en">Search</span>

          </a></div>

          <ul>

            <li><a href="<?cs var:toroot?>guide/topics/search/search-dialog.html">Using the Android Search Dialog</a></li>

            <li><a href="<?cs var:toroot?>guide/topics/search/search-dialog.html">Creating a Search Interface</a></li>

            <li><a href="<?cs var:toroot?>guide/topics/search/adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>

            <li><a href="<?cs var:toroot?>guide/topics/search/adding-custom-suggestions.html">Adding Custom Suggestions</a></li>

            <li><a href="<?cs var:toroot?>guide/topics/search/searchable-config.html">Searchable Configuration</a></li>

</div>

</div>

<p>When using the Android search dialog, you can provide search suggestions based on recent search

<p>When using the Android search dialog or search widget, you can provide search suggestions based

on recent search

queries. For example, if a user previously searched for "puppies," then that query appears as a

suggestion once he or she begins typing the same query. Figure 1 shows an example of a search dialog

with recent query suggestions.</p>

<p>Before you begin, you need to implement the search dialog for basic searches in your application.

If you haven't, see <a href="search-dialog.html">Using the Android Search Dialog</a>.</p>

<p>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 <a href="search-dialog.html">Creating a Search Interface</a>.</p>

</div>

<p>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 <a href="search-dialog.html">Using the Android

Search Dialog</a>).</p>

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 <a href="search-dialog.html">Creating a Search

Interface</a>).</p>

<p>To provide recent queries suggestions, you need to:</p>

<ul>

  <li>Implement a searchable Activity, <a

href="{@docRoot}guide/topics/search/search-dialog.html">using the Android Search Dialog</a>.</li>

  <li>Implement a searchable activity, as described in <a

href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</li>

  <li>Create a content provider that extends {@link

android.content.SearchRecentSuggestionsProvider} and declare it in your application manifest.</li>

  <li>Modify the searchable configuration with information about the content provider that

  <li>Save queries to your content provider each time a search is executed.</li>

</ul>

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

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

<p>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:</p>

<p>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:</p>

<ol>

  <li>Search Manager takes the search query text (whatever has been typed so far) and performs a

  <li>The system takes the search query text (whatever has been typed so far) and performs a

query to the content provider that contains your suggestions.</li>

  <li>Your content provider returns a {@link android.database.Cursor} that points to all

suggestions that match the search query text.</li>

  <li>Search Manager displays the list of suggestions provided by the Cursor.</li>

  <li>The system displays the list of suggestions provided by the Cursor.</li>

</ol>

<p>Once the recent query suggestions are displayed, the following might happen:</p>

  <li>If the user types another key, or changes the query in any way, the aforementioned steps are

repeated and the suggestion list is updated.</li>

  <li>If the user executes the search, the suggestions are ignored and the search is delivered

to your searchable Activity using the normal {@link android.content.Intent#ACTION_SEARCH}

Intent.</li>

to your searchable activity using the normal {@link android.content.Intent#ACTION_SEARCH}

intent.</li>

  <li>If the user selects a suggestion, an

{@link android.content.Intent#ACTION_SEARCH} Intent is delivered to your searchable Activity using

{@link android.content.Intent#ACTION_SEARCH} intent is delivered to your searchable activity using

the suggested text as the query.</li>

</ul>

<h2 id="RecentQuerySearchableConfiguration">Modifying the Searchable Configuration</h2>

<p>To configure your search dialog to use your suggestions provider, you need to add

<p>To configure the system to use your suggestions provider, you need to add

the {@code android:searchSuggestAuthority} and {@code android:searchSuggestSelection} attributes to

the {@code &lt;searchable&gt;} element in your searchable configuration file. For example:</p>

<h2 id="SavingQueries">Saving Queries</h2>

<p>To populate your collection of recent queries, add each query

received by your searchable Activity to your {@link

received by your searchable activity to your {@link

android.content.SearchRecentSuggestionsProvider}. To do this, create an instance of {@link

android.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:</p>

your searchable activity receives a query. For example, here's how you can save the query during

your activity's {@link android.app.Activity#onCreate(Bundle) onCreate()} method:</p>

<pre>

@Override

    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);

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

<div id="qv">

<h2>Topics</h2>

<ol>

<li><a href="search-dialog.html">Using the Android Search Dialog</a></li>

<li><a href="search-dialog.html">Creating a Search Interface</a></li>

<li><a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a></li>

<li><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></li>

</ol>

<p>Search is a core user feature on Android. Users should be able

to search any data that is available to them, whether the content is located on the device or

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

the Internet. To help create a consistent search experience for users, Android provides a

search framework that helps you implement search for your application.</p>

<div class="figure" style="width:250px">

<img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" />

search suggestions.</p>

</div>

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

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

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

<p>Once your application is set up to use the search dialog, you can:</p>

<p>Once you've set up either the search dialog or the search widget, you can:</p>

<ul>

<li>Enable voice search</li>

if your data is stored in an SQLite database, you should use the {@link android.database.sqlite}

APIs to perform searches.</p>

<p>The following documents show you how to use the search dialog in your application:</p>

<p>The following documents show you how to use Android's framework to implement search:</p>

<dl>

  <dt><strong><a href="search-dialog.html">Using the Android Search Dialog</a></strong></dt>

  <dd>How to set up your application to use the search dialog. </dd>

  <dt><strong><a href="search-dialog.html">Creating a Search Interface</a></strong></dt>

  <dd>How to set up your application to use the search dialog or search widget. </dd>

  <dt><strong><a href="adding-recent-query-suggestions.html">Adding Recent Query

Suggestions</a></strong></dt>

  <dd>How to show suggestions based on queries previously used in the search dialog.</dd>

  <dd>How to provide suggestions based on queries previously used.</dd>

  <dt><strong><a href="adding-custom-suggestions.html">Adding Custom Suggestions</a></strong></dt>

  <dd>How to show suggestions based on custom data from your application and offer your suggestions

  <dd>How to provide suggestions based on custom data from your application and also offer them

in the system-wide Quick Search Box.</dd>

  <dt><strong><a href="searchable-config.html">Searchable Configuration</a></strong></dt>

  <dd>A reference for the searchable configuration file (though the other

  <dd>A reference document for the searchable configuration file (though the other

documents also discuss the configuration file in terms of specific behaviors).</dd>

</dl>

send the personal information, you should not log it. If you must log it, protect that data

very carefully and erase it as soon as possible.</p>

</li>

<li><strong>Provide the user with a way to clear their search history.</strong>

<li><strong>Provide users with a way to clear their search history.</strong>

<p>The search framework helps your application provide context-specific suggestions while the user

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

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

</li>

</ul>