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).
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.
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.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.
+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()}.
-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 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.
-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).
+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