From d27b10837525f341eee7d46013e2177b0bad3c60 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Thu, 10 Sep 2009 19:22:48 -0700 Subject: [PATCH] docs only. add Searchable resource information to the Available Resources doc and update some some of the attribute documentation to indicate that the icon label is not recommended. and fixing merge issue... Change-Id: I1b1a62aa9804f4a0bf2f93328dde90b9f7aec50a --- core/java/android/app/SearchManager.java | 24 +- core/res/res/values/attrs.xml | 9 +- .../topics/resources/available-resources.jd | 336 +++++++++++++++++- 3 files changed, 343 insertions(+), 26 deletions(-) diff --git a/core/java/android/app/SearchManager.java b/core/java/android/app/SearchManager.java index 2245562763cfb..7d4e51dfeb690 100644 --- a/core/java/android/app/SearchManager.java +++ b/core/java/android/app/SearchManager.java @@ -768,8 +768,11 @@ import java.util.List; * * * android:icon - * If provided, this icon will be used in place of the label string. This - * is provided in order to present logos or other non-textual banners. + * If provided, this icon will be shown in place of the label above the search box. + * This is a reference to a drawable (icon) resource. Note that the application icon + * is also used as an icon to the left of the search box and you cannot modify this + * behavior, so including the icon attribute is unecessary and this may be + * deprecated in the future. * No * * @@ -778,11 +781,6 @@ import java.util.List; * entered. * No * - * - * android:searchButtonText - * If provided, this text will replace the default text in the "Search" button. - * No - * * * android:searchMode * If provided and non-zero, sets additional modes for control of the search @@ -791,15 +789,17 @@ import java.util.List; * * showSearchLabelAsBadge * If set, this flag enables the display of the search target (label) - * within the search bar. If this flag and showSearchIconAsBadge + * above the search box. If this flag and showSearchIconAsBadge * (see below) are both not set, no badge will be shown. * * showSearchIconAsBadge - * If set, this flag enables the display of the search target (icon) within - * the search bar. If this flag and showSearchLabelAsBadge + * If set, this flag enables the display of the search target (icon) + * above the search box. If this flag and showSearchLabelAsBadge * (see above) are both not set, no badge will be shown. If both flags * are set, showSearchIconAsBadge has precedence and the icon will be - * shown. + * shown. Because the application icon is now used to the left of the + * search box by default, using this search mode is no longer necessary + * and may be deprecated in the future. * * queryRewriteFromData * If set, this flag causes the suggestion column SUGGEST_COLUMN_INTENT_DATA @@ -2000,4 +2000,4 @@ public class SearchManager Thread thread = Thread.currentThread(); Log.d(TAG, msg + " (" + thread.getName() + "-" + thread.getId() + ")"); } -} +} \ No newline at end of file diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml index fd78f83698aa4..b2ba645cc782e 100644 --- a/core/res/res/values/attrs.xml +++ b/core/res/res/values/attrs.xml @@ -2759,9 +2759,11 @@ For a more in-depth discussion of search configuration, please refer to {@link android.app.SearchManager}. --> - +{@link android.app.SearchManager}.

+ +

+ Source file format: + XML file requiring a <?xml version="1.0" encoding="utf-8"?> + declaration, and a root <searchable> element. +

+ +

+ Resource source file location: {@code res/xml/searchable.xml} + (The file name is arbitrary, but standard practice is to use searchable.xml.) +

+ +

+ Compiled resource datatype: + Resource pointer to an xml object. +

+ +

+ Resource reference name: +

+ +
    +
  • + Java: + R.xml.filename. +
    • +
  • + XML: + @[package:]xml/filename (e.g., @xml/searchable). +
    • +
+ +

+ Syntax +

