SearchView

open class SearchView : LinearLayoutCompat, CollapsibleActionView
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ androidx.appcompat.widget.LinearLayoutCompat
   ↳ androidx.appcompat.widget.SearchView

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 android.widget.SearchView class.

When the SearchView is used in an androidx.appcompat.app.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).

Summary

Nested classes

abstract

abstract

Callbacks for changes to the query text.

abstract

Callback interface for selection events on suggestions.

Inherited constants

Public constructors

<init>(@NonNull context: Context)

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?)

<init>(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int)

Public methods

open Unit

open Int

Returns the IME options set on the query text field.

open Int

Returns the input type set on the query text field.

open Int

Gets the specified maximum width in pixels, if set.

open CharSequence!

Returns the query string currently in the text field.

open CharSequence?

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

open CursorAdapter!

Returns the adapter used for suggestions, if any.

open Boolean

Returns the default iconified state of the search field.

open Boolean

Returns the current iconified state of the SearchView.

open Boolean

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

open Boolean

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

open Unit

Called when this view is collapsed as an action view.

open Unit

Called when this view is expanded as an action view.

open Unit
onWindowFocusChanged(hasWindowFocus: Boolean)

open Boolean
requestFocus(direction: Int, previouslyFocusedRect: Rect!)

open Unit

Iconifies or expands the SearchView.

open Unit

Sets the default or resting state of the search field.

open Unit
setImeOptions(imeOptions: Int)

Sets the IME options on the query text field.

open Unit
setInputType(inputType: Int)

Sets the input type on the query text field.

open Unit
setMaxWidth(maxpixels: Int)

Makes the view at most this many pixels wide android.R.attr#maxWidth

open Unit

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

open Unit

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

open Unit

Sets a listener for user actions within the SearchView.

open Unit

Sets a listener to inform when the search button is pressed.

open Unit

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

open Unit
setQuery(query: CharSequence!, submit: Boolean)

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

open Unit
setQueryHint(@Nullable hint: CharSequence?)

Sets the hint text to display in the query text field.

open Unit

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.

open Unit

Sets the SearchableInfo for this SearchView.

open Unit

Enables showing a submit button when the query is non-empty.

open Unit

You can set a custom adapter if you wish.

Protected methods

open Unit

open Unit
onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int)

open Unit
onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int)

open Unit

open Parcelable!

Inherited functions

Public constructors

<init>

SearchView(@NonNull context: Context)

<init>

SearchView(@NonNull context: Context, @Nullable attrs: AttributeSet?)

<init>

SearchView(@NonNull context: Context, @Nullable attrs: AttributeSet?, defStyleAttr: Int)

Public methods

clearFocus

open fun clearFocus(): Unit

getImeOptions

open fun getImeOptions(): Int

Returns the IME options set on the query text field.

Return
Int: the ime options

getInputType

open fun getInputType(): Int

Returns the input type set on the query text field.

Return
Int: the input type android.R.attr#inputType

getMaxWidth

open fun getMaxWidth(): Int

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

Return
Int: the maximum width of the view android.R.attr#maxWidth

getQuery

open fun getQuery(): CharSequence!

Returns the query string currently in the text field.

Return
CharSequence!: the query string

getQueryHint

@Nullable open fun getQueryHint(): CharSequence?

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 SearchableInfo#getHintId()
  4. Default hint provided by the theme against which the view was inflated
Return
CharSequence?: the displayed query hint text, or null if none set androidx.appcompat.R.attr#queryHint

getSuggestionsAdapter

open fun getSuggestionsAdapter(): CursorAdapter!

Returns the adapter used for suggestions, if any.

Return
CursorAdapter!: the suggestions adapter

isIconfiedByDefault

open fun isIconfiedByDefault(): Boolean

Returns the default iconified state of the search field.

Return
Boolean: androidx.appcompat.R.attr#iconifiedByDefault

isIconified

open fun isIconified(): Boolean

Returns the current iconified state of the SearchView.

Return
Boolean: true if the SearchView is currently iconified, false if the search field is fully visible.

isQueryRefinementEnabled

open fun isQueryRefinementEnabled(): Boolean

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

Return
Boolean: true if enabled for all items, false otherwise.

isSubmitButtonEnabled

open fun isSubmitButtonEnabled(): Boolean

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

Return
Boolean: whether the submit button is enabled automatically when necessary

onActionViewCollapsed

open fun onActionViewCollapsed(): Unit

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

onActionViewExpanded

open fun onActionViewExpanded(): Unit

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

onWindowFocusChanged

open fun onWindowFocusChanged(hasWindowFocus: Boolean): Unit

requestFocus

open fun requestFocus(direction: Int, previouslyFocusedRect: Rect!): Boolean

setIconified

open fun setIconified(iconify: Boolean): Unit

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.

setIconifiedByDefault

open fun setIconifiedByDefault(iconified: Boolean): Unit

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 androidx.appcompat.R.attr#iconifiedByDefault

setImeOptions

open fun setImeOptions(imeOptions: Int): Unit

Sets the IME options on the query text field.

Parameters
imeOptions Int: the options to set on the query text field android.R.attr#imeOptions

setInputType

open fun setInputType(inputType: Int): Unit

Sets the input type on the query text field.

Parameters
inputType Int: the input type to set on the query text field android.R.attr#inputType

setMaxWidth

open fun setMaxWidth(maxpixels: Int): Unit

Makes the view at most this many pixels wide android.R.attr#maxWidth

setOnCloseListener

open fun setOnCloseListener(listener: SearchView.OnCloseListener!): Unit

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.

setOnQueryTextFocusChangeListener

open fun setOnQueryTextFocusChangeListener(listener: OnFocusChangeListener!): Unit

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

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

setOnQueryTextListener

open fun setOnQueryTextListener(listener: SearchView.OnQueryTextListener!): Unit

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.

setOnSearchClickListener

open fun setOnSearchClickListener(listener: OnClickListener!): Unit

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 OnClickListener!: the listener to inform when the search button is clicked or the text field is programmatically de-iconified.

setOnSuggestionListener

open fun setOnSuggestionListener(listener: SearchView.OnSuggestionListener!): Unit

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

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

setQuery

open fun setQuery(query: CharSequence!, submit: Boolean): Unit

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 CharSequence!: whether to submit the query right now or only update the contents of text field.

setQueryHint

open fun setQueryHint(@Nullable hint: CharSequence?): Unit

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 androidx.appcompat.R.attr#queryHint

setQueryRefinementEnabled

open fun setQueryRefinementEnabled(enable: Boolean): Unit

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.

setSearchableInfo

open fun setSearchableInfo(searchable: SearchableInfo!): Unit

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.

setSubmitButtonEnabled

open fun setSubmitButtonEnabled(enabled: Boolean): Unit

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.

setSuggestionsAdapter

open fun setSuggestionsAdapter(adapter: CursorAdapter!): Unit

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.

Protected methods

onDetachedFromWindow

protected open fun onDetachedFromWindow(): Unit

onLayout

protected open fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int): Unit

onMeasure

protected open fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int): Unit

onRestoreInstanceState

protected open fun onRestoreInstanceState(state: Parcelable!): Unit

onSaveInstanceState

protected open fun onSaveInstanceState(): Parcelable!