diff options
Diffstat (limited to 'docs/html/guide/topics/search/searchable-config.jd')
| -rw-r--r-- | docs/html/guide/topics/search/searchable-config.jd | 268 |
1 files changed, 144 insertions, 124 deletions
diff --git a/docs/html/guide/topics/search/searchable-config.jd b/docs/html/guide/topics/search/searchable-config.jd index 71566de..2aa2db6 100644 --- a/docs/html/guide/topics/search/searchable-config.jd +++ b/docs/html/guide/topics/search/searchable-config.jd @@ -14,18 +14,18 @@ parent.link=index.html </div> </div> -<p>In order to utilize the Android search framework and provide a custom search dialog, your +<p>To utilize the Android search framework and provide a custom search dialog, your application must provide a search configuration in the form of an XML resource. This document 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 the companion documents about <a +in terms of its syntax and usage. For more information about how to implement search +features for your application, see the developer guide about <a href="index.html">Search</a>.</p> <dl class="xml"> <dt>file location:</dt> <dd><code>res/xml/<em>filename</em>.xml</code><br/> -The filename will be used as the resource ID.</dd> +Android uses the filename as the resource ID.</dd> <dt>syntax:</dt> <dd> @@ -70,174 +70,187 @@ The filename will be used as the resource ID.</dd> <p class="caps">attributes:</p> <dl class="atn-list"> <dt><code>android:label</code></dt> - <dd><em>String resource</em>. <strong>Required</strong>. This is the name of your application. -It should normally be the same as the name applied to the {@code android:label} attribute of your <a + <dd><em>String resource</em>. (Required.) The name of your application. +It should be the same as the name applied to the {@code android:label} attribute of your <a href="{@docRoot}guide/topics/manifest/activity-element.html#label">{@code <activity>}</a> or <a href="{@docRoot}guide/topics/manifest/application-element.html#label">{@code -<application>}</a> manifest element. This is only visible to the user when you set -<code>android:includeInGlobalSearch</code> "true", in which case, this label is used to identify +<application>}</a> manifest element. This label is only visible to the user when you set +<code>android:includeInGlobalSearch</code> to "true", in which case, this label is used to identify your application as a searchable item in the system's search settings.</dd> + <dt><code>android:hint</code></dt> - <dd><em>String resource</em>. The text to display in the search text field when no text has - been entered. This is recommended in order to provide a hint to the user about what -content is searchable. For consistency among other Android applications, you should format the + <dd><em>String resource</em>. (Recommended.) The text to display in the search text field when +no text has been entered. It provides a hint to the user about what +content is searchable. For consistency with other Android applications, you should format the string for {@code android:hint} as "Search <em><content-or-product></em>". For example, "Search songs and artists" or "Search YouTube".</dd> + <dt><code>android:searchMode</code></dt> - <dd><em>Keyword</em>. Sets additional modes that control the search presentation. -Specifically, the available modes define how the query text in the search dialog's text box -should be rewritten when a suggestion is focused. The following mode values are accepted: + <dd><em>Keyword</em>. Sets additional modes that control the search dialog presentation. +Currently available modes define how the query text that appears in the search dialog +should be rewritten when a custom suggestion receives focus. The following mode values are accepted: <table> <tr><th>Value</th><th>Description</th></tr> <tr> - <td><code>"queryRewriteFromData"</code></td> - <td>If set, this causes the suggestion column - {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} to be considered as the -text for suggestion query - rewriting. This should only be used when the values in - {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user -inspection and editing - - typically, HTTP/HTTPS Uri's.</td> + <td><code>"queryRewriteFromText"</code></td> + <td>Use the value from the {@link android.app.SearchManager#SUGGEST_COLUMN_TEXT_1} +colum to rewrite the query text in the search dialog.</td> </tr> <tr> - <td><code>"queryRewriteFromText"</code></td> - <td>If set, this causes the suggestion - column {@link android.app.SearchManager#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 {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} -values are not suitable - for user inspection and editing.</td> + <td><code>"queryRewriteFromData"</code></td> + <td>Use the value from the + {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column to rewrite the +query text in the search dialog. This should only be used when the values in + {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} are suitable for user +inspection and editing, typically HTTP URI's.</td> </tr> </table> <p>For more information, see the discussion about rewriting the query text in <a href="adding-custom-suggestions.html#RewritingQueryText">Adding Custom Suggestions</a>.</p> </dd> + <dt><code>android:searchButtonText</code></dt> - <dd><em>String resource</em>. The text to display in the button that executes the search. By + <dd><em>String resource</em>. The text to display in the button that executes search. By default, the button shows a search icon (a magnifying glass), which is ideal for -internationalization.</dd> +internationalization, so you should not use this attribute to change the button unless the +behavior is something other than a search (such as a URL request in a web browser).</dd> + <dt><code>android:inputType</code></dt> - <dd><em>Keyword</em>. Defines the type of input method (soft-keyboard) to use with the search -dialog. For most searches, in which free form text is expected, this attribute is not needed and -the default input method should be used. See {@link android.R.attr#inputType} for a list of suitable -values for this attribute.</dd> + <dd><em>Keyword</em>. Defines the type of input method (such as the type of soft keyboard) +to use with the search dialog. For most searches, in which free-form text is expected, you don't +need this attribute. See {@link android.R.attr#inputType} for a list of suitable values for this +attribute.</dd> + <dt><code>android:imeOptions</code></dt> <dd><em>Keyword</em>. 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" (provides the "search" button instead of a carriage -return). See {@link android.R.attr#imeOptions} for a list of suitable values for this attribute. + For most searches, in which free-form text is expected, you don't need this attribute. The +default IME is "actionSearch" (provides the "search" button instead of a carriage +return in the soft keyboard). See {@link android.R.attr#imeOptions} for a list of suitable values +for this attribute. </dd> </dl> + + <h4>Search suggestion attributes</h4> + <p>If you have defined a content provider to generate search suggestions, you need to - define additional attributes in order to configure communications with the Content - Provider. When providing search suggestions, you'll need some of the following + define additional attributes that configure communications with the content + provider. When providing search suggestions, you need some of the following {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> <dt><code>android:searchSuggestAuthority</code></dt> - <dd><em>String</em>. <strong>Required to provide search suggestions</strong>. + <dd><em>String</em>. (Required to provide search suggestions.) This value must match the authority string provided in the {@code android:authorities} -attribute of the {@code <provider>} element.</dd> +attribute of the Android manifest {@code <provider>} element.</dd> + <dt><code>android:searchSuggestPath</code></dt> - <dd><em>String</em>. This path will be used as a portion of the suggestions + <dd><em>String</em>. This path is used as a portion of the suggestions query {@link android.net.Uri}, after the prefix and authority, 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.</dd> + of suggestions (such as for different data types) and you need + a way to disambiguate the suggestions queries when you receive them.</dd> + <dt><code>android:searchSuggestSelection</code></dt> - <dd><em>String</em>. This value will be passed into your - query function as the {@code selection} parameter. Typically this will be a WHERE clause -for your database, and should contain a single question mark, which is a place-holder for 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 the {@code + <dd><em>String</em>. This value is passed into your + query function as the {@code selection} parameter. Typically this is a WHERE clause +for your database, and should contain a single question mark, which is a placeholder for the +actual query string that has been typed by the user (for example, {@code "query=?"}). However, you +can also use any non-null value to trigger the delivery of the query text via the {@code selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd> + <dt><code>android:searchSuggestIntentAction</code></dt> <dd><em>String</em>. The default Intent action to be used when a user - clicks on a search suggestion (such as {@code "android.intent.action.VIEW"}). - If not overridden by the selected suggestion (via the {@link -android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value will - be placed in the action field of the {@link android.content.Intent} when the - user clicks a suggestion.</dd> + clicks on a custom search suggestion (such as {@code "android.intent.action.VIEW"}). + If this is not overridden by the selected suggestion (via the {@link +android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value is placed in the action +field of the {@link android.content.Intent} when the user clicks a suggestion.</dd> + <dt><code>android:searchSuggestIntentData</code></dt> <dd><em>String</em>. The default Intent data to be used when a user - clicks on a search suggestion. + clicks on a custom search suggestion. If not overridden by the selected suggestion (via the {@link -android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value will be +android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is placed in the data field of the {@link android.content.Intent} when the user clicks a suggestion.</dd> + <dt><code>android:searchSuggestThreshold</code></dt> <dd><em>Integer</em>. The minimum number of characters needed to - trigger a suggestion look-up. Only guarantees that a source will not be - queried for anything shorter than the threshold. The default value is 0.</dd> + trigger a suggestion look-up. Only guarantees that the Search Manager will not query your + content provider for anything shorter than the threshold. The default value is 0.</dd> </dl> <p>For more information about the above attributes for search suggestions, see the guides for <a href="adding-recent-query-suggestions.html">Adding Recent Query Suggestions</a> and <a href="adding-custom-suggestions.html">Adding Custom Suggestions</a>.</p> - <p>Beyond providing search suggestions while using your application's search dialog, 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. When providing search suggestions to Quick Search Box, you'll need some of the + + <h4>Quick Search Box attributes</h4> + + <p>To make your custom search suggestions available to Quick Search Box, you need some of the following {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> <dt><code>android:includeInGlobalSearch</code></dt> - <dd><em>Boolean</em>. <strong>Required to provide search suggestions in - Quick Search Box</strong>. "true" if you want your suggestions to be - included in the globally accessible Quick Search Box. Note that 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.</dd> + <dd><em>Boolean</em>. (Required to provide search suggestions in + Quick Search Box.) Set to "true" if you want your suggestions to 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 before + your suggestions will appear in Quick Search Box.</dd> + <dt><code>android:searchSettingsDescription</code></dt> <dd><em>String</em>. Provides a brief description of the search suggestions that you provide -to Quick Search Box, which will be displayed in the searchable items entry for your application. +to Quick Search Box, which is displayed in the searchable items entry for your application. Your description should concisely describe the content that is searchable. For example, "Artists, albums, and tracks" for a music application, or "Saved notes" for a notepad application.</dd> + <dt><code>android:queryAfterZeroResults</code></dt> - <dd><em>Boolean</em>. "true" if you want your content provider to be invoked for - supersets of queries that have returned zero results for in the past. For example, if a - source returned zero results for "bo", it would be ignored for "bob". If "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.</dd> + <dd><em>Boolean</em>. Set to "true" if you want your content provider to be invoked for + supersets of queries that have returned zero results in the past. For example, if +your content provider returned zero results for "bo", it should be requiried for "bob". If set to +"false", supersets are ignored for a single session ("bob" does not invoke a requery). This lasts +only for the life of the search dialog (when the search dialog is reopened, "bo" queries your +content provider again). The default value is false.</dd> </dl> + + <h4>Voice search attributes</h4> + <p>To enable voice search for your search dialog, you'll need some of the following {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> <dt><code>android:voiceSearchMode</code></dt> - <dd><em>Keyword</em>. <strong>Required to provide voice search capabilities</strong>. + <dd><em>Keyword</em>. (Required to provide voice search capabilities.) Enables voice search for the search dialog, with a specific mode for voice search. - (Voice search may not be provided by the device, in which case these flags will + (Voice search may not be provided by the device, in which case these flags have no effect.) The following mode values are accepted: <table> <tr><th>Value</th><th>Description</th></tr> <tr> <td><code>"showVoiceSearchButton"</code></td> - <td>Display a voice search button. This only - takes effect if voice search is available on the device. If set, then either - {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be set + <td>Display a voice search button, if voice search is available on the device. If set, +then either {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be set (separated by the pipe | character).</td> </tr> <tr> <td><code>"launchWebSearch"</code></td> - <td>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.</td> + <td>The voice search button takes the user directly + to a built-in voice web search activity. Most applications don't need this flag, as + it takes the user away from the Activity in which search was invoked.</td> </tr> <tr> <td><code>"launchRecognizer"</code></td> - <td>The voice search button will take + <td>The voice search button takes 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 + prompts the user to speak, transcribes the spoken text, and forwards the resulting + query text to the searchable Activity, just as if the user typed it into the search UI and clicked the search button.</td> </tr> </table> </dd> + <dt><code>android:voiceLanguageModel</code></dt> <dd><em>Keyword</em>. The language model that should be used by the voice recognition system. The following values are accepted: @@ -245,92 +258,99 @@ albums, and tracks" for a music application, or "Saved notes" for a notepad appl <tr><th>Value</th><th>Description</th></tr> <tr> <td><code>"free_form"</code></td> - <td>Use a language model based on free-form speech recognition. This is the -default.</td> + <td>Use free-form speech recognition for dictating queries. This is primarily +optimized for English. This is the default.</td> </tr> <tr> <td><code>"web_search"</code></td> - <td>Use a language model based on web search terms.</td> + <td>Use web-search-term recognition for shorter, search-like phrases. This is +available in more languages than "free_form".</td> </tr> </table> <p>Also see {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL} for more information.</p></dd> + <dt><code>android:voicePromptText</code></dt> <dd><em>String</em>. An additional message to display in the voice input dialog.</dd> + <dt><code>android:voiceLanguage</code></dt> <dd><em>String</em>. The spoken language to be expected, expressed as the string value of -a constants in {@link java.util.Locale} (for example, {@code "de"} for German or {@code "fr"} for -French). This is only needed if it is different from the current value of {@link +a constants in {@link java.util.Locale} (such as {@code "de"} for German or {@code "fr"} for +French). This is needed only if it is different from the current value of {@link java.util.Locale#getDefault() Locale.getDefault()}.</dd> + <dt><code>android:voiceMaxResults</code></dt> <dd><em>Integer</em>. Forces the maximum number of results to return, - including the "best" result which will always be provided as the {@link + including the "best" result which is always provided as the {@link android.content.Intent#ACTION_SEARCH} Intent's primary query. Must be 1 or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS} to get the results from the Intent. - If not provided, the recognizer will choose how many results to return.</dd> + If not provided, the recognizer chooses how many results to return.</dd> </dl> </dd> <!-- end searchable element --> + <dt id="actionkey-element"><code><actionkey></code></dt> - <dd>Defines a shortcut key for a search action, in order to provide special behaviors at the touch -of a button, based on the current query or focused suggestion. For example, the Contacts -application enables the device call key for suggestions. So, when -the user focuses on a search suggestion using the directional controls and then presses the call -key, the application will immediately initiate a phone call to the suggested contact. + <dd>Defines a device key and behavior for a search action. A search action provides a +special behavior at the touch of a button on the device, based on the current query or focused +suggestion. For example, the Contacts application provides a search action to initiate a phone call +to the currenly focused contact suggestion at the press of the CALL button. <p>Not all action keys are available on every device, and not all keys are allowed to be overriden in this way. For example, the "Home" key cannot be used and must always return to the home screen. Also be sure not to define an action key for a key that's needed for typing a search query. This essentially limits the available and reasonable action keys to the call button and menu button. Also note that action keys are not generally discoverable, so you should not provide them as a core user feature.</p> + <p>You must define the <code>android:keycode</code> to define the key and at least one of the +other three attributes in order to define the search action.</p> <p class="caps">attributes:</p> <dl class="atn-list"> <dt><code>android:keycode</code></dt> - <dd><em>String</em>. <strong>Required</strong>. A key code from {@link + <dd><em>String</em>. (Required.) A key code from {@link android.view.KeyEvent} that represents the action key - you wish to respond to (for example {@code "KEYCODE_CALL"}). 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)}. - In addition to the key code, you must also provide one or more of - the action specifier attributes below. Not all action keys -are actually supported using this mechanism, as many of them are used for typing, - navigation, or system functions. Note that although each of the action message elements are -optional, at least one must be present for the action key to have any effect.</dd> + you wish to respond to (for example {@code "KEYCODE_CALL"}). This is 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)}. Not all +keys are supported for a search action, as many of them are used for typing, navigation, or system +functions.</dd> + <dt><code>android:queryActionMsg</code></dt> <dd><em>String</em>. An action message to be sent if the action key is pressed while the -user is simply entering query text. 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 +user is entering query text. This is added to the + {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that the Search Manager + passes to your searchable Activity. To examine the string, use {@link android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}.</dd> + <dt><code>android:suggestActionMsg</code></dt> <dd><em>String</em>. An action message to be sent if the action key is pressed while a - suggestion is focused. This will be added to the - Intent that is passed to your searchable Activity (using the action you've defined for - the suggestion). To examine the string, + suggestion is in focus. This is added to the + Intent that that the Search Manager passes to your searchable Activity (using the action +you've defined for the suggestion). To examine the string, use {@link android.content.Intent#getStringExtra - getStringExtra(SearchManager.ACTION_MSG)}. Note that this should only be used if all your + getStringExtra(SearchManager.ACTION_MSG)}. This should only be used if all your suggestions support this action key. If not all suggestions can handle the same action key, then you must instead use the following {@code android:suggestActionMsgColumn} attribute.</dd> + <dt><code>android:suggestActionMsgColumn</code></dt> <dd><em>String</em>. The name of the column in your content provider that defines the -action message for this action key, which is to be sent if the action key is pressed while a - suggestion is focused. This attribute lets you control the +action message for this action key, which is to be sent if the user presses the action key while a + suggestion is in focus. This attribute lets you control the action key on a suggestion-by-suggestion basis, because, instead of using the {@code android:suggestActionMsg} attribute to define the action message for all suggestions, each entry in -your content provider provides its own action message. First, you must define a column in your +your content provider provides its own action message. + <p>First, you must define a column in your content provider for each suggestion to provide an action message, then provide the name of that -column in this attribute. The search manager will look at your suggestion cursor, - using the string provided here in order to select your action message column, and - then select the action message string from the cursor. That string will be added to the - Intent that is passed to your searchable Activity (using the action you've defined for - suggestions). To examine the string, use {@link +column in this attribute. The Search Manager looks at your suggestion cursor, + using the string provided here to select your action message column, and + then select the action message string from the Cursor. That string is added to the + Intent that the Search Manager passes to your searchable Activity (using the action you've +defined for suggestions). To examine the string, use {@link android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. If the data -does not exist for the selected suggestion, the action key will be ignored.</dd> +does not exist for the selected suggestion, the action key is ignored.</dd> </dl> </dd><!-- end action key --> </dl> |