diff --git a/core/java/android/app/SearchManager.java b/core/java/android/app/SearchManager.java index fd559d66cba1f..7ad64237569f0 100644 --- a/core/java/android/app/SearchManager.java +++ b/core/java/android/app/SearchManager.java @@ -40,7 +40,7 @@ import java.util.List; * methods and the the {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} * {@link android.content.Intent Intent}. This class does provide a basic * overview of search services and how to integrate them with your activities. - * If you do require direct access to the Search Manager, do not instantiate + * If you do require direct access to the SearchManager, do not instantiate * this class directly; instead, retrieve it through * {@link android.content.Context#getSystemService * context.getSystemService(Context.SEARCH_SERVICE)}. @@ -49,9 +49,10 @@ import java.util.List; *
    *
  1. Developer Guide *
  2. How Search Is Invoked - *
  3. Query-Search Applications - *
  4. Filter-Search Applications + *
  5. Implementing Search for Your App *
  6. Search Suggestions + *
  7. Exposing Search Suggestions to + * Quick Search Box
    8. *
  8. Action Keys *
  9. Searchability Metadata *
  10. Passing Search Context @@ -62,37 +63,18 @@ import java.util.List; *

    Developer Guide

    * *

    The ability to search for user, system, or network based data is considered to be - * a core user-level feature of the android platform. At any time, the user should be + * a core user-level feature of the Android platform. At any time, the user should be * able to use a familiar command, button, or keystroke to invoke search, and the user - * should be able to search any data which is available to them. The goal is to make search - * appear to the user as a seamless, system-wide feature. + * should be able to search any data which is available to them. * - *

    In terms of implementation, there are three broad classes of Applications: - *

      - *
    1. Applications that are not inherently searchable
      2. - *
    2. Query-Search Applications
      3. - *
    3. Filter-Search Applications
      4. - *
    - *

    These categories, as well as related topics, are discussed in - * the sections below. + *

    To make search appear to the user as a seamless system-wide feature, the application + * framework centrally controls it, offering APIs to individual applications to control how they + * are searched. Applications can customize how search is invoked, how the search dialog looks, + * and what type of search results are available, including suggestions that are available as the + * user types. * - *

    Even if your application is not searchable, it can still support the invocation of - * search. Please review the section How Search Is Invoked - * for more information on how to support this. - * - *

    Many applications are searchable. These are - * the applications which can convert a query string into a list of results. - * Within this subset, applications can be grouped loosely into two families: - *

    - *

    Generally speaking, you would use query search for network-based data, and filter - * search for local data, but this is not a hard requirement and applications - * are free to use the model that fits them best (or invent a new model). - *

    It should be clear that the search implementation decouples "search - * invocation" from "searchable". This satisfies the goal of making search appear - * to be "universal". The user should be able to launch any search from - * almost any context. + *

    Even applications which are not searchable will by default support the invocation of + * search to trigger Quick Search Box, the system's 'global search'. * * *

    How Search Is Invoked

    @@ -100,14 +82,15 @@ import java.util.List; *

    Unless impossible or inapplicable, all applications should support * invoking the search UI. This means that when the user invokes the search command, * a search UI will be presented to them. The search command is currently defined as a menu - * item called "Search" (with an alphabetic shortcut key of "S"), or on some devices, a dedicated + * item called "Search" (with an alphabetic shortcut key of "S"), or on many devices, a dedicated * search button key. - *

    If your application is not inherently searchable, you can also allow the search UI - * to be invoked in a "web search" mode. If the user enters a search term and clicks the - * "Search" button, this will bring the browser to the front and will launch a web-based + *

    If your application is not inherently searchable, the default implementation will cause + * the search UI to be invoked in a "global search" mode known as Quick Search Box. As the user + * types, search suggestions from across the device and the web will be surfaced, and if they + * click the "Search" button, this will bring the browser to the front and will launch a web-based * search. The user will be able to click the "Back" button and return to your application. *

    In general this is implemented by your activity, or the {@link android.app.Activity Activity} - * base class, which captures the search command and invokes the Search Manager to + * base class, which captures the search command and invokes the SearchManager to * display and operate the search UI. You can also cause the search UI to be presented in response * to user keystrokes in your activity (for example, to instantly start filter searching while * viewing a list and typing any key). @@ -124,7 +107,7 @@ import java.util.List; * button or menu item - and invoking the search UI directly.

    11. *
  11. You can provide a type-to-search feature, in which search is invoked automatically * when the user enters any characters.
    12. - *
  12. Even if your application is not inherently searchable, you can allow web search, + *
  13. Even if your application is not inherently searchable, you can allow global search, * via the search key (or even via a search menu item). *
  14. You can disable search entirely. This should only be used in very rare circumstances, * as search is a system-wide feature and users will expect it to be available in all contexts.
    15. @@ -148,21 +131,23 @@ import java.util.List; * setDefaultKeyMode(DEFAULT_KEYS_SEARCH_LOCAL); // search within your activity * setDefaultKeyMode(DEFAULT_KEYS_SEARCH_GLOBAL); // search using platform global search * - *

    How to enable web-based search. In addition to searching within your activity or - * application, you can also use the Search Manager to invoke a platform-global search, typically - * a web search. There are two ways to do this: + *

    How to enable global search with Quick Search Box. In addition to searching within + * your activity or application, you can also use the Search Manager to invoke a platform-global + * search, which uses Quick Search Box to search across the device and the web. There are two ways + * to do this: *

    + *
  15. Simply do nothing and the default implementation of + * {@link android.app.Activity#onSearchRequested} will cause global search to be triggered. + * (You can also always trigger search via a direct call to {@link android.app.Activity#startSearch}. + * This is most useful if you wish to provide local searchability and access to global + * search.)
    16. * - *

    How to disable search from your activity. search is a system-wide feature and users + *

    How to disable search from your activity. Search is a system-wide feature and users * will expect it to be available in all contexts. If your UI design absolutely precludes * launching search, override {@link android.app.Activity#onSearchRequested onSearchRequested} * as shown: @@ -172,7 +157,7 @@ import java.util.List; * return false; * } * - *

    Managing focus and knowing if Search is active. The search UI is not a separate + *

    Managing focus and knowing if search is active. The search UI is not a separate * activity, and when the UI is invoked or dismissed, your activity will not typically be paused, * resumed, or otherwise notified by the methods defined in * Application Fundamentals: @@ -194,17 +179,10 @@ import java.util.List; * the search UI. More details on searchable activities and search intents are provided in the * sections below. * - * - *

    Query-Search Applications

    - * - *

    Query-search applications are those that take a single query (e.g. a search - * string) and present a set of results that may fit. Primary examples include - * web queries, map lookups, or email searches (with the common thread being - * network query dispatch). It may also be the case that certain local searches - * are treated this way. It's up to the application to decide. + * + *

    Implementing Search for Your App

    * - *

    What you need to do: The following steps are necessary in order to - * implement query search. + *

    The following steps are necessary in order to implement search. *

    * - *

    Another feature of suggestions is that they can expose queries or results before the user - * ever visits the application. This reduces the amount of context switching required, and helps - * the user access their data quickly and with less context shifting. In order to provide this - * capability, suggestions are accessed via a - * {@link android.content.ContentProvider Content Provider}. + *

    Once an application is configured to provide search suggestions, those same suggestions can + * easily be made available to the system-wide Quick Search Box, providing faster access to its + * content from on central prominent place. See + * Exposing Search Suggestions to Quick Search + * Box for more details. * *

    The primary form of suggestions is known as queried suggestions and is based on query * text that the user has already typed. This would generally be based on partial matches in @@ -299,7 +262,8 @@ import java.util.List; * available, they should be weighted based on other factors - for example, most recent queries * or most recent results. * - *

    Overview of how suggestions are provided. When the search manager identifies a + *

    Overview of how suggestions are provided. Suggestions are accessed via a + * {@link android.content.ContentProvider Content Provider}. When the search manager identifies a * particular activity as searchable, it will check for certain metadata which indicates that * there is also a source of suggestions. If suggestions are provided, the following steps are * taken. @@ -569,6 +533,11 @@ import java.util.List; * query text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable for user * inspection and editing. * + * + *

    Exposing Search Suggestions to Quick Search Box

    + * + *

    + * * *

    Action Keys

    *