+ +
+<searchable xmlns:android="http://schemas.android.com/apk/res/android
+     android:label="@string/search_label" 
+     ... >
+     <actionkey
+          android:keycode="KEYCODE_CALL"
+          ... >     
+</searchable>
+
+ +
+
+ <searchable> +
+
+ Defines all application search configurations, including settings for text and voice searches + performed within the application. It accepts the following attributes: +
    +
  • + label - Required. This is the name for your application, as it + will appear to the user. This will be visible only if searchMode is set to + "showSearchLabelAsBadge" (see below). +
    • +
  • + hint - This is the text to display in the search text field when no text has + been entered. This is recommended in order to provide context to the search about to be + performed (e.g., "Search the Dictionary"). +
    • +
  • + searchMode - If provided and non-zero, this sets additional modes for control + of the search presentation. The following mode values are accepted: +
      +
    • + showSearchLabelAsBadge - If set, this enables the display of the + search target (label) within the search bar. +
      • +
    • + queryRewriteFromData - If set, this causes the suggestion column + SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query + rewriting. This should only be used when the values in + SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing - + typically, HTTP/HTTPS Uri's. +
      • +
    • + queryRewriteFromText - If set, this causes the suggestion + column SUGGEST_COLUMN_TEXT_1 to be considered as the text for suggestion query + rewriting. This should be used for suggestions in which no query + text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable + for user inspection and editing. +
      • +
    +

    More than one of the above values for searchMode can be used at once. For + example, you can declare two modes at once, like this: + searchMode="queryRewriteFromData|queryRewriteFromText" +

    • +
  • + inputType - If provided, supplies a hint about the type of search text + the user will be entering. For most searches, in which free form text is expected, + this attribute is not needed. See + {@link android.R.attr#inputType} for a list of suitable values for this attribute. +
    • +
  • + imeOptions - If provided, supplies additional options for the input method. + For most searches, in which free form text is expected, this attribute is not needed, + and will default to "actionSearch". See + {@link android.R.attr#imeOptions} for a list of suitable values for this attribute. +
    • +
+ +

If you have defined a content provider to generate search suggestions, you need to + provide some more searchable metadata in order to configure communications with the content + provider. The following are additional {@code <searchable>} attributes for use when + providing search suggestions:

+ +
    +
  • + searchSuggestAuthority - Required to provide search suggestions. + This value must match the authority string provided in the provider section of your manifest. +
    • +
  • + searchSuggestPath - If provided, this path will be inserted in the suggestions + query Uri, after the authority you have provide but before the standard suggestions path. + This is only required if you have a single content provider issuing different types + of suggestions (e.g. for different data types) and you need + a way to disambiguate the suggestions queries when they are received. +
    • +
  • + searchSuggestSelection - If provided, this value will be passed into your + query function as the selection parameter. Typically this will be a WHERE clause for + your database, and will contain a single question mark, which represents the actual query + string that has been typed by the user. However, you can also use any non-null value to simply + trigger the delivery of the query text (via selection arguments), and then use the query + text in any way appropriate for your provider (ignoring the actual text of the selection parameter.) +
    • +
  • + searchSuggestIntentAction - The default Intent action to be used when a user + clicks on a search suggestion. + If provided, and not overridden by the selected suggestion, this value will + be placed in the action field of the {@link android.content.Intent} when the + user clicks a suggestion. +
    • +
  • + searchSuggestIntentData - The default Intent data to be used when a user + clicks on a search suggestion. + If provided, and not overridden by the selected suggestion, this value will be + placed in the data field of the {@link android.content.Intent} when the user clicks + a suggestion. +
    • +
+ +

Beyond providing search suggestions while using your application's local search, you + can also configure your search suggestions to be made available to Quick Search Box, + which will allow users so receive search suggestions from your application content from outside + your application. The following are additional {@code <searchable>} attributes for use when + providing search suggestions to Quick Search Box:

+ +
    +
  • + includeInGlobalSearch - Required to provide search suggestions in + Quick Search Box. If true, this indicates the search suggestions provided by your + application should be included in the globally accessible Quick Search Box. The user must + still enable your application as a searchable item in the system search settings in order + for your suggestions to appear in Quick Search Box. +
    • +
  • + searchSettingsDescription - If provided, this provides a brief description + of the search suggestions that you provide to Quick Search Box, + and will be displayed in the search settings entry for your application. +
    • +
  • + queryAfterZeroResults - Indicates whether a source should be invoked for + supersets of queries it has returned zero results for in the past. For example, if a + source returned zero results for "bo", it would be ignored for "bob". If set to false, + this source will only be ignored for a single session; the next time the search dialog + is invoked, all sources will be queried. The default value is false. +
    • +
  • + searchSuggestThreshold - Indicates the minimum number of characters needed to + trigger a source lookup from Quick Search Box. Only guarantees that a source will not be + queried for anything shorter than the threshold. The default value is 0. +
    • +
+ +

To enable voice search for your Activity, you can add fields to the searchable metadata + that enable and configure voice search. The following are additional {@code <searchable>} + attributes for use when implementing voice search:

+ +
    +
  • + voiceSearchMode - Required to provide voice search + capabilities. + If provided and non-zero, enables voice search. + (Voice search may not be provided by the device, in which case these flags will + have no effect.) The following mode values are accepted: +
      +
    • + showVoiceSearchButton - If set, display a voice search button. This only + takes effect if voice search is available on the device. If set, then "launchWebSearch" + or "launchRecognizer" must also be set. +
      • +
    • + launchWebSearch - If set, the voice search button will take the user directly + to a built-in voice web search activity. Most applications will not use this flag, as + it will take the user away from the activity in which search was invoked. +
      • +
    • + launchRecognizer - If set, the voice search button will take + the user directly to a built-in voice recording activity. This activity + will prompt the user to speak, transcribe the spoken text, and forward the resulting + query text to the searchable activity, just as if the user had typed it into the + search UI and clicked the search button. +
      • +
    +
    • +
  • + voiceLanguageModel - A string constant from + {@link android.speech.RecognizerIntent}. + If provided, this specifies the language model that + should be used by the voice recognition system. See + {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL } for more + information. If not provided, the default value + {@link android.speech.RecognizerIntent#LANGUAGE_MODEL_FREE_FORM } will be used. +
    • +
  • + voicePromptText - A string. If provided, this specifies a prompt + that will be displayed during voice input. If not provided, a default prompt + will be displayed. +
    • +
  • + voiceLanguage - A string constant from {@link java.util.Locale}. + If provided, this specifies the spoken language to be expected. + This is only needed if it is different from the current value of + {@link java.util.Locale#getDefault()}. +
    • +
  • + voiceMaxResults - If provided, enforces the maximum number of results to return, + including the "best" result which will always be provided as the SEARCH intent's primary + query. Must be one or greater. Use EXTRA_RESULTS to get the results from the intent. + If not provided, the recognizer will choose how many results to return. +
    • +
+
+ +
+ <actionkey> +
+
+ Defines a shortcut key for a search action. +
    +
  • + keycode - Required. This attribute denotes the action key + you wish to respond to. Note that not all action keys are actually supported using + this mechanism, as many of them are used for typing, + navigation, or system functions. This will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your + searchable Activity. To examine the key code, use + {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}. + Note that, in addition to the keycode, you must also provide one or more of + the action specifier attributes below. +
    • +
  • + queryActionMsg - If you wish to handle an action key during normal + search query entry, you must define an action string here. This will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is + passed to your searchable Activity. To examine the string, use + {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. +
    • +
  • + suggestActionMsg - If you wish to handle an action key while a + suggestion is being displayed and selected, there are two ways to handle this. + If all of your suggestions can handle the action key, you can simply define + the action message using this attribute. This will be added to the + {@link android.content.Intent#ACTION_SEARCH} Intent that is passed to your + searchable Activity. To examine the string, + use {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. +
    • +
  • + suggestActionMsgColumn - If you wish to handle an action key while + a suggestion is being displayed and selected, but you do not wish to enable + this action key for every suggestion, then you can use this attribute to control + it on a suggestion-by-suggestion basis. First, you must define a column + (and name it here) where your suggestions will include the action string. Then, + in your content provider, you must provide this column, and when desired, + provide data in this column. The search manager will look at your suggestion cursor, + using the string provided here in order to select a column, and will use + that to select a string from the cursor. That string will be added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} + Intent that is passed to your searchable Activity. To examine + the string, use {@link android.content.Intent#getStringExtra + getStringExtra(SearchManager.ACTION_MSG)}. If the data does not exist for the + selection suggestion, the action key will be ignored. +
    • +
+
+
+ + + + +