From 911711fd31c29fa3a0fad27d98071f7295fc5c00 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Mon, 13 Aug 2012 18:22:21 -0700 Subject: revise info on Search button availability... behavior not guaranteed either bug: 6966922 Change-Id: I4122e6fb99b95da3f53b56333a5f27d2adde6d44 --- docs/html/guide/topics/search/index.jd | 4 +- docs/html/guide/topics/search/search-dialog.jd | 68 +++++++++++--------------- 2 files changed, 30 insertions(+), 42 deletions(-) diff --git a/docs/html/guide/topics/search/index.jd b/docs/html/guide/topics/search/index.jd index 2ee624b6b7a7..680c6079a1c0 100644 --- a/docs/html/guide/topics/search/index.jd +++ b/docs/html/guide/topics/search/index.jd @@ -54,9 +54,9 @@ 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.

-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 Invoking the search dialog.

diff --git a/docs/html/guide/topics/search/search-dialog.jd b/docs/html/guide/topics/search/search-dialog.jd index 49451acf4d29..b9a26d669a48 100644 --- a/docs/html/guide/topics/search/search-dialog.jd +++ b/docs/html/guide/topics/search/search-dialog.jd @@ -6,14 +6,6 @@ parent.link=index.html
-

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

    @@ -61,14 +53,8 @@ Dictionary

    Downloads

      -
    1. search_icons.zip
      2. -
    - -

    See also

    -
      -
    1. Adding Recent Query Suggestions
      2. -
    2. Adding Custom Suggestions
      3. -
    3. Searchable Configuration
      4. +
    4. Action Bar +Icon Pack
@@ -142,12 +128,14 @@ 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.

      +

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

    • 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 +Instead of putting it in your activity layout, you should usually use +{@link android.widget.SearchView} as an action view in the Action Bar.

    @@ -415,10 +403,9 @@ 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 +

    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.

    To enable the search dialog, you must indicate to the system which searchable activity should @@ -469,8 +456,8 @@ search dialog:

    href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@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. +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.

    @@ -495,21 +482,22 @@ searches.

    Invoking the search dialog

    -

    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.

    - -

    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 always provide another search -button in your UI that activates the search dialog by calling {@link -android.app.Activity#onSearchRequested()}.

    - -

    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 scale-down the hdpi image by one half).

    +

    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 must provide a search button in your UI that activates the search +dialog by calling {@link android.app.Activity#onSearchRequested()}.

    + +

    For instance, you should add a Search button in your Options Menu 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 Action Bar +Icon Pack.

    + +

    Note: If your app uses the action bar, then you should not use +the search dialog for your search interface. Instead, use the search +widget as a collapsible view in the action bar.

    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 -- cgit v1.2.3-59-g8ed1b