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
diff --git a/core/java/android/app/SearchManager.java b/core/java/android/app/SearchManager.java
index 2245562..7d4e51d 100644
--- a/core/java/android/app/SearchManager.java
+++ b/core/java/android/app/SearchManager.java
@@ -768,8 +768,11 @@
* </tr>
*
* <tr><th>android:icon</th>
- * <td>If provided, this icon will be used <i>in place</i> of the label string. This
- * is provided in order to present logos or other non-textual banners.</td>
+ * <td>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.</td>
* <td align="center">No</td>
* </tr>
*
@@ -778,11 +781,6 @@
* entered.</td>
* <td align="center">No</td>
* </tr>
- *
- * <tr><th>android:searchButtonText</th>
- * <td>If provided, this text will replace the default text in the "Search" button.</td>
- * <td align="center">No</td>
- * </tr>
*
* <tr><th>android:searchMode</th>
* <td>If provided and non-zero, sets additional modes for control of the search
@@ -791,15 +789,17 @@
* <tbody>
* <tr><th>showSearchLabelAsBadge</th>
* <td>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.</td>
* </tr>
* <tr><th>showSearchIconAsBadge</th>
- * <td>If set, this flag enables the display of the search target (icon) within
- * the search bar. If this flag and showSearchLabelAsBadge
+ * <td>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.</td>
+ * 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.</td>
* </tr>
* <tr><th>queryRewriteFromData</th>
* <td>If set, this flag causes the suggestion column SUGGEST_COLUMN_INTENT_DATA
@@ -2000,4 +2000,4 @@
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 fd78f83..b2ba645 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}. -->
<declare-styleable name="Searchable">
- <!-- If provided, this icon will be shown in place of the label. It is typically used
- in order to identify a searchable application via a logo or branding, instead of
- plain text. This is a reference to a drawable (icon) resource.
+ <!-- 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.
<i>Optional attribute.</i> -->
<attr name="icon" />
<!-- This is the user-displayed name of the searchable activity. <i>Required
@@ -3330,4 +3332,3 @@
</resources>
-
diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd
index 2a6a6ac..0dfc625 100644
--- a/docs/html/guide/topics/resources/available-resources.jd
+++ b/docs/html/guide/topics/resources/available-resources.jd
@@ -36,6 +36,7 @@
</ol>
</li>
<li><a href="#stylesandthemes">Styles and Themes</a></li>
+ <li><a href="#Searchable">Searchable</a></li>
</ol>
</div>
@@ -86,7 +87,7 @@
<code><color></code> tags.
</p>
<p>
- <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary)
+ <strong>Resource source file location</strong>: {@code res/values/<em>colors</em>.xml} (File name is arbitrary.)
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a Java int.
@@ -183,7 +184,7 @@
<strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags.
</p>
<p>
- <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary)
+ <strong>Resource source file location</strong>: {@code res/values/<em>strings</em>.xml} (File name is arbitrary.)
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence.
@@ -338,8 +339,8 @@
<code><resources></code> element containing one or more
<code><dimen></code> tags.</p>
-<p><strong>Resource source file location</strong>: res/values/dimens.xml (File
-name is arbitrary; standard practice is to put all dimensions in one file
+<p><strong>Resource source file location</strong>: {@code res/values/dimens.xml} (File
+name is arbitrary, but standard practice is to put all dimensions in one file
devoted to dimensions.)</p>
<p><strong>Compiled resource datatype:</strong> Resource pointer to a
dimension.</p>
@@ -424,7 +425,7 @@
<strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file.
</p>
<p>
- <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif.
+ <strong>Resource file location</strong>: {@code res/drawable/<em>some_file</em>.png}
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}.
@@ -453,7 +454,8 @@
<code><resources></code> element containing one or more
<code><drawable></code> tags.</p>
<p>
- <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.)
+ <strong>Resource source file location</strong>: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable
+ items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.)
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}.
@@ -540,7 +542,7 @@
<strong>Source file format:</strong> PNG — one resource per file
</p>
<p>
- <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png)
+ <strong>Resource source file location</strong>: {@code res/drawable/<em>some_name</em>.9.png} (Filename must end in {@code .9.png})
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}.
@@ -573,7 +575,7 @@
<strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration
</p>
<p>
- <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml
+ <strong>Resource file location</strong>: {@code res/anim/<em>some_file</em>.xml}
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}.
@@ -1055,7 +1057,7 @@
<strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags.
</p>
<p>
- <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary).
+ <strong>Resource file location</strong>: {@code res/values/<em>attrs</em>.xml} (File name is arbitrary.)
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource.
@@ -1084,7 +1086,7 @@
<strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags.
</p>
<p>
- <strong>Resource source file location</strong>: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml.
+ <strong>Resource source file location</strong>: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.)
</p>
<p>
<strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence.
@@ -1133,3 +1135,317 @@
<p>For examples of how to declare and apply styles and themes, read
<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>
+
+
+
+<h2 id="Searchable">Searchable</h2>
+
+<p>To make search appear to the user as a seamless system-wide feature, the Android framework
+offers APIs that let applications 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 shown as the user types.</p>
+
+<p>In order to utilize the Android search framework, an application must provide a search configuration
+in the form of an XML resource.
+This section describes the search configuration XML in terms of its syntax and usage. For a more
+complete discussion about how to implement search features for your application, see
+<!-- <a href="{@docRoot}guide/topics/search/index.html">Search</a> -->
+{@link android.app.SearchManager}.</p>
+
+<p>
+ <strong>Source file format:</strong>
+ XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code>
+ declaration, and a root <code><searchable></code> element.
+</p>
+
+<p>
+ <strong>Resource source file location</strong>: {@code res/xml/searchable.xml}
+ (The file name is arbitrary, but standard practice is to use searchable.xml.)
+</p>
+
+<p>
+ <strong>Compiled resource datatype:</strong>
+ Resource pointer to an xml object.
+</p>
+
+<p>
+ <strong>Resource reference name:</strong>
+</p>
+
+<ul>
+ <li>
+ <strong>Java:</strong>
+ <code>R.xml.<em>filename</em></code>.
+ </li>
+ <li>
+ <strong>XML:</strong>
+ <code>@[<em>package</em>:]xml/<em>filename</em></code> (e.g., <code>@xml/searchable</code>).
+ </li>
+</ul>
+
+<p>
+ <strong>Syntax</strong>
+</p>
+
+<pre>
+<searchable xmlns:android="http://schemas.android.com/apk/res/android
+ android:label="@string/search_label"
+ ... >
+ <em><actionkey
+ android:keycode="KEYCODE_CALL"
+ ... ></em>
+</searchable>
+</pre>
+
+<dl>
+ <dt>
+ <searchable>
+ </dt>
+ <dd>
+ Defines all application search configurations, including settings for text and voice searches
+ performed within the application. It accepts the following attributes:
+ <ul>
+ <li>
+ <em>label</em> - <strong>Required</strong>. This is the name for your application, as it
+ will appear to the user. This will be visible only if <em>searchMode</em> is set to
+ "showSearchLabelAsBadge" (see below).
+ </li>
+ <li>
+ <em>hint</em> - 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").
+ </li>
+ <li>
+ <em>searchMode</em> - If provided and non-zero, this sets additional modes for control
+ of the search presentation. The following mode values are accepted:
+ <ul>
+ <li>
+ <em>showSearchLabelAsBadge</em> - If set, this enables the display of the
+ search target (label) within the search bar.
+ </li>
+ <li>
+ <em>queryRewriteFromData</em> - 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.
+ </li>
+ <li>
+ <em>queryRewriteFromText</em> - 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.
+ </li>
+ </ul>
+ <p>More than one of the above values for <em>searchMode</em> can be used at once. For
+ example, you can declare two modes at once, like this:
+ <code>searchMode="queryRewriteFromData|queryRewriteFromText"</code>
+ </li>
+ <li>
+ <em>inputType</em> - 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.
+ </li>
+ <li>
+ <em>imeOptions</em> - 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.
+ </li>
+ </ul>
+
+ <p>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:</p>
+
+ <ul>
+ <li>
+ <em>searchSuggestAuthority</em> - <strong>Required to provide search suggestions</strong>.
+ This value must match the authority string provided in the provider section of your manifest.
+ </li>
+ <li>
+ <em>searchSuggestPath</em> - 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.
+ </li>
+ <li>
+ <em>searchSuggestSelection</em> - 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.)
+ </li>
+ <li>
+ <em>searchSuggestIntentAction</em> - 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.
+ </li>
+ <li>
+ <em>searchSuggestIntentData</em> - 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.
+ </li>
+ </ul>
+
+ <p>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:</p>
+
+ <ul>
+ <li>
+ <em>includeInGlobalSearch</em> - <strong>Required to provide search suggestions in
+ Quick Search Box</strong>. 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.
+ </li>
+ <li>
+ <em>searchSettingsDescription</em> - 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.
+ </li>
+ <li>
+ <em>queryAfterZeroResults</em> - 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.
+ </li>
+ <li>
+ <em>searchSuggestThreshold</em> - 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.
+ </li>
+ </ul>
+
+ <p>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:</p>
+
+ <ul>
+ <li>
+ <em>voiceSearchMode</em> - <strong>Required to provide voice search
+ capabilities</strong>.
+ 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:
+ <ul>
+ <li>
+ <em>showVoiceSearchButton</em> - 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.
+ </li>
+ <li>
+ <em>launchWebSearch</em> - 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.
+ </li>
+ <li>
+ <em>launchRecognizer</em> - 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.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <em>voiceLanguageModel</em> - 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.
+ </li>
+ <li>
+ <em>voicePromptText</em> - A string. If provided, this specifies a prompt
+ that will be displayed during voice input. If not provided, a default prompt
+ will be displayed.
+ </li>
+ <li>
+ <em>voiceLanguage</em> - 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()}.
+ </li>
+ <li>
+ <em>voiceMaxResults</em> - 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.
+ </li>
+ </ul>
+ </dd>
+
+ <dt>
+ <actionkey>
+ </dt>
+ <dd>
+ Defines a shortcut key for a search action.
+ <ul>
+ <li>
+ <em>keycode</em> - <strong>Required</strong>. 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.
+ </li>
+ <li>
+ <em>queryActionMsg</em> - 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)}.
+ </li>
+ <li>
+ <em>suggestActionMsg</em> - 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)}.
+ </li>
+ <li>
+ <em>suggestActionMsgColumn</em> - 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.
+ </li>
+ </ul>
+ </dd>
+</dl>
+
+
+
+
+
