Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit abdf0d53 authored by Scott Main's avatar Scott Main
Browse files

docs: update search dev guide with SearcView widget 

Change-Id: Ieb0ccdb78760a3c90df2381e647463f7532b0efc
parent 9f187296

core/java/android/widget/SearchView.java

+9 −7
Original line number Original line Diff line number Diff line
@@ -54,18 +54,16 @@ import android.widget.TextView.OnEditorActionListener; 
import java.util.WeakHashMap;

import java.util.WeakHashMap;





/**

/**

 * Provides the user interface elements for the user to enter a search query and submit a

 * A widget that provides a user interface for the user to enter a search query and submit a

 * request to a search provider. Shows a list of query suggestions or results, if

 * request to a search provider. Shows a list of query suggestions or results, if

 * available and allows the user to pick a suggestion or result to launch into.

 * available, and allows the user to pick a suggestion or result to launch into.

 *

 *

 * <p>

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

 * <b>XML attributes</b>

 * documentation.<p>

 * <p>

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

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

 *

 *

 * @attr ref android.R.styleable#SearchView_iconifiedByDefault

 * @attr ref android.R.styleable#SearchView_iconifiedByDefault

 * @attr ref android.R.styleable#SearchView_maxWidth

 * @attr ref android.R.styleable#SearchView_maxWidth

 * @attr ref android.R.styleable#SearchView_queryHint

 */

 */

