1page.title=Setting Up the Search Interface
2trainingnavtop=true
3next.title=Storing and Searching for Data
4next.link=search.html
5
6@jd:body
7
8  <div id="tb-wrapper">
9    <div id="tb">
10      <h2>This lesson teaches you to</h2>
11
12      <ul>
13        <li><a href="{@docRoot}training/search/setup.html#add-sv">Add the Search View to the Action
14        Bar</a></li>
15
16        <li><a href="{@docRoot}training/search/setup.html#create-sc">Create a Searchable
17        Configuration</a></li>
18
19        <li><a href="{@docRoot}training/search/setup.html#create-sa">Create a Searchable
20        Activity</a></li>
21      </ul>
22
23      <h2>You should also read:</h2>
24
25      <ul>
26        <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
27      </ul>
28    </div>
29  </div>
30
31  <p>Beginning in Android 3.0, using the {@link android.widget.SearchView} widget as an item in
32  the action bar is the preferred way to provide search in your app. Like with all items in
33  the action bar, you can define the {@link android.widget.SearchView} to show at all times, only
34  when there is room, or as a collapsible action, which displays the {@link
35  android.widget.SearchView} as an icon initially, then takes up the entire action bar as a search
36  field when the user clicks the icon.</p>
37
38  <p class="note"><strong>Note:</strong> Later in this class, you will learn how to make your
39  app compatible down to Android 2.1 (API level 7) for devices that do not support
40  {@link android.widget.SearchView}.</p>
41
42  <h2 id="add-sv">Add the Search View to the Action Bar</h2>
43
44  <p>To add a {@link android.widget.SearchView} widget to the action bar, create a file named
45  <code>res/menu/options_menu.xml</code> in your project and add the following code to the file.
46  This code defines how to create the search item, such as the icon to use and the title of the
47  item. The <code>collapseActionView</code> attribute allows your {@link android.widget.SearchView}
48  to expand to take up the whole action bar and collapse back down into a
49  normal action bar item when not in use. Because of the limited action bar space on handset devices,
50  using the <code>collapsibleActionView</code> attribute is recommended to provide a better
51  user experience.</p>
52  <pre>
53&lt;?xml version="1.0" encoding="utf-8"?&gt;
54&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
55    &lt;item android:id="@+id/search"
56          android:title="@string/search_title"
57          android:icon="@drawable/ic_search"
58          android:showAsAction="collapseActionView|ifRoom"
59          android:actionViewClass="android.widget.SearchView" /&gt;
60&lt;/menu&gt;
61</pre>
62
63  <p class="note"><strong>Note:</strong> If you already have an existing XML file for your menu
64  items, you can add the <code>&lt;item&gt;</code> element to that file instead.</p>
65
66  <p>To display the {@link android.widget.SearchView} in the action bar, inflate the XML menu
67  resource (<code>res/menu/options_menu.xml</code>) in the {@link
68  android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method of your activity:</p>
69  <pre>
70&#64;Override
71public boolean onCreateOptionsMenu(Menu menu) {
72    MenuInflater inflater = getMenuInflater();
73    inflater.inflate(R.menu.options_menu, menu);
74
75    return true;
76}
77</pre>
78
79  <p>If you run your app now, the {@link android.widget.SearchView} appears in your app's action
80  bar, but it isn't functional. You now need to define <em>how</em> the {@link
81  android.widget.SearchView} behaves.</p>
82
83  <h2 id="create-sc">Create a Searchable Configuration</h2>
84
85  <p>A <a href="http://developer.android.com/guide/topics/search/searchable-config.html">searchable
86  configuration</a> defines how the {@link android.widget.SearchView} behaves and is defined in a
87  <code>res/xml/searchable.xml</code> file. At a minimum, a searchable configuration must contain
88  an <code>android:label</code> attribute that has the same value as the
89  <code>android:label</code> attribute of the <a href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a> or
90  <a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a> element in your Android manifest.
91  However, we also recommend adding an <code>android:hint</code> attribute to give the user an idea of what to enter into the search
92  box:</p>
93  <pre>
94&lt;?xml version="1.0" encoding="utf-8"?&gt;
95
96&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android"
97        android:label="@string/app_name"
98        android:hint="@string/search_hint" /&gt;
99</pre>
100
101  <p>In your application's manifest file, declare a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">
102  <code>&lt;meta-data&gt;</code></a> element that points to the <code>res/xml/searchable.xml</code> file,
103  so that your application knows where to find it. Declare the element in an <code>&lt;activity&gt;</code>
104  that you want to display the {@link android.widget.SearchView} in:</p>
105  <pre>
106&lt;activity ... &gt;
107    ...
108    &lt;meta-data android:name="android.app.searchable"
109            android:resource="@xml/searchable" /&gt;
110
111&lt;/activity&gt;
112</pre>
113
114  <p>In the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method that you
115  created before, associate the searchable configuration with the {@link android.widget.SearchView}
116  by calling {@link android.widget.SearchView#setSearchableInfo}:</p>
117  <pre>
118&#64;Override
119public boolean onCreateOptionsMenu(Menu menu) {
120    MenuInflater inflater = getMenuInflater();
121    inflater.inflate(R.menu.options_menu, menu);
122
123    // Associate searchable configuration with the SearchView
124    SearchManager searchManager =
125           (SearchManager) getSystemService(Context.SEARCH_SERVICE);
126    SearchView searchView =
127            (SearchView) menu.findItem(R.id.search).getActionView();
128    searchView.setSearchableInfo(
129            searchManager.getSearchableInfo(getComponentName()));
130
131    return true;
132}
133</pre>
134
135  <p>The call to {@link android.app.SearchManager#getSearchableInfo getSearchableInfo()} obtains a
136  {@link android.app.SearchableInfo} object that is created from the searchable configuration XML
137  file. When the searchable configuration is correctly associated with your {@link
138  android.widget.SearchView}, the {@link android.widget.SearchView} starts an activity with the
139  {@link android.content.Intent#ACTION_SEARCH} intent when a user submits a query. You now need an
140  activity that can filter for this intent and handle the search query.</p>
141
142  <h2 id="create-sa">Create a Searchable Activity</h2>
143
144  <p>A {@link android.widget.SearchView} tries to start an activity with the {@link
145  android.content.Intent#ACTION_SEARCH} when a user submits a search query. A searchable activity
146  filters for the {@link android.content.Intent#ACTION_SEARCH} intent and searches for the query in
147  some sort of data set. To create a searchable activity, declare an activity of your choice to
148  filter for the {@link android.content.Intent#ACTION_SEARCH} intent:</p>
149  <pre>
150&lt;activity android:name=".SearchResultsActivity" ... &gt;
151    ...
152    &lt;intent-filter&gt;
153        &lt;action android:name="android.intent.action.SEARCH" /&gt;
154    &lt;/intent-filter&gt;
155    ...
156&lt;/activity&gt;
157</pre>
158
159  <p>In your searchable activity, handle the {@link android.content.Intent#ACTION_SEARCH} intent by
160  checking for it in your {@link android.app.Activity#onCreate onCreate()} method.</p>
161
162  <p class="note"><strong>Note:</strong> If your searchable activity launches in single top mode
163  (<code>android:launchMode="singleTop"</code>), also handle the {@link
164  android.content.Intent#ACTION_SEARCH} intent in the {@link android.app.Activity#onNewIntent
165  onNewIntent()} method. In single top mode, only one instance of your activity is created and
166  subsequent calls to start your activity do not create a new activity on the
167  stack. This launch mode is useful so users can perform searches from the same activity
168  without creating a new activity instance every time.</p>
169  <pre>
170public class SearchResultsActivity extends Activity {
171
172    &#64;Override
173    public void onCreate(Bundle savedInstanceState) {
174        ...
175        handleIntent(getIntent());
176    }
177
178    &#64;Override
179    protected void onNewIntent(Intent intent) {
180        ...
181        handleIntent(intent);
182    }
183
184    private void handleIntent(Intent intent) {
185
186        if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
187            String query = intent.getStringExtra(SearchManager.QUERY);
188            //use the query to search your data somehow
189        }
190    }
191    ...
192}
193</pre>
194
195  <p>If you run your app now, the {@link android.widget.SearchView} can accept the user's query and
196  start your searchable activity with the {@link android.content.Intent#ACTION_SEARCH} intent. It
197  is now up to you to figure out how to store and search your data given a query.</p>