From 055e3f25ba85d7aefcddaa0aa2bb0589719ec80c Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Fri, 3 Feb 2012 11:00:47 -0800 Subject: docs: android u search class Change-Id: I433cb5b82426c942af8f357180aeb7c947f2d9e1 --- docs/html/training/search/setup.jd | 197 +++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/html/training/search/setup.jd (limited to 'docs/html/training/search/setup.jd') diff --git a/docs/html/training/search/setup.jd b/docs/html/training/search/setup.jd new file mode 100644 index 0000000..044e422 --- /dev/null +++ b/docs/html/training/search/setup.jd @@ -0,0 +1,197 @@ +page.title=Setting Up the Search Interface +trainingnavtop=true +next.title=Storing and Searching for Data +next.link=search.html + +@jd:body + +
+
+

This lesson teaches you to

+ + + +

You should also read:

+ + +
+
+ +

Beginning in Android 3.0, using the {@link android.widget.SearchView} widget as an item in + the action bar is the preferred way to provide search in your app. Like with all items in + the action bar, you can define the {@link android.widget.SearchView} to show at all times, only + when there is room, or as a collapsible action, which displays the {@link + android.widget.SearchView} as an icon initially, then takes up the entire action bar as a search + field when the user clicks the icon.

+ +

Note: Later in this class, you will learn how to make your + app compatible down to Android 2.1 (API level 7) for devices that do not support + {@link android.widget.SearchView}.

+ +

Add the Search View to the Action Bar

+ +

To add a {@link android.widget.SearchView} widget to the action bar, create a file named + res/menu/options_menu.xml in your project and add the following code to the file. + This code defines how to create the search item, such as the icon to use and the title of the + item. The collapseActionView attribute allows your {@link android.widget.SearchView} + to expand to take up the whole action bar and collapse back down into a + normal action bar item when not in use. Because of the limited action bar space on handset devices, + using the collapsibleActionView attribute is recommended to provide a better + user experience.

+ 
+<?xml version="1.0" encoding="utf-8"?>
+<menu xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:id="@+id/search"
+          android:title="@string/search_title"
+          android:icon="@drawable/ic_search"
+          android:showAsAction="collapseActionView|ifRoom"
+          android:actionViewClass="android.widget.SearchView" />
+</menu>
+
+ +

Note: If you already have an existing XML file for your menu + items, you can add the <item> element to that file instead.

+ +

To display the {@link android.widget.SearchView} in the action bar, inflate the XML menu + resource (res/menu/options_menu.xml) in the {@link + android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method of your activity:

+ 
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.options_menu, menu);
+
+    return true;
+}
+
+ +

If you run your app now, the {@link android.widget.SearchView} appears in your app's action + bar, but it isn't functional. You now need to define how the {@link + android.widget.SearchView} behaves.

+ +

Create a Searchable Configuration

+ +

A searchable + configuration defines how the {@link android.widget.SearchView} behaves and is defined in a + res/xml/searchable.xml file. At a minimum, a searchable configuration must contain + an android:label attribute that has the same value as the + android:label attribute of the <application> or + <activity> element in your Android manifest. + However, we also recommend adding an android:hint attribute to give the user an idea of what to enter into the search + box:

+ 
+<?xml version="1.0" encoding="utf-8"?>
+
+<searchable xmlns:android="http://schemas.android.com/apk/res/android"
+        android:label="@string/app_name"
+        android:hint="@string/search_hint" />
+
+ +

In your application's manifest file, declare a + <meta-data> element that points to the res/xml/searchable.xml file, + so that your application knows where to find it. Declare the element in an <activity> + that you want to display the {@link android.widget.SearchView} in:

+ 
+<activity ... >
+    ...
+    <meta-data android:name="android.app.searchable"
+            android:resource="@xml/searchable" />
+
+</activity>
+
+ +

In the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method that you + created before, associate the searchable configuration with the {@link android.widget.SearchView} + by calling {@link android.widget.SearchView#setSearchableInfo}:

+ 
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.options_menu, menu);
+
+    // Associate searchable configuration with the SearchView
+    SearchManager searchManager =
+           (SearchManager) getSystemService(Context.SEARCH_SERVICE);
+    SearchView searchView =
+            (SearchView) menu.findItem(R.id.search).getActionView();
+    searchView.setSearchableInfo(
+            searchManager.getSearchableInfo(getComponentName()));
+
+    return true;
+}
+
+ +

The call to {@link android.app.SearchManager#getSearchableInfo getSearchableInfo()} obtains a + {@link android.app.SearchableInfo} object that is created from the searchable configuration XML + file. When the searchable configuration is correctly associated with your {@link + android.widget.SearchView}, the {@link android.widget.SearchView} starts an activity with the + {@link android.content.Intent#ACTION_SEARCH} intent when a user submits a query. You now need an + activity that can filter for this intent and handle the search query.

+ +

Create a Searchable Activity

+ +

A {@link android.widget.SearchView} tries to start an activity with the {@link + android.content.Intent#ACTION_SEARCH} when a user submits a search query. A searchable activity + filters for the {@link android.content.Intent#ACTION_SEARCH} intent and searches for the query in + some sort of data set. To create a searchable activity, declare an activity of your choice to + filter for the {@link android.content.Intent#ACTION_SEARCH} intent:

+ 
+<activity android:name=".SearchResultsActivity" ... >
+    ...
+    <intent-filter>
+        <action android:name="android.intent.action.SEARCH" />
+    </intent-filter>
+    ...
+</activity>
+
+ +

In your searchable activity, handle the {@link android.content.Intent#ACTION_SEARCH} intent by + checking for it in your {@link android.app.Activity#onCreate onCreate()} method.

+ +

Note: If your searchable activity launches in single top mode + (android:launchMode="singleTop"), also handle the {@link + android.content.Intent#ACTION_SEARCH} intent in the {@link android.app.Activity#onNewIntent + onNewIntent()} method. In single top mode, only one instance of your activity is created and + subsequent calls to start your activity do not create a new activity on the + stack. This launch mode is useful so users can perform searches from the same activity + without creating a new activity instance every time.

+ 
+public class SearchResultsActivity extends Activity {
+
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        ...
+        handleIntent(getIntent());
+    }
+
+    @Override
+    protected void onNewIntent(Intent intent) {
+        ...
+        handleIntent(intent);
+    }
+
+    private void handleIntent(Intent intent) {
+
+        if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
+            String query = intent.getStringExtra(SearchManager.QUERY);
+            //use the query to search your data somehow
+        }
+    }
+    ...
+}
+
+ +

If you run your app now, the {@link android.widget.SearchView} can accept the user's query and + start your searchable activity with the {@link android.content.Intent#ACTION_SEARCH} intent. It + is now up to you to figure out how to store and search your data given a query.

\ No newline at end of file -- cgit v1.1