Merge "revise info on Search button availability... behavior not guaranteed...

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

APIs to perform searches.

<br/><br/>

Also, there is no guarantee that every device provides a dedicated SEARCH button to invoke the

Also, there is no guarantee that a device provides a dedicated SEARCH button that invokes the

search interface in your application. When using the search dialog or a custom interface, you

must always provide a search button in your UI that activates the search interface. For more

must provide a search button in your UI that activates the search interface. For more

information, see <a href="search-dialog.html#InvokingTheSearchDialog">Invoking the search

dialog</a>.</p>

<div id="qv-wrapper">

<div id="qv">

  <h2>Quickview</h2>

  <ul>

    <li>The Android system sends search queries from the search dialog or widget to an activity you

specify to perform searches and present results</li>

    <li>You can put the search widget in the Action Bar, as an "action view," for quick

access</li>

  </ul>

<h2>In this document</h2>

<ol>

<h2>Downloads</h2>

<ol>

<li><a href="{@docRoot}shareables/search_icons.zip">search_icons.zip</a></li>

</ol>

<h2>See also</h2>

<ol>

<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="searchable-config.html">Searchable Configuration</a></li>

<li><a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar

Icon Pack</a></li>

</ol>

</div>

  <li>A search interface, provided by either:

    <ul>

      <li>The search dialog

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

        <p>By default, the search dialog is hidden, but appears at the top of the screen when

          you call {@link android.app.Activity#onSearchRequested()} (when the user presses your

          Search button).</p>

      </li>

      <li>Or, a {@link android.widget.SearchView} widget

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

Instead of putting it in your activity layout, you should usually use

{@link android.widget.SearchView} as an 

<a href="{@docRoot}guide/topics/ui/actionbar.html#ActionView">action view in the Action Bar</a>.</p>

      </li>

    </ul>

your application for devices running Android 3.0, you should consider using the search widget

instead (see the side box).</p>

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

<p>The search dialog is always hidden by default, until the user activates it. Your application

can activate the search dialog by calling {@link

android.app.Activity#onSearchRequested onSearchRequested()}. However, this method doesn't work

until you enable the search dialog for the activity.</p>

<p>To enable the search dialog, you must indicate to the system which searchable activity should

href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code &lt;meta-data&gt;}</a>

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.

While the user is in this activity, the {@link

android.app.Activity#onSearchRequested onSearchRequested()} method activates 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.</p>

<h3 id="InvokingTheSearchDialog">Invoking the search dialog</h3>

<p>As mentioned above, the device SEARCH button will open the search dialog as long as the current

activity has declared in the manifest the searchable activity to use.</p>

<p>However, some devices do not include a dedicated SEARCH button, so you should not assume that

it's always available. When using the search dialog, you must <strong>always provide another search

button in your UI</strong> that activates the search dialog by calling {@link

android.app.Activity#onSearchRequested()}.</p>

<p>For instance, you should either provide a menu item in your <a

href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> or a button in your

activity layout that

activates search by calling {@link android.app.Activity#onSearchRequested()}. The <a

href="{@docRoot}shareables/search_icons.zip">search_icons.zip</a> file includes icons for

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

<p>Although some devices provide a dedicated Search button, the behavior of the button may vary

between devices and many devices do not provide a Search button at all. So when using the search

dialog, you <strong>must provide a search button in your UI</strong> that activates the search

dialog by calling {@link android.app.Activity#onSearchRequested()}.</p>

<p>For instance, you should add a Search button in your <a

href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> or UI

layout that calls {@link android.app.Activity#onSearchRequested()}. For consistency with

the Android system and other apps, you should label your button with the Android Search icon that's

available from the <a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar

Icon Pack</a>.</p>

<p class="note"><strong>Note:</strong> If your app uses the <a

href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>, then you should not use

the search dialog for your search interface. Instead, use the <a href="#UsingSearchWidget">search

widget</a> as a collapsible view in the action bar.</p>

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