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