It’s all in our Tutorial app

There are two ways that you can provide search capabilities in your apps:

• By using a SearchView Widget
• By using a Search Dialog

We show you how to use both options.

Our tutorial app displays a SearchView Widget’s search icon in the Action Bar. Pressing the icon expands the SearchView to display a textbox.

The app also displays a search button. Pressing the button displays a floating Search Dialog in front of the Action Bar.

There’s also a menu item in the overflow menu which triggers the Search Dialog to be displayed.

Using either search option starts the search activity which does the search and displays the results.

Top to bottom: The collapsed SearchView Widget showing the search icon, the Search Dialog and the expanded SearchView Widget’s textbox at the bottom

Since Honeycomb (Android 3.0, API Level 11), the preferred method to provide search function is to use the SearchView Widget as an action item in the Action Bar.

We’ll show you how to do this on device’s running API Level 7 and up using the support library’s SearchView Widget. You can place the SearchView Widget anywhere but we’ll put it in the Action Bar.

The SearchView Widget provides a text box for user input and passes the search request to the Search Provider.

Using the SearchView Widget

We display a SearchView Widget in the Action Bar of our tutorial app.

You may want to have a look at our Action Bar tutorial, Using Android’s Action Bar, where we show you how to use the support library to display an Action Bar on devices using API Level 7 and up.

What’s on the menu? Putting the SearchView in the menu

We create a menu resource file, my_menu.xml and add the SearchView to the menu as an action item.

If you haven’t already done so, have look at our Menu tutorial, Using menu’s in your apps: a tutorial for more on menus and action items.

Action Stations! Adding the SearchView Widget to the Action Bar

We create a menu resource file, my_menu.xml in the res/menu folder:

We add our menu items to our menu which we define in an XML menu resource file

Note the following:

• We’re using the support library so we use our custom namespace, my_app
• We have two menu items:
  • The first is our SearchView which we want displayed in the Action Bar as an action item if there is room
  • The second is displayed in the overflow menu
• icon – you must include an icon for the action item as it will be displayed in the Action Bar in the default collapsed mode, only expanding when the icon is pressed
• title – the string that is displayed as a hint in the search box
• actionViewClass – we declare our action provider class, the support library’s SearchView
• showAsAction – we want the first menu item to show in the Action Bar as an action item if there is room. The second item will be shown in the overflow menu

The menu is inflated when the app runs and displays the SearchView Widget’s search icon in the Action Bar.

Tell Andy about the search: Create a Searchable Configuration file

You need to notify the Android system that you want to use the search framework. You do this in an XML Search Configuration file.

We define what the SearchView should do in a configuration file, search_config.xml which we save in res/xml folder.

We’ve included the minimum attributes in our search configuration file. Have a look at the documentation for more on the configuration file's syntax and usage.

Define the Searchable Configuration in an XML file

Note the following:

This file is used later to create a SearchableInfo object.

• – the root node element
• label – this attribute is required. Use the name of your app as included in the manifest file. It’s used to identify your app as a searchable item in the device’s search settings
• hint – it’s recommended that you include a hint. It will be displayed in the search box and should indicate what is searchable

Someone’s got to do the work: You need an activity to handle the search and display the results

Regardless of whether you use a SearchView Widget or a Search Dialog, you will need an activity to do the search and display the results.

Create a searchable activity

Our MySearchableActivity activity performs the search and displays the results.

Anything to declare? Make it known that this activity will do the search

We must tell the system which activity to use to do the search. We do this in the manifest:

Use an Intent Filter to notify the system that this activity will receive ACTION_SEARCH intents

Note the following:

You may want to check out our tutorial on Intents and Intent Filters if you haven’t already done so.

• – declares the activity
• singleTop – if this activity exists on the back stack then it will be used instead of creating a new one
• - our activity will accept the ACTION_SEARCH intent which contains the query
• - we tell the activity to use our searchable configuration file, search_config
  • name – required attribute with the value android.app.searchable
  • resource – required attribute pointing to our searchable configuration file, search_config

Let’s be friends: Associate the Search Widget with the Searchable Configuration

Before you can use the SearchView Widget, you need to associate it with the Searchable Configuration. We do this in the onCreateOptionsMenu() method:

Associate the SearchView Widget and the Searchable Configuration

Note the following:

We’re using the support library so that we can display the Search Widget in the Action Bar from API Level 7 and up.

• We inflate our menu resource file
• searchManager – our SearchManager object that gives us access to the system’s search services
• searchActionBarItem – a reference to the menu’s SearchView action item
• searchView – our SearchView object
• MenuItemCompat – we’re using the support library so we use the MenuItemCompat class’s getActionView() method
• setSearchableInfo – sets the searchable configuration for the SearchView Widget
• setIconifiedByDefault – by default, the Search Widget displays just the icon in the Action Bar so you don’t have to set setIconifiedByDefault() to true here. Pressing the icon expands the view to display the text box. If you set it to false, then the text box will be shown alongside the icon

