Android APIs
public class

SearchView

extends LinearLayoutCompat
implements CollapsibleActionView
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.support.v7.widget.LinearLayoutCompat
         ↳ android.support.v7.widget.SearchView

Class Overview

A widget that provides a user interface for the user to enter a search query and submit a request to a search provider. Shows a list of query suggestions or results, if available, and allows the user to pick a suggestion or result to launch into.

Note: This class is included in the support library for compatibility with API level 7 and higher. If you're developing your app for API level 11 and higher only, you should instead use the framework SearchView class.

When the SearchView is used in an ActionBar as an action view, it's collapsed by default, so you must provide an icon for the action.

If you want the search field to always be visible, then call setIconifiedByDefault(false).

Developer Guides

For information about using SearchView, read the Search API guide. Additional information about action views is also available in the <Action Bar API guide

Summary

Nested Classes
interface SearchView.OnCloseListener  
interface SearchView.OnQueryTextListener Callbacks for changes to the query text. 
interface SearchView.OnSuggestionListener Callback interface for selection events on suggestions. 
[Expand]
Inherited XML Attributes
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Constants
From class android.support.v7.widget.LinearLayoutCompat
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
SearchView(Context context)
SearchView(Context context, AttributeSet attrs)
SearchView(Context context, AttributeSet attrs, int defStyleAttr)
Public Methods
int getImeOptions()
Returns the IME options set on the query text field.
int getInputType()
Returns the input type set on the query text field.
int getMaxWidth()
Gets the specified maximum width in pixels, if set.
CharSequence getQuery()
Returns the query string currently in the text field.
CharSequence getQueryHint()
Returns the hint text that will be displayed in the query text field.
CursorAdapter getSuggestionsAdapter()
Returns the adapter used for suggestions, if any.
boolean isIconfiedByDefault()
Returns the default iconified state of the search field.
boolean isIconified()
Returns the current iconified state of the SearchView.
boolean isQueryRefinementEnabled()
Returns whether query refinement is enabled for all items or only specific ones.
boolean isSubmitButtonEnabled()
Returns whether the submit button is enabled when necessary or never displayed.
void onActionViewCollapsed()
Called when this view is collapsed as an action view.
void onActionViewExpanded()
Called when this view is expanded as an action view.
void onWindowFocusChanged(boolean hasWindowFocus)
Called when the window containing this view gains or loses focus.
void setIconified(boolean iconify)
Iconifies or expands the SearchView.
void setIconifiedByDefault(boolean iconified)
Sets the default or resting state of the search field.
void setImeOptions(int imeOptions)
Sets the IME options on the query text field.
void setInputType(int inputType)
Sets the input type on the query text field.
void setMaxWidth(int maxpixels)
Makes the view at most this many pixels wide
void setOnCloseListener(SearchView.OnCloseListener listener)
Sets a listener to inform when the user closes the SearchView.
void setOnQueryTextFocusChangeListener(View.OnFocusChangeListener listener)
Sets a listener to inform when the focus of the query text field changes.
void setOnQueryTextListener(SearchView.OnQueryTextListener listener)
Sets a listener for user actions within the SearchView.
void setOnSearchClickListener(View.OnClickListener listener)
Sets a listener to inform when the search button is pressed.
void setOnSuggestionListener(SearchView.OnSuggestionListener listener)
Sets a listener to inform when a suggestion is focused or clicked.
void setQuery(CharSequence query, boolean submit)
Sets a query string in the text field and optionally submits the query as well.
void setQueryHint(CharSequence hint)
Sets the hint text to display in the query text field.
void setQueryRefinementEnabled(boolean enable)
Specifies if a query refinement button should be displayed alongside each suggestion or if it should depend on the flags set in the individual items retrieved from the suggestions provider.
void setSearchableInfo(SearchableInfo searchable)
Sets the SearchableInfo for this SearchView.
void setSubmitButtonEnabled(boolean enabled)
Enables showing a submit button when the query is non-empty.
void setSuggestionsAdapter(CursorAdapter adapter)
You can set a custom adapter if you wish.
Protected Methods
void onDetachedFromWindow()
This is called when the view is detached from a window.
void onMeasure(int widthMeasureSpec, int heightMeasureSpec)

Measure the view and its content to determine the measured width and the measured height.