public class SearchView extends LinearLayout {

public class SearchView extends LinearLayout {
@@ -374,6 +372,8 @@ public class SearchView extends LinearLayout { 
     * in the SearchableInfo.

     * in the SearchableInfo.

     *

     *

     * @param hint the hint text to display

     * @param hint the hint text to display

     *

     * @attr ref android.R.styleable#SearchView_queryHint

     */

     */

    public void setQueryHint(CharSequence hint) {

    public void setQueryHint(CharSequence hint) {

        mQueryHint = hint;

        mQueryHint = hint;
@@ -389,6 +389,8 @@ public class SearchView extends LinearLayout { 
     * <p>The default value is true.</p>

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

     *

     *

     * @param iconified whether the search field should be iconified by default

     * @param iconified whether the search field should be iconified by default

     *

     * @attr ref android.R.styleable#SearchView_iconifiedByDefault

     */

     */

    public void setIconifiedByDefault(boolean iconified) {

    public void setIconifiedByDefault(boolean iconified) {

        if (mIconifiedByDefault == iconified) return;

        if (mIconifiedByDefault == iconified) return;

docs/html/guide/guide_toc.cs

+1 −1
Original line number Original line Diff line number Diff line
@@ -310,7 +310,7 @@ 
            <span class="en">Search</span>

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

          </a></div>

          </a></div>

          <ul>

          <ul>

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

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

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

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

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

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

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

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

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

+91 −93

File changed.

Preview size limit exceeded, changes collapsed.

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

+29 −28
Original line number Original line Diff line number Diff line
@@ -28,13 +28,15 @@ Configuration</a></li> 
</div>

</div>

</div>

</div>





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

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

on recent search

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

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

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

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

with recent query suggestions.</p>

with recent query suggestions.</p>





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

<p>Before you begin, you need to implement the search dialog or a search widget for basic searches

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

in your application.

If you haven't, see <a href="search-dialog.html">Creating a Search Interface</a>.</p>
@@ -47,16 +49,16 @@ suggestions.</p> 
</div>

</div>





<p>Recent query suggestions are simply saved searches. When the user selects one of

<p>Recent query suggestions are simply saved searches. When the user selects one of

the suggestions, your searchable Activity receives a {@link

the suggestions, your searchable activity receives a {@link

android.content.Intent#ACTION_SEARCH} Intent with the suggestion as the search query, which your

android.content.Intent#ACTION_SEARCH} intent with the suggestion as the search query, which your

searchable Activity already handles (as described in <a href="search-dialog.html">Using the Android

searchable activity already handles (as described in <a href="search-dialog.html">Creating a Search

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

Interface</a>).</p>





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

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





<ul>

<ul>

  <li>Implement a searchable Activity, <a

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

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

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

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

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

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

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

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

  <li>Modify the searchable configuration with information about the content provider that
@@ -64,20 +66,19 @@ provides search suggestions.</li> 
  <li>Save queries to your content provider each time a search is executed.</li>

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

</ul>

</ul>





<p>Just as the Search Manager displays the search dialog, it also displays the

<p>Just as the Android system displays the search dialog, it also displays the

search suggestions. All you need to do is provide a source from which the suggestions can be

search suggestions below the dialog or search widget. All you need to do is provide a source from

retrieved.</p>

which the system can retrieve suggestions.</p>





<p>When the Search Manager identifies that your Activity is searchable and provides search

<p>When the system identifies that your activity is searchable and provides search

suggestions, the following procedure takes place as soon as the user types into the search

suggestions, the following procedure takes place as soon as the user begins typing a query:</p>

dialog:</p>





<ol>

<ol>

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

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

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

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

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

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

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

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

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

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

</ol>

</ol>





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

<p>Once the recent query suggestions are displayed, the following might happen:</p>
@@ -86,10 +87,10 @@ suggestions that match the search query text.</li> 
  <li>If the user types another key, or changes the query in any way, the aforementioned steps are

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

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

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

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

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

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

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

Intent.</li>

intent.</li>

  <li>If the user selects a suggestion, an

  <li>If the user selects a suggestion, an

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

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

the suggested text as the query.</li>

the suggested text as the query.</li>

</ul>

</ul>
@@ -151,7 +152,7 @@ searchable configuration). For example:</p> 




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

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





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

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

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

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

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

the {@code &lt;searchable&gt;} element in your searchable configuration file. For example:</p>
@@ -179,12 +180,12 @@ automatically replaced by the query text entered by the user).</p> 
<h2 id="SavingQueries">Saving Queries</h2>

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





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

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

received by your searchable Activity to your {@link

received by your searchable activity to your {@link

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

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

android.provider.SearchRecentSuggestions} and call {@link

android.provider.SearchRecentSuggestions} and call {@link

android.provider.SearchRecentSuggestions#saveRecentQuery(String,String) saveRecentQuery()} each time

android.provider.SearchRecentSuggestions#saveRecentQuery(String,String) saveRecentQuery()} each time

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

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

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

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





<pre>

<pre>

&#64;Override

&#64;Override
@@ -192,10 +193,10 @@ public void onCreate(Bundle savedInstanceState) { 
    super.onCreate(savedInstanceState);

    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    setContentView(R.layout.main);





    Intent Intent  = getIntent();

    Intent intent  = getIntent();





    if (Intent.ACTION_SEARCH.equals(Intent .getAction())) {

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {

        String query = Intent .getStringExtra(SearchManager.QUERY);

        String query = intent.getStringExtra(SearchManager.QUERY);

        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,

        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,

                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);

                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);

        suggestions.saveRecentQuery(query, null);

        suggestions.saveRecentQuery(query, null);
@@ -212,7 +213,7 @@ the search query string as the first parameter and, optionally, a second string 
second line of the suggestion (or null). The second parameter is only used if you've enabled

second line of the suggestion (or null). The second parameter is only used if you've enabled

two-line mode for the search suggestions with {@link

two-line mode for the search suggestions with {@link

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}. If you have enabled

android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}. If you have enabled

two-line mode, then the query text is also matched against this second line when the Search Manager

two-line mode, then the query text is also matched against this second line when the system

looks for matching suggestions.</p>

looks for matching suggestions.</p>

docs/html/guide/topics/search/index.jd

+23 −26
Original line number Original line Diff line number Diff line
@@ -5,7 +5,7 @@ page.title=Search 
<div id="qv">

<div id="qv">

<h2>Topics</h2>

<h2>Topics</h2>

<ol>

<ol>

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

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

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

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

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

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

</ol>

</ol>
@@ -24,9 +24,8 @@ Dictionary</a></li> 




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

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

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

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

the Internet. The search experience should be seamless and consistent across the entire

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

system, which is why Android provides a search framework to help you provide users with

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

a familiar search dialog and a great search experience.</p>





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

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

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

<img src="{@docRoot}images/search/search-suggest-custom.png" alt="" height="417" />
@@ -34,16 +33,14 @@ a familiar search dialog and a great search experience.</p> 
search suggestions.</p>

search suggestions.</p>

</div>

</div>





<p>Android's search framework provides a user interface in which users can perform a search and

<p>The search framework offers two modes of search input: a search dialog at the top of the

an interaction layer that communicates with your application, so you don't have to build

screen or a search widget ({@link android.widget.SearchView}) that you can embed in your activity

your own search Activity. Instead, a search dialog appears at the top of the screen at the user's

layout. In either case, the Android system will assist your search implementation by

command without interrupting the current Activity.</p>

delivering search queries to a specific activity that performs searchs. You can also enable either

the search dialog or widget to provide search suggestions as the user types. Figure 1 shows an

example of the search dialog with optional search suggestions.</p>





<p>The search framework manages the life of the search dialog. When users execute a search, the

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

search framework passes the query text to your application so your application can perform a

search. Figure 1 shows an example of the search dialog with optional search suggestions.</p>



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





<ul>

<ul>

<li>Enable voice search</li>

<li>Enable voice search</li>
@@ -57,19 +54,19 @@ search your data. To perform a search, you need to use APIs appropriate for your 
if your data is stored in an SQLite database, you should use the {@link android.database.sqlite}

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

APIs to perform searches.</p>

APIs to perform searches.</p>





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

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





<dl>

<dl>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</dl>

</dl>
@@ -92,17 +89,17 @@ you don't need to send the user ID as well; send only the zip code to the server 
send the personal information, you should not log it. If you must log it, protect that data

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

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

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

</li>

</li>

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

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

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

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

types. Sometimes these

types. Sometimes these

suggestions are based on previous searches or other actions taken by the user in an earlier

suggestions are based on previous searches or other actions taken by the user in an earlier

session. A user might not wish for previous searches to be revealed to other device users, for

session. A user might not wish for previous searches to be revealed to other device users, for

instance, if they share their phone with a friend. If your application provides suggestions that can

instance, if the user shares the device with a friend. If your application provides suggestions that

reveal previous activities, you should implement the ability for the user to clear the search

can reveal previous search activities, you should implement the ability for the user to clear the

history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply call the

search history. If you are using {@link android.provider.SearchRecentSuggestions}, you can simply

{@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are implementing

call the {@link android.provider.SearchRecentSuggestions#clearHistory()} method. If you are

custom suggestions, you'll need to provide a similar "clear history" method in your provider that

implementing custom suggestions, you'll need to provide a similar "clear history" method in your

the user can execute.</p>

content provider that the user can execute.</p>

</li>

</li>

</ul>

</ul>