Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fef8cebc authored by Bjorn Bringert's avatar Bjorn Bringert
Browse files

Clean up SearchableInfo API, JavaDoc and formatting 

This change cleans up the JavaDoc in SearchableInfo,
removes trailing whitespace, fixes an if-statement
style violoation, and re-hides some things that were
exposed for Froyo that query deprecated or discouraged
attributes:

SearchableInfo.getSearchButtonText()
SearchableInfo.getLabelId()
SearchableInfo.getIconlId()
class SearchableInfo.ActionKeyInfo
SearchableInfo.findActionKey()

Bug http://b/issue?id=2553524

Change-Id: Iee5521c844f74137166730e523d29ba07ef1856b
parent e2522466

api/current.xml

+0 −127
Original line number Diff line number Diff line
@@ -24544,19 +24544,6 @@ 
 visibility="public"

>

</method>

<method name="findActionKey"

 return="android.app.SearchableInfo.ActionKeyInfo"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<parameter name="keyCode" type="int">

</parameter>

</method>

<method name="getHintId"

 return="int"

 abstract="false"
@@ -24568,17 +24555,6 @@ 
 visibility="public"

>

</method>

<method name="getIconId"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getImeOptions"

 return="int"

 abstract="false"
@@ -24601,17 +24577,6 @@ 
 visibility="public"

>

</method>

<method name="getLabelId"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getSearchActivity"

 return="android.content.ComponentName"

 abstract="false"
@@ -24623,17 +24588,6 @@ 
 visibility="public"

>

</method>

<method name="getSearchButtonText"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getSettingsDescriptionId"

 return="int"

 abstract="false"
@@ -24869,87 +24823,6 @@ 
>

</field>

</class>

<class name="SearchableInfo.ActionKeyInfo"

 extends="java.lang.Object"

 abstract="false"

 static="true"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<implements name="android.os.Parcelable">

</implements>

<method name="describeContents"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getKeyCode"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getQueryActionMsg"

 return="java.lang.String"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getSuggestActionMsg"

 return="java.lang.String"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="getSuggestActionMsgColumn"

 return="java.lang.String"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="writeToParcel"

 return="void"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<parameter name="dest" type="android.os.Parcel">

</parameter>

<parameter name="flags" type="int">

</parameter>

</method>

</class>

<class name="Service"

 extends="android.content.ContextWrapper"

 abstract="true"

core/java/android/app/SearchableInfo.java

+179 −121
Original line number Diff line number Diff line
@@ -38,9 +38,13 @@ import java.io.IOException; 
import java.util.HashMap;



/**

 * Searchability meta-data for an activity.

 * See <a href="SearchManager.html#SearchabilityMetadata">Searchability meta-data</a>

 * for more information.

 * Searchability meta-data for an activity. Only applications that search other applications

 * should need to use this class.

 * See <a href="{@docRoot}guide/topics/search/searchable-config.html">Searchable Configuration</a>

 * for more information about declaring searchability meta-data for your application.

 *

 * @see SearchManager#getSearchableInfo(ComponentName)

 * @see SearchManager#getSearchablesInGlobalSearch()

 */