void onRestoreInstanceState(Parcelable state)
Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState().
Parcelable onSaveInstanceState()
Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state.
[Expand]
Inherited Methods
From class android.support.v7.widget.LinearLayoutCompat
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.view.ViewParent
From interface android.view.ViewManager
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.accessibility.AccessibilityEventSource
From interface android.support.v7.view.CollapsibleActionView

Public Constructors

public SearchView (Context context)

Parameters
context Context

public SearchView (Context context, AttributeSet attrs)

Parameters
context Context
attrs AttributeSet

public SearchView (Context context, AttributeSet attrs, int defStyleAttr)

Parameters
context Context
attrs AttributeSet
defStyleAttr int

Public Methods

public int getImeOptions ()

Returns the IME options set on the query text field.

Returns
int the ime options

See also:

public int getInputType ()

Returns the input type set on the query text field.

Returns
int the input type

public int getMaxWidth ()

Gets the specified maximum width in pixels, if set. Returns zero if no maximum width was specified.

Returns
int the maximum width of the view

public CharSequence getQuery ()

Returns the query string currently in the text field.

Returns
CharSequence the query string

public CharSequence getQueryHint ()

Returns the hint text that will be displayed in the query text field.

The displayed query hint is chosen in the following order:

  1. Non-null value set with setQueryHint(CharSequence)
  2. Value specified in XML using app:queryHint
  3. Valid string resource ID exposed by the SearchableInfo via getHintId()
  4. Default hint provided by the theme against which the view was inflated

Returns
CharSequence the displayed query hint text, or null if none set

public CursorAdapter getSuggestionsAdapter ()

Returns the adapter used for suggestions, if any.

Returns
CursorAdapter the suggestions adapter

public boolean isIconfiedByDefault ()

Returns the default iconified state of the search field.

Returns
boolean

public boolean isIconified ()

Returns the current iconified state of the SearchView.

Returns
boolean true if the SearchView is currently iconified, false if the search field is fully visible.

public boolean isQueryRefinementEnabled ()

Returns whether query refinement is enabled for all items or only specific ones.

Returns
boolean true if enabled for all items, false otherwise.

public boolean isSubmitButtonEnabled ()

Returns whether the submit button is enabled when necessary or never displayed.

Returns
boolean whether the submit button is enabled automatically when necessary

public void onActionViewCollapsed ()

Called when this view is collapsed as an action view. See collapseActionView(android.view.MenuItem).

public void onActionViewExpanded ()

Called when this view is expanded as an action view. See expandActionView(android.view.MenuItem).

public void onWindowFocusChanged (boolean hasWindowFocus)

Called when the window containing this view gains or loses focus. Note that this is separate from view focus: to receive key events, both your view and its window must have focus. If a window is displayed on top of yours that takes input focus, then your own window will lose focus but the view focus will remain unchanged.

Parameters
hasWindowFocus boolean: True if the window containing this view now has focus, false otherwise.

public void setIconified (boolean iconify)

Iconifies or expands the SearchView. Any query text is cleared when iconified. This is a temporary state and does not override the default iconified state set by setIconifiedByDefault(boolean). If the default state is iconified, then a false here will only be valid until the user closes the field. And if the default state is expanded, then a true here will only clear the text field and not close it.

Parameters
iconify boolean: a true value will collapse the SearchView to an icon, while a false will expand it.

public void setIconifiedByDefault (boolean iconified)

Sets the default or resting state of the search field. If true, a single search icon is shown by default and expands to show the text field and other buttons when pressed. Also, if the default state is iconified, then it collapses to that state when the close button is pressed. Changes to this property will take effect immediately.

The default value is true.

Parameters
iconified boolean: whether the search field should be iconified by default

public void setImeOptions (int imeOptions)

Sets the IME options on the query text field.

Parameters
imeOptions int: the options to set on the query text field

See also:

public void setInputType (int inputType)

Sets the input type on the query text field.

Parameters
inputType int: the input type to set on the query text field

See also:

public void setMaxWidth (int maxpixels)

Makes the view at most this many pixels wide

Parameters
maxpixels int

public void setOnCloseListener (SearchView.OnCloseListener listener)

Sets a listener to inform when the user closes the SearchView.

Parameters
listener SearchView.OnCloseListener: the listener to call when the user closes the SearchView.

public void setOnQueryTextFocusChangeListener (View.OnFocusChangeListener listener)

