Merge change 24641 into donut
* changes:
docs only. change the japanese homepage Market link to go to the Market dev site instead of the English market promo site
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>
+
+
+
+
+