ActionBar SearchView's default hint shouldn't override SearchableInfo

Moves the queryHint to defaultQueryHint, specifies the override order
as queryHint > SearchableInfo > defaultQueryHint.

Cleans up annotations and comments for several related methods.

Bug: 20614122
Change-Id: Ib58ec309e6814cd512df147d789ec0cd546018af

3 files changed, 52 insertions, 44 deletions

diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 5eacce3..c93d796 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -374,24 +374,30 @@ public abstract class Context {
     }
 
     /**
-     * Return a localized string from the application's package's
+     * Returns a localized string from the application's package's
      * default string table.
      *
      * @param resId Resource id for the string
+     * @return The string data associated with the resource, stripped of styled
+     *         text information.
      */
+    @NonNull
     public final String getString(@StringRes int resId) {
         return getResources().getString(resId);
     }
 
     /**
-     * Return a localized formatted string from the application's package's
+     * Returns a localized formatted string from the application's package's
      * default string table, substituting the format arguments as defined in
      * {@link java.util.Formatter} and {@link java.lang.String#format}.
      *
      * @param resId Resource id for the format string
-     * @param formatArgs The format arguments that will be used for substitution.
+     * @param formatArgs The format arguments that will be used for
+     *                   substitution.
+     * @return The string data associated with the resource, formatted and
+     *         stripped of styled text information.
      */
-
+    @NonNull
     public final String getString(@StringRes int resId, Object... formatArgs) {
         return getResources().getString(resId, formatArgs);
     }
diff --git a/core/java/android/content/res/Resources.java b/core/java/android/content/res/Resources.java
index 334d180..6e77e33 100644
--- a/core/java/android/content/res/Resources.java
+++ b/core/java/android/content/res/Resources.java
@@ -393,10 +393,11 @@ public class Resources {
      * @throws NotFoundException Throws NotFoundException if the given ID does not exist.
      *
      * @return String The string data associated with the resource,
-     * stripped of styled text information.
+     *         stripped of styled text information.
      */
+    @NonNull
     public String getString(@StringRes int id) throws NotFoundException {
-        CharSequence res = getText(id);
+        final CharSequence res = getText(id);
         if (res != null) {
             return res.toString();
         }
@@ -421,11 +422,11 @@ public class Resources {
      * @throws NotFoundException Throws NotFoundException if the given ID does not exist.
      *
      * @return String The string data associated with the resource,
-     * stripped of styled text information.
+     *         stripped of styled text information.
      */
-    public String getString(@StringRes int id, Object... formatArgs)
-            throws NotFoundException {
-        String raw = getString(id);
+    @NonNull
+    public String getString(@StringRes int id, Object... formatArgs) throws NotFoundException {
+        final String raw = getString(id);
         return String.format(mConfiguration.locale, raw, formatArgs);
     }
 
diff --git a/core/java/android/widget/SearchView.java b/core/java/android/widget/SearchView.java
index bbf120a..088adbb 100644
--- a/core/java/android/widget/SearchView.java
+++ b/core/java/android/widget/SearchView.java
@@ -18,6 +18,7 @@ package android.widget;
 
 import static android.widget.SuggestionsAdapter.getColumnString;
 
+import android.annotation.Nullable;
 import android.app.PendingIntent;
 import android.app.SearchManager;
 import android.app.SearchableInfo;
@@ -120,6 +121,8 @@ public class SearchView extends LinearLayout implements CollapsibleActionView {
     private final Intent mVoiceWebSearchIntent;
     private final Intent mVoiceAppSearchIntent;
 
+    private final CharSequence mDefaultQueryHint;
+
     private OnQueryTextListener mOnQueryChangeListener;
     private OnCloseListener mOnCloseListener;
     private OnFocusChangeListener mOnQueryTextFocusChangeListener;
@@ -329,10 +332,8 @@ public class SearchView extends LinearLayout implements CollapsibleActionView {
             setMaxWidth(maxWidth);
         }
 
-        final CharSequence queryHint = a.getText(R.styleable.SearchView_queryHint);
-        if (!TextUtils.isEmpty(queryHint)) {
-            setQueryHint(queryHint);
-        }
+        mDefaultQueryHint = a.getText(R.styleable.SearchView_defaultQueryHint);
+        mQueryHint = a.getText(R.styleable.SearchView_queryHint);
 
         final int imeOptions = a.getInt(R.styleable.SearchView_imeOptions, -1);
         if (imeOptions != -1) {
@@ -570,36 +571,48 @@ public class SearchView extends LinearLayout implements CollapsibleActionView {
     }
 
     /**
-     * Sets the hint text to display in the query text field. This overrides any hint specified
-     * in the SearchableInfo.
-     *
-     * @param hint the hint text to display
+     * Sets the hint text to display in the query text field. This overrides
+     * any hint specified in the {@link SearchableInfo}.
+     * <p>
+     * This value may be specified as an empty string to prevent any query hint
+     * from being displayed.
      *
+     * @param hint the hint text to display or {@code null} to clear
      * @attr ref android.R.styleable#SearchView_queryHint
      */
-    public void setQueryHint(CharSequence hint) {
+    public void setQueryHint(@Nullable CharSequence hint) {
         mQueryHint = hint;
         updateQueryHint();
     }
 
     /**
-     * Gets the hint text to display in the query text field.
-     * @return the query hint text, if specified, null otherwise.
+     * Returns the hint text that will be displayed in the query text field.
+     * <p>
+     * The displayed query hint is chosen in the following order:
+     * <ol>
+     * <li>Non-null value set with {@link #setQueryHint(CharSequence)}
+     * <li>Value specified in XML using
+     *     {@link android.R.styleable#SearchView_queryHint android:queryHint}
+     * <li>Valid string resource ID exposed by the {@link SearchableInfo} via
+     *     {@link SearchableInfo#getHintId()}
+     * <li>Default hint provided by the theme against which the view was
+     *     inflated
+     * </ol>
      *
+     * @return the displayed query hint text, or {@code null} if none set
      * @attr ref android.R.styleable#SearchView_queryHint
      */
+    @Nullable
     public CharSequence getQueryHint() {
+        final CharSequence hint;
         if (mQueryHint != null) {
-            return mQueryHint;
-        } else if (mSearchable != null) {
-            CharSequence hint = null;
-            int hintId = mSearchable.getHintId();
-            if (hintId != 0) {
-                hint = getContext().getString(hintId);
-            }
-            return hint;
+            hint = mQueryHint;
+        } else if (mSearchable != null && mSearchable.getHintId() != 0) {
+            hint = getContext().getText(mSearchable.getHintId());
+        } else {
+            hint = mDefaultQueryHint;
         }
-        return null;
+        return hint;
     }
 
     /**
@@ -1113,20 +1126,8 @@ public class SearchView extends LinearLayout implements CollapsibleActionView {
     }
 
     private void updateQueryHint() {
-        if (mQueryHint != null) {
-            mSearchSrcTextView.setHint(getDecoratedHint(mQueryHint));
-        } else if (mSearchable != null) {
-            CharSequence hint = null;
-            int hintId = mSearchable.getHintId();
-            if (hintId != 0) {
-                hint = getContext().getString(hintId);
-            }
-            if (hint != null) {
-                mSearchSrcTextView.setHint(getDecoratedHint(hint));
-            }
-        } else {
-            mSearchSrcTextView.setHint(getDecoratedHint(""));
-        }
+        final CharSequence hint = getQueryHint();
+        mSearchSrcTextView.setHint(getDecoratedHint(hint == null ? "" : hint));
     }
 
     /**