Executing a search using the SearchView Widget

Press the SearchView Widget’s icon in the Action Bar to display the text box if it’s not already showing. Enter your query and start the search.

The system will then start your Searchable activity to take care of the rest.

Using the Search Dialog

The Search Dialog is an alternative to the SearchView Widget. The Search Dialog remains hidden until you activate it by calling onSearchRequested().

You have to first enable the Search Dialog in an activity before you can use it.

Tell Andy about the Search Dialog: Enabling the Search Dialog

Both our MySearchableActivity and the MyActivity activities can display the Search Dialog.

You tell the system which activities you want to use the Search Dialog in by including the necessary element in the manifest.

You can include the element within the element if you want to use the Search Dialog in all of your activities.

You don’t have to include it in the Searchable activity, MySearchableActivity as it’s enabled by default.

Here’s how we add the element in the main activity’s manifest declaration:

We enable the Search Dialog to be used in an activity by adding the appropriate meta-data

Note the following:

• - we include the element to enable the Search Dialog
  • name – unique name for the item
  • value – our activity that will handle the search query

Calling onSearchRequested() will activate the Search Dialog. The user then enters their query text and executes the search. The system will then start the MySearchableActivity activity, passing it the query in an intent, to do the search

Show me what you’ve got: Displaying the Search Dialog

We’ve provided a Search Button to show the Search Dialog by calling onSearchRequested().

To be consistent, it’s a good idea to use the search icon for the button’s label. You can download the standard Android icons from the official Action Bar Icon Pack download link.

Do you really care? The Search dialog and activity lifecycle

If the current activity is not the search activity then the normal activity lifecycle events are triggered once the user executes the search.

If it is the search activity then:

• by default, a new instance of the activity is created and brought to the top of the stack. Pressing the back button moves back down the stack to the previous instance of the activity
• if you set android:launchMode to singleTop in the manifest then the search activity calls onNewIntent() and passes the ACTION_SEARCH intent to it.

When the activity is started for the first time and onCreate() is called, we get the ACTION_SEARCH intent and call handleIntent(), passing it the intent as a parameter.

Because we’ve set this activity’s launch mode to singleTop, when the activity is re-launched, the current instance of the activity (not a new one) at the top of the stack is used along with the original ACTION_SEARCH intent that was used to create it in the first place.

Setting the activity’s launch mode to singleTop executes the onNewIntent() method each time the activity is re-launched

Note the following:

• setIntent –holds a reference to the original intent in case we overwrite it by calling getIntent()
• handleIntent – we call handleIntent() as we would in onCreate() to process the query

Let’s talk: Executing the Dialog Search

To start the Dialog Search, press the button or select an item from the overflow menu. This executes the onSearchRequested() method which displays the Search Dialog.

You could also call startSearch(null,false,null,false) to start the Search Dialog.

Pressing the button

Pressing the button executes the doSearch() method (declared as the onClick attribute in the layout) which triggers the onSearchRequested() method:

The doSearch() method executes when the Search Button is pressed

Selecting a menu item

The SearchView Widget’s menu item appears in the overflow menu if there is no room for it in the Action Bar. Its menu item is then handled as a Search Dialog.

Selecting any item from the overflow menu triggers the onOptionsItemSelected() method:

Selecting an item from the overflow menu triggers the onOptionsItemSelected() method

If either of the menu items match, then either onSearchRequested() or startSearch() is called. Both of these start the search procedure using a Search Dialog.

Getting results: Performing the search and showing the results

The way the search is handled is the same for the SearchView Widget and the Search Dialog.

Our Searchable activity, MySearchableActivity does the searching and displays the results.

Get the user’s query string

The user types in the query and executes it. Then the system starts the Searchable activity, sending it an ACTION_SEARCH intent. The intent contains the search query string.

Check out our tutorial, Passing data between activities for more on using intents to pass data.

Get the intent:

Get the intent and call the handleIntent() method

Extract the user’s query string out of the intent:

The handleIntent() method gets the user’s query out of the intent and calls the doSearchQuery() method

Note the following:

• we use an if statement to confirm that it is an ACTION_SEARCH intent
• intent – the intent is passed as a parameter to the handleIntent() method
• searchQuery – get the search query string out of the intent
• doSearchQuery – our method that will do the search and return the results. We pass it the query string supplied by the user

Do the search

We don’t actually do a search in our tutorial but call the doSearchQuery() method where you would include your code to do the search.

How you do your search depends on how you’ve stored your data.

Usually you’d use a database to store your data.

Have a look at our SQLite database tutorial, Using a SQLite database in Android and the Android Content Providers tutorial.

Use a cursor loader if you’re searching a content provider, you can see more about that in our Loading data using Android’s Loaders tutorial.

Display the results

Usually you’d display the results in a ListView. Have a look at our Android ListView tutorial on how to do that.

I hope that you have found this tutorial helpful.

This project was created using .

You can download the project files here 

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.