public final class SearchableInfo implements Parcelable {
@@ -97,11 +101,11 @@ public final class SearchableInfo implements Parcelable { 
    private final int mVoiceLanguageId;           // voiceLanguage

    private final int mVoiceMaxResults;           // voiceMaxResults



    

    /**

     * Retrieve the authority for obtaining search suggestions.

     * Gets the search suggestion content provider authority.

     *

     * @return Returns a string containing the suggestions authority.

     * @return The search suggestions authority, or {@code null} if not set.

     * @see android.R.styleable#Searchable_searchSuggestAuthority

     */

    public String getSuggestAuthority() {

        return mSuggestAuthority;
@@ -117,6 +121,8 @@ public final class SearchableInfo implements Parcelable { 


    /**

     * Gets the component name of the searchable activity.

     *

     * @return A component name, never {@code null}.

     */

    public ComponentName getSearchActivity() {

        return mSearchActivity;
@@ -125,6 +131,8 @@ public final class SearchableInfo implements Parcelable { 
    /**

     * Checks whether the badge should be a text label.

     *

     * @see android.R.styleable#Searchable_searchMode

     *

     * @hide This feature is deprecated, no need to add it to the API.

     */

    public boolean useBadgeLabel() {
@@ -134,6 +142,8 @@ public final class SearchableInfo implements Parcelable { 
    /**

     * Checks whether the badge should be an icon.

     *

     * @see android.R.styleable#Searchable_searchMode

     *

     * @hide This feature is deprecated, no need to add it to the API.

     */

    public boolean useBadgeIcon() {
@@ -142,6 +152,8 @@ public final class SearchableInfo implements Parcelable { 


    /**

     * Checks whether the text in the query field should come from the suggestion intent data.

     *

     * @see android.R.styleable#Searchable_searchMode

     */

    public boolean shouldRewriteQueryFromData() {

        return 0 != (mSearchMode & SEARCH_MODE_QUERY_REWRITE_FROM_DATA);
@@ -149,69 +161,79 @@ public final class SearchableInfo implements Parcelable { 


    /**

     * Checks whether the text in the query field should come from the suggestion title.

     *

     * @see android.R.styleable#Searchable_searchMode

     */

    public boolean shouldRewriteQueryFromText() {

        return 0 != (mSearchMode & SEARCH_MODE_QUERY_REWRITE_FROM_TEXT);

    }



    /**

     * Gets the resource ID of the description string to use for this source in system search

     * Gets the resource id of the description string to use for this source in system search

     * settings, or {@code 0} if none has been specified.

     *

     * @see android.R.styleable#Searchable_searchSettingsDescription

     */

    public int getSettingsDescriptionId() {

        return mSettingsDescriptionId;

    }



    /**

     * Retrieve the path for obtaining search suggestions.

     * Gets the content provider path for obtaining search suggestions.

     * 

     * @return Returns a string containing the suggestions path, or null if not provided.

     * @return The suggestion path, or {@code null} if not set.

     * @see android.R.styleable#Searchable_searchSuggestPath

     */

    public String getSuggestPath() {

        return mSuggestPath;

    }



    /**

     * Retrieve the selection pattern for obtaining search suggestions.  This must

     * include a single ? which will be used for the user-typed characters.

     * Gets the selection for obtaining search suggestions.

     *

     * @return Returns a string containing the suggestions authority.

     * @see android.R.styleable#Searchable_searchSuggestSelection

     */

    public String getSuggestSelection() {

        return mSuggestSelection;

    }



    /**

     * Retrieve the (optional) intent action for use with these suggestions.  This is

     * useful if all intents will have the same action (e.g. "android.intent.action.VIEW").

     * Gets the optional intent action for use with these suggestions. This is

     * useful if all intents will have the same action

     * (e.g. {@link android.content.Intent#ACTION_VIEW})

     *

     * Can be overriden in any given suggestion via the AUTOSUGGEST_COLUMN_INTENT_ACTION column.

     * This can be overriden in any given suggestion using the column

     * {@link SearchManager#SUGGEST_COLUMN_INTENT_ACTION}.

     *

     * @return Returns a string containing the default intent action.

     * @return The default intent action, or {@code null} if not set.

     * @see android.R.styleable#Searchable_searchSuggestIntentAction

     */

    public String getSuggestIntentAction() {

        return mSuggestIntentAction;

    }



    /**

     * Retrieve the (optional) intent data for use with these suggestions.  This is

     * useful if all intents will have similar data URIs (e.g. "android.intent.action.VIEW"), 

     * Gets the optional intent data for use with these suggestions.  This is

     * useful if all intents will have similar data URIs,

     * but you'll likely need to provide a specific ID as well via the column

     * AUTOSUGGEST_COLUMN_INTENT_DATA_ID, which will be appended to the intent data URI.

     * {@link SearchManager#SUGGEST_COLUMN_INTENT_DATA_ID}, which will be appended to the

     * intent data URI.

     * 

     * Can be overriden in any given suggestion via the AUTOSUGGEST_COLUMN_INTENT_DATA column.

     * This can be overriden in any given suggestion using the column

     * {@link SearchManager#SUGGEST_COLUMN_INTENT_DATA}.

     * 

     * @return Returns a string containing the default intent data.

     * @return The default intent data, or {@code null} if not set.

     * @see android.R.styleable#Searchable_searchSuggestIntentData

     */

    public String getSuggestIntentData() {

        return mSuggestIntentData;

    }



    /**

     * Gets the suggestion threshold for use with these suggestions. 

     * Gets the suggestion threshold.

     * 

     * @return The value of the <code>searchSuggestThreshold</code> attribute, 

     *         or 0 if the attribute is not set.

     * @return The suggestion threshold, or {@code 0} if not set.

     * @see android.R.styleable#Searchable_searchSuggestThreshold

     */

    public int getSuggestThreshold() {

        return mSuggestThreshold;
@@ -220,9 +242,6 @@ public final class SearchableInfo implements Parcelable { 
    /**

     * Get the context for the searchable activity.

     *

     * This is fairly expensive so do it on the original scan, or when an app is

     * selected, but don't hang on to the result forever.

     * 

     * @param context You need to supply a context to start with

     * @return Returns a context related to the searchable activity

     * @hide
@@ -250,13 +269,10 @@ public final class SearchableInfo implements Parcelable { 
    /**

     * Get the context for the suggestions provider.

     *

     * This is fairly expensive so do it on the original scan, or when an app is

     * selected, but don't hang on to the result forever.

     * 

     * @param context You need to supply a context to start with

     * @param activityContext If we can determine that the provider and the activity are the

     *        same, we'll just return this one.

     * @return Returns a context related to the context provider

     * @return Returns a context related to the suggestion provider

     * @hide

     */

    public Context getProviderContext(Context context, Context activityContext) {
@@ -264,7 +280,7 @@ public final class SearchableInfo implements Parcelable { 
        if (mSearchActivity.getPackageName().equals(mSuggestProviderPackage)) {

            return activityContext;

        }

        if (mSuggestProviderPackage != null)

        if (mSuggestProviderPackage != null) {

            try {

                theirContext = context.createPackageContext(mSuggestProviderPackage, 0);

            } catch (PackageManager.NameNotFoundException e) {
@@ -272,7 +288,7 @@ public final class SearchableInfo implements Parcelable { 
            } catch (java.lang.SecurityException e) {

                // unexpected, but we deal with this by null-checking theirContext

            }

        

        }

        return theirContext;

    }
@@ -359,10 +375,11 @@ public final class SearchableInfo implements Parcelable { 


    /**

     * Information about an action key in searchability meta-data.

     * See <a href="SearchManager.html#SearchabilityMetadata">Searchability meta-data</a>

     * for more information.

     *

     * @see SearchableInfo#findActionKey(int)

     *

     * @hide This feature is used very little, and on many devices there are no reasonable

     *       keys to use for actions.

     */

    public static class ActionKeyInfo implements Parcelable {
@@ -417,18 +434,34 @@ public final class SearchableInfo implements Parcelable { 
            mSuggestActionMsgColumn = in.readString();

        }



        /**

         * Gets the key code that this action key info is for.

         * @see android.R.styleable#SearchableActionKey_keycode

         */

        public int getKeyCode() {

            return mKeyCode;

        }



        /**

         * Gets the action message to use for queries.

         * @see android.R.styleable#SearchableActionKey_queryActionMsg

         */

        public String getQueryActionMsg() {

            return mQueryActionMsg;

        }



        /**

         * Gets the action message to use for suggestions.

         * @see android.R.styleable#SearchableActionKey_suggestActionMsg

         */

        public String getSuggestActionMsg() {

            return mSuggestActionMsg;

        }



        /**

         * Gets the name of the column to get the suggestion action message from.

         * @see android.R.styleable#SearchableActionKey_suggestActionMsgColumn

         */

        public String getSuggestActionMsgColumn() {

            return mSuggestActionMsgColumn;

        }
@@ -449,7 +482,9 @@ public final class SearchableInfo implements Parcelable { 
     * If any action keys were defined for this searchable activity, look up and return.

     * 

     * @param keyCode The key that was pressed

     * @return Returns the ActionKeyInfo record, or null if none defined

     * @return Returns the action key info, or {@code null} if none defined.

     *

     * @hide ActionKeyInfo is hidden

     */

    public ActionKeyInfo findActionKey(int keyCode) {

        if (mActionKeys == null) {
@@ -566,147 +601,170 @@ public final class SearchableInfo implements Parcelable { 
    }



    /**

     * Return the "label" (user-visible name) of this searchable context.  This must be 

     * accessed using the target (searchable) Activity's resources, not simply the context of the

     * caller.

     * Gets the "label" (user-visible name) of this searchable context. This must be

     * read using the searchable Activity's resources.

     * 

     * @return Returns the resource Id

     * @return A resource id, or {@code 0} if no label was specified.

     * @see android.R.styleable#Searchable_label

     *

     * @hide deprecated functionality

     */

    public int getLabelId() {

        return mLabelId;

    }



    /**

     * Return the resource Id of the hint text.  This must be 

     * accessed using the target (searchable) Activity's resources, not simply the context of the

     * caller.

     * Gets the resource id of the hint text. This must be

     * read using the searchable Activity's resources.

     * 

     * @return Returns the resource Id, or 0 if not specified by this package.

     * @return A resource id, or {@code 0} if no hint was specified.

     * @see android.R.styleable#Searchable_hint

     */

    public int getHintId() {

        return mHintId;

    }



    /**

     * Return the icon Id specified by the Searchable_icon meta-data entry.  This must be 

     * accessed using the target (searchable) Activity's resources, not simply the context of the

     * caller.

     * Gets the icon id specified by the Searchable_icon meta-data entry. This must be

     * read using the searchable Activity's resources.

     * 

     * @return A resource id, or {@code 0} if no icon was specified.

     * @see android.R.styleable#Searchable_icon

     *

     * @return Returns the resource id.

     * @hide deprecated functionality

     */

    public int getIconId() {

        return mIconId;

    }



    /**

     * @return true if android:voiceSearchMode="showVoiceSearchButton"

     * Checks if the searchable activity wants the voice search button to be shown.

     *

     * @see android.R.styleable#Searchable_voiceSearchMode

     */

    public boolean getVoiceSearchEnabled() {

        return 0 != (mVoiceSearchMode & VOICE_SEARCH_SHOW_BUTTON);

    }



    /**

     * @return true if android:voiceSearchMode="launchWebSearch"

     * Checks if voice search should start web search.

     *

     * @see android.R.styleable#Searchable_voiceSearchMode

     */

    public boolean getVoiceSearchLaunchWebSearch() {

        return 0 != (mVoiceSearchMode & VOICE_SEARCH_LAUNCH_WEB_SEARCH);

    }



    /**

     * @return true if android:voiceSearchMode="launchRecognizer"

     * Checks if voice search should start in-app search.

     *

     * @see android.R.styleable#Searchable_voiceSearchMode

     */

    public boolean getVoiceSearchLaunchRecognizer() {

        return 0 != (mVoiceSearchMode & VOICE_SEARCH_LAUNCH_RECOGNIZER);

    }



    /**

     * @return the resource Id of the language model string, if specified in the searchable

     * activity's metadata, or 0 if not specified.  

     * Gets the resource id of the voice search language model string.

     *

     * @return A resource id, or {@code 0} if no language model was specified.

     * @see android.R.styleable#Searchable_voiceLanguageModel

     */

    public int getVoiceLanguageModeId() {

        return mVoiceLanguageModeId;

    }



    /**

     * @return the resource Id of the voice prompt text string, if specified in the searchable

     * activity's metadata, or 0 if not specified.  

     * Gets the resource id of the voice prompt text string.

     *

     * @return A resource id, or {@code 0} if no voice prompt text was specified.

     * @see android.R.styleable#Searchable_voicePromptText

     */

    public int getVoicePromptTextId() {

        return mVoicePromptTextId;

    }



    /**

     * @return the resource Id of the spoken langauge, if specified in the searchable

     * activity's metadata, or 0 if not specified.  

     * Gets the resource id of the spoken language to recognize in voice search.

     *

     * @return A resource id, or {@code 0} if no language was specified.

     * @see android.R.styleable#Searchable_voiceLanguage

     */

    public int getVoiceLanguageId() {

        return mVoiceLanguageId;

    }



    /**

     * The maximum number of voice recognition results to return.

     *

     * @return the max results count, if specified in the searchable

     * activity's metadata, or 0 if not specified.  

     *         activity's metadata, or {@code 0} if not specified.

     * @see android.R.styleable#Searchable_voiceMaxResults

     */

    public int getVoiceMaxResults() {

        return mVoiceMaxResults;

    }



    /**

     * Return the resource Id of replacement text for the "Search" button.

     * Gets the resource id of replacement text for the "Search" button.

     *

     * @return Returns the resource Id, or 0 if not specified by this package.

     * @return A resource id, or {@code 0} if no replacement text was specified.

     * @see android.R.styleable#Searchable_searchButtonText

     * @hide This feature is deprecated, no need to add it to the API.

     */

    public int getSearchButtonText() {

        return mSearchButtonText;

    }



    /**

     * Return the input type as specified in the searchable attributes.  This will default to

     * InputType.TYPE_CLASS_TEXT if not specified (which is appropriate for free text input).

     * Gets the input type as specified in the searchable attributes. This will default to

     * {@link InputType#TYPE_CLASS_TEXT} if not specified (which is appropriate

     * for free text input).

     * 

     * @return the input type

     * @see android.R.styleable#Searchable_inputType

     */

    public int getInputType() {

        return mSearchInputType;

    }



    /**

     * Return the input method options specified in the searchable attributes.

     * This will default to EditorInfo.ACTION_GO if not specified (which is

     * Gets the input method options specified in the searchable attributes.

     * This will default to {@link EditorInfo#IME_ACTION_GO} if not specified (which is

     * appropriate for a search box).

     * 

     * @return the input type

     * @see android.R.styleable#Searchable_imeOptions

     */

    public int getImeOptions() {

        return mSearchImeOptions;

    }



    /**

     * Checks whether the searchable is exported.

     * Checks whether the searchable should be included in global search.

     *

     * @return The value of the <code>exported</code> attribute,

     *         or <code>false</code> if the attribute is not set.

     * @return The value of the {@link android.R.styleable#Searchable_includeInGlobalSearch}

     *         attribute, or {@code false} if the attribute is not set.

     * @see android.R.styleable#Searchable_includeInGlobalSearch

     */

    public boolean shouldIncludeInGlobalSearch() {

        return mIncludeInGlobalSearch;

    }



    /**

     * Checks whether this searchable activity should be invoked after a query returned zero

     * results.

     * Checks whether this searchable activity should be queried for suggestions if a prefix

     * of the query has returned no results.

     *

     * @return The value of the <code>queryAfterZeroResults</code> attribute,

     *         or <code>false</code> if the attribute is not set.

     * @see android.R.styleable#Searchable_queryAfterZeroResults

     */

    public boolean queryAfterZeroResults() {

        return mQueryAfterZeroResults;

    }



    /**

     * Checks whether this searchable activity has auto URL detect turned on.

     * Checks whether this searchable activity has auto URL detection turned on.

     *

     * @return The value of the <code>autoUrlDetect</code> attribute,

     *         or <code>false</code> if the attribute is not set.

     * @see android.R.styleable#Searchable_autoUrlDetect

     */

    public boolean autoUrlDetect() {

        return mAutoUrlDetect;
@@ -727,7 +785,7 @@ public final class SearchableInfo implements Parcelable { 
    };



    /**

     * Instantiate a new SearchableInfo from the data in a Parcel that was

     * Instantiates a new SearchableInfo from the data in a Parcel that was

     * previously written with {@link #writeToParcel(Parcel, int)}.

     *

     * @param in The Parcel containing the previously written SearchableInfo,