Sets a listener to inform when the focus of the query text field changes.

Parameters
listener View.OnFocusChangeListener: the listener to inform of focus changes.

public void setOnQueryTextListener (SearchView.OnQueryTextListener listener)

Sets a listener for user actions within the SearchView.

Parameters
listener SearchView.OnQueryTextListener: the listener object that receives callbacks when the user performs actions in the SearchView such as clicking on buttons or typing a query.

public void setOnSearchClickListener (View.OnClickListener listener)

Sets a listener to inform when the search button is pressed. This is only relevant when the text field is not visible by default. Calling setIconified(false) can also cause this listener to be informed.

Parameters
listener View.OnClickListener: the listener to inform when the search button is clicked or the text field is programmatically de-iconified.

public void setOnSuggestionListener (SearchView.OnSuggestionListener listener)

Sets a listener to inform when a suggestion is focused or clicked.

Parameters
listener SearchView.OnSuggestionListener: the listener to inform of suggestion selection events.

public void setQuery (CharSequence query, boolean submit)

Sets a query string in the text field and optionally submits the query as well.

Parameters
query CharSequence: the query string. This replaces any query text already present in the text field.
submit boolean: whether to submit the query right now or only update the contents of text field.

public void setQueryHint (CharSequence hint)

Sets the hint text to display in the query text field. This overrides any hint specified in the SearchableInfo.

This value may be specified as an empty string to prevent any query hint from being displayed.

Parameters
hint CharSequence: the hint text to display or null to clear

public void setQueryRefinementEnabled (boolean enable)

Specifies if a query refinement button should be displayed alongside each suggestion or if it should depend on the flags set in the individual items retrieved from the suggestions provider. Clicking on the query refinement button will replace the text in the query text field with the text from the suggestion. This flag only takes effect if a SearchableInfo has been specified with setSearchableInfo(SearchableInfo) and not when using a custom adapter.

Parameters
enable boolean: true if all items should have a query refinement button, false if only those items that have a query refinement flag set should have the button.

public void setSearchableInfo (SearchableInfo searchable)

Sets the SearchableInfo for this SearchView. Properties in the SearchableInfo are used to display labels, hints, suggestions, create intents for launching search results screens and controlling other affordances such as a voice button.

Parameters
searchable SearchableInfo: a SearchableInfo can be retrieved from the SearchManager, for a specific activity or a global search provider.

public void setSubmitButtonEnabled (boolean enabled)

Enables showing a submit button when the query is non-empty. In cases where the SearchView is being used to filter the contents of the current activity and doesn't launch a separate results activity, then the submit button should be disabled.

Parameters
enabled boolean: true to show a submit button for submitting queries, false if a submit button is not required.

public void setSuggestionsAdapter (CursorAdapter adapter)

You can set a custom adapter if you wish. Otherwise the default adapter is used to display the suggestions from the suggestions provider associated with the SearchableInfo.

Parameters
adapter CursorAdapter

Protected Methods

protected void onDetachedFromWindow ()

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

Measure the view and its content to determine the measured width and the measured height. This method is invoked by measure(int, int) and should be overridden by subclasses to provide accurate and efficient measurement of their contents.

CONTRACT: When overriding this method, you must call setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by measure(int, int). Calling the superclass' onMeasure(int, int) is a valid use.

The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override onMeasure(int, int) to provide better measurements of their content.

If this method is overridden, it is the subclass's responsibility to make sure the measured height and width are at least the view's minimum height and width (getSuggestedMinimumHeight() and getSuggestedMinimumWidth()).

Parameters
widthMeasureSpec int: horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.
heightMeasureSpec int: vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.

protected void onRestoreInstanceState (Parcelable state)

Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState(). This function will never be called with a null state.

Parameters
state Parcelable: The frozen state that had previously been returned by onSaveInstanceState().

protected Parcelable onSaveInstanceState ()

Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state. This state should only contain information that is not persistent or can not be reconstructed later. For example, you will never store your current position on screen because that will be computed again when a new instance of the view is placed in its view hierarchy.

Some examples of things you may store here: the current cursor position in a text view (but usually not the text itself since that is stored in a content provider or other persistent storage), the currently selected item in a list view.

Returns
Parcelable Returns a Parcelable object containing the view's current dynamic state, or null if there is nothing interesting to save. The default implementation returns null.