1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.support.v4.widget;
18
19import android.app.SearchManager;
20import android.app.SearchableInfo;
21import android.content.ComponentName;
22import android.content.Context;
23import android.view.View;
24import android.widget.SearchView;
25import android.widget.TextView;
26
27/**
28 * Helper for accessing features in {@link SearchView}
29 * introduced after API level 4 in a backwards compatible fashion.
30 *
31 * @deprecated Use {@link SearchView} directly.
32 */
33@Deprecated
34public final class SearchViewCompat {
35    private static void checkIfLegalArg(View searchView) {
36        if (searchView == null) {
37            throw new IllegalArgumentException("searchView must be non-null");
38        }
39        if (!(searchView instanceof SearchView)) {
40            throw new IllegalArgumentException("searchView must be an instance of "
41                    + "android.widget.SearchView");
42        }
43    }
44
45    private SearchViewCompat(Context context) {
46        /* Hide constructor */
47    }
48
49    /**
50     * Creates a new SearchView.
51     *
52     * @param context The Context the view is running in.
53     * @return A SearchView instance if the class is present on the current
54     *         platform, null otherwise.
55     *
56     * @deprecated Use {@link SearchView} constructor directly.
57     */
58    @Deprecated
59    public static View newSearchView(Context context) {
60        return new SearchView(context);
61    }
62
63    /**
64     * Sets the SearchableInfo for this SearchView. Properties in the SearchableInfo are used
65     * to display labels, hints, suggestions, create intents for launching search results screens
66     * and controlling other affordances such as a voice button.
67     *
68     * @param searchView The SearchView to operate on.
69     * @param searchableComponent The application component whose
70     * {@link android.app.SearchableInfo} should be loaded and applied to
71     * the SearchView.
72     *
73     * @deprecated Use {@link SearchView#setSearchableInfo(SearchableInfo)} directly.
74     */
75    @Deprecated
76    public static void setSearchableInfo(View searchView, ComponentName searchableComponent) {
77        checkIfLegalArg(searchView);
78        SearchManager searchManager = (SearchManager)
79                searchView.getContext().getSystemService(Context.SEARCH_SERVICE);
80        ((SearchView) searchView).setSearchableInfo(
81                searchManager.getSearchableInfo(searchableComponent));
82    }
83
84    /**
85     * Sets the IME options on the query text field.  This is a no-op if
86     * called on pre-{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}
87     * platforms.
88     *
89     * @see TextView#setImeOptions(int)
90     * @param searchView The SearchView to operate on.
91     * @param imeOptions the options to set on the query text field
92     *
93     * @deprecated Use {@link SearchView#setImeOptions(int)} directly.
94     */
95    @Deprecated
96    public static void setImeOptions(View searchView, int imeOptions) {
97        checkIfLegalArg(searchView);
98        ((SearchView) searchView).setImeOptions(imeOptions);
99    }
100
101    /**
102     * Sets the input type on the query text field.  This is a no-op if
103     * called on pre-{@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}
104     * platforms.
105     *
106     * @see TextView#setInputType(int)
107     * @param searchView The SearchView to operate on.
108     * @param inputType the input type to set on the query text field
109     *
110     * @deprecated Use {@link SearchView#setInputType(int)} directly.
111     */
112    @Deprecated
113    public static void setInputType(View searchView, int inputType) {
114        checkIfLegalArg(searchView);
115        ((SearchView) searchView).setInputType(inputType);
116    }
117
118    /**
119     * Sets a listener for user actions within the SearchView.
120     *
121     * @param searchView The SearchView in which to register the listener.
122     * @param listener the listener object that receives callbacks when the user performs
123     *     actions in the SearchView such as clicking on buttons or typing a query.
124     *
125     * @deprecated Use {@link SearchView#setOnQueryTextListener(SearchView.OnQueryTextListener)}
126     * directly.
127     */
128    @Deprecated
129    public static void setOnQueryTextListener(View searchView, OnQueryTextListener listener) {
130        checkIfLegalArg(searchView);
131        ((SearchView) searchView).setOnQueryTextListener(newOnQueryTextListener(listener));
132    }
133
134    private static SearchView.OnQueryTextListener newOnQueryTextListener(
135            final OnQueryTextListener listener) {
136        return new SearchView.OnQueryTextListener() {
137            @Override
138            public boolean onQueryTextSubmit(String query) {
139                return listener.onQueryTextSubmit(query);
140            }
141
142            @Override
143            public boolean onQueryTextChange(String newText) {
144                return listener.onQueryTextChange(newText);
145            }
146        };
147    }
148
149    /**
150     * @deprecated Use {@link SearchView.OnQueryTextListener} instead.
151     */
152    @Deprecated
153    public static abstract class OnQueryTextListenerCompat implements OnQueryTextListener {
154        @Override
155        public boolean onQueryTextSubmit(String query) {
156            return false;
157        }
158
159        @Override
160        public boolean onQueryTextChange(String newText) {
161            return false;
162        }
163    }
164
165    /**
166     * @deprecated Use {@link SearchView.OnQueryTextListener} instead.
167     */
168    @Deprecated
169    public interface OnQueryTextListener {
170        /**
171         * Called when the user submits the query. This could be due to a key press on the
172         * keyboard or due to pressing a submit button.
173         * The listener can override the standard behavior by returning true
174         * to indicate that it has handled the submit request. Otherwise return false to
175         * let the SearchView handle the submission by launching any associated intent.
176         *
177         * @param query the query text that is to be submitted
178         *
179         * @return true if the query has been handled by the listener, false to let the
180         * SearchView perform the default action.
181         */
182        boolean onQueryTextSubmit(String query);
183
184        /**
185         * Called when the query text is changed by the user.
186         *
187         * @param newText the new content of the query text field.
188         *
189         * @return false if the SearchView should perform the default action of showing any
190         * suggestions if available, true if the action was handled by the listener.
191         */
192        boolean onQueryTextChange(String newText);
193    }
194
195    /**
196     * Sets a listener to inform when the user closes the SearchView.
197     *
198     * @param searchView The SearchView in which to register the listener.
199     * @param listener the listener to call when the user closes the SearchView.
200     *
201     * @deprecated Use {@link SearchView#setOnCloseListener(SearchView.OnCloseListener)} directly.
202     */
203    @Deprecated
204    public static void setOnCloseListener(View searchView, OnCloseListener listener) {
205        checkIfLegalArg(searchView);
206        ((SearchView) searchView).setOnCloseListener(newOnCloseListener(listener));
207    }
208
209    private static SearchView.OnCloseListener newOnCloseListener(final OnCloseListener listener) {
210        return new SearchView.OnCloseListener() {
211            @Override
212            public boolean onClose() {
213                return listener.onClose();
214            }
215        };
216    }
217
218    /**
219     * @deprecated Use {@link SearchView.OnCloseListener} instead.
220     */
221    @Deprecated
222    public static abstract class OnCloseListenerCompat implements OnCloseListener {
223        @Override
224        public boolean onClose() {
225            return false;
226        }
227    }
228
229    /**
230     * Callback for closing the query UI.
231     *
232     * @deprecated Use {@link SearchView.OnCloseListener} instead.
233     */
234    @Deprecated
235    public interface OnCloseListener {
236        /**
237         * The user is attempting to close the SearchView.
238         *
239         * @return true if the listener wants to override the default behavior of clearing the
240         * text field and dismissing it, false otherwise.
241         */
242        boolean onClose();
243    }
244
245    /**
246     * Returns the query string currently in the text field.
247     *
248     * @param searchView The SearchView to operate on.
249     *
250     * @return the query string
251     *
252     * @deprecated Use {@link SearchView#getQuery()} directly.
253     */
254    @Deprecated
255    public static CharSequence getQuery(View searchView) {
256        checkIfLegalArg(searchView);
257        return ((SearchView) searchView).getQuery();
258    }
259
260    /**
261     * Sets a query string in the text field and optionally submits the query as well.
262     *
263     * @param searchView The SearchView to operate on.
264     * @param query the query string. This replaces any query text already present in the
265     * text field.
266     * @param submit whether to submit the query right now or only update the contents of
267     * text field.
268     *
269     * @deprecated Use {@link SearchView#setQuery(CharSequence, boolean)} directly.
270     */
271    @Deprecated
272    public static void setQuery(View searchView, CharSequence query, boolean submit) {
273        checkIfLegalArg(searchView);
274        ((SearchView) searchView).setQuery(query, submit);
275    }
276
277    /**
278     * Sets the hint text to display in the query text field. This overrides any hint specified
279     * in the SearchableInfo.
280     *
281     * @param searchView The SearchView to operate on.
282     * @param hint the hint text to display
283     *
284     * @deprecated Use {@link SearchView#setQueryHint(CharSequence)} directly.
285     */
286    @Deprecated
287    public static void setQueryHint(View searchView, CharSequence hint) {
288        checkIfLegalArg(searchView);
289        ((SearchView) searchView).setQueryHint(hint);
290    }
291
292    /**
293     * Iconifies or expands the SearchView. Any query text is cleared when iconified. This is
294     * a temporary state and does not override the default iconified state set by
295     * setIconifiedByDefault(boolean). If the default state is iconified, then
296     * a false here will only be valid until the user closes the field. And if the default
297     * state is expanded, then a true here will only clear the text field and not close it.
298     *
299     * @param searchView The SearchView to operate on.
300     * @param iconify a true value will collapse the SearchView to an icon, while a false will
301     * expand it.
302     *
303     * @deprecated Use {@link SearchView#setIconified(boolean)} directly.
304     */
305    @Deprecated
306    public static void setIconified(View searchView, boolean iconify) {
307        checkIfLegalArg(searchView);
308        ((SearchView) searchView).setIconified(iconify);
309    }
310
311    /**
312     * Returns the current iconified state of the SearchView.
313     *
314     * @param searchView The SearchView to operate on.
315     * @return true if the SearchView is currently iconified, false if the search field is
316     * fully visible.
317     *
318     * @deprecated Use {@link SearchView#isIconified()} directly.
319     */
320    @Deprecated
321    public static boolean isIconified(View searchView) {
322        checkIfLegalArg(searchView);
323        return ((SearchView) searchView).isIconified();
324    }
325
326    /**
327     * Enables showing a submit button when the query is non-empty. In cases where the SearchView
328     * is being used to filter the contents of the current activity and doesn't launch a separate
329     * results activity, then the submit button should be disabled.
330     *
331     * @param searchView The SearchView to operate on.
332     * @param enabled true to show a submit button for submitting queries, false if a submit
333     * button is not required.
334     *
335     * @deprecated Use {@link SearchView#setSubmitButtonEnabled(boolean)} directly.
336     */
337    @Deprecated
338    public static void setSubmitButtonEnabled(View searchView, boolean enabled) {
339        checkIfLegalArg(searchView);
340        ((SearchView) searchView).setSubmitButtonEnabled(enabled);
341    }
342
343    /**
344     * Returns whether the submit button is enabled when necessary or never displayed.
345     *
346     * @param searchView The SearchView to operate on.
347     * @return whether the submit button is enabled automatically when necessary
348     *
349     * @deprecated Use {@link SearchView#isSubmitButtonEnabled()} directly.
350     */
351    @Deprecated
352    public static boolean isSubmitButtonEnabled(View searchView) {
353        checkIfLegalArg(searchView);
354        return ((SearchView) searchView).isSubmitButtonEnabled();
355    }
356
357    /**
358     * Specifies if a query refinement button should be displayed alongside each suggestion
359     * or if it should depend on the flags set in the individual items retrieved from the
360     * suggestions provider. Clicking on the query refinement button will replace the text
361     * in the query text field with the text from the suggestion. This flag only takes effect
362     * if a SearchableInfo has been specified with {@link #setSearchableInfo(View, ComponentName)}
363     * and not when using a custom adapter.
364     *
365     * @param searchView The SearchView to operate on.
366     * @param enable true if all items should have a query refinement button, false if only
367     * those items that have a query refinement flag set should have the button.
368     *
369     * @see SearchManager#SUGGEST_COLUMN_FLAGS
370     * @see SearchManager#FLAG_QUERY_REFINEMENT
371     *
372     * @deprecated Use {@link SearchView#setQueryRefinementEnabled(boolean)} directly.
373     */
374    @Deprecated
375    public static void setQueryRefinementEnabled(View searchView, boolean enable) {
376        checkIfLegalArg(searchView);
377        ((SearchView) searchView).setQueryRefinementEnabled(enable);
378    }
379
380    /**
381     * Returns whether query refinement is enabled for all items or only specific ones.
382     * @param searchView The SearchView to operate on.
383     * @return true if enabled for all items, false otherwise.
384     *
385     * @deprecated Use {@link SearchView#isQueryRefinementEnabled()} directly.
386     */
387    @Deprecated
388    public static boolean isQueryRefinementEnabled(View searchView) {
389        checkIfLegalArg(searchView);
390        return ((SearchView) searchView).isQueryRefinementEnabled();
391    }
392
393    /**
394     * Makes the view at most this many pixels wide
395     * @param searchView The SearchView to operate on.
396     *
397     * @deprecated Use {@link SearchView#setMaxWidth(int)} directly.
398     */
399    @Deprecated
400    public static void setMaxWidth(View searchView, int maxpixels) {
401        checkIfLegalArg(searchView);
402        ((SearchView) searchView).setMaxWidth(maxpixels);
403    }
404}
405