Android 3.1 r1 中文API文檔 (120) —— SearchView

前言

　　本章內容是android.widget.SearchView，版本為Android 3.1 r1，為Android 3.0 r1新增API，翻譯來自"xiaoQLu。
 

結構

繼承關系

public class SearchView extends LinearLayout

        

java.lang.Object

android.view.View

         android.view.ViewGroup

                   android.widget.LinearLayout

                            android.widget.SearchView

 

類概述

        

         一個為用戶提供輸入搜索查詢和提交請求給搜索提供者的用戶界面部件。顯示查詢建議或結果列表，如果有的話，運行用戶選擇一條查詢建議或結果並啟動與其相關的操作。

         更多信息，參見Search文檔。

 

內部類

　　interface          SearchView.OnCloseListener       

　　（譯者注：當用戶關閉SearchView時觸發的回調函數）

 

interface     SearchView.OnQueryTextListener                

當查詢文本改變時的回調函數。

 

　　interface           SearchView.OnSuggestionListener

　　在建議上選擇事件時的回調接口。

 

XML屬性

屬性名稱

描述

android:iconifiedByDefault

設置SearchView的默認狀態。

如果為true，在沒有被使用和點擊展開時它將被圖形化。

android:maxWidth

SearchView的可選擇的最大寬度

android:queryHint

當查詢條件為空時顯示的一個提示字符串。

 

公共方法

public CharSequence getQuery ()

　　返回當前文本域中的查詢字符串

　　　　返回值

　　　　　　查詢字符串

 

public CursorAdapter getSuggestionsAdapter ()

如果有的話，返回用於搜索建議的適配器。

　　　　返回值

　　　　　　查詢適配器

 

　　public boolean isIconfiedByDefault ()

返回查詢區域默認的圖標狀態。

 

public boolean isIconified ()

返回SearchView當前的圖標狀態

　　　　返回值

如果SearchView目前是圖標狀態，返回true，如果查詢區域是完全可見的返回false

 

public boolean isQueryRefinementEnabled ()

返回查詢優化是否是對所有的條目都起作用或者只是對特別的幾個起作用

　　　　返回值

　　　　　　如果是對所有的條目起作用，剛返回true，否則返回false。

 

　　public boolean isSubmitButtonEnabled ()

返回當提交按鈕在必須的時候是否可用或者從不顯示

　　　　返回值

　　　　　　提交按鈕在必須的時候是否自動啟用

 

public boolean onKeyDown (int keyCode, KeyEvent event)

是否處理操作鍵按下事件

參數

keyCode   鍵入的鍵盤值，同時和鍵盤事件中的參數相同

event        輸入鍵的完整事件記錄

　　　　返回值

　　　　　　如果事件在這裡被處理，返回true，不處理返回false

 

public void setIconified (boolean iconify)

　　圖標化或者展開SearchView。當圖標化時任何查詢條件都被清除。這是一個臨時的狀態，不會重寫被setIconifiedByDefault(boolean)設置的默認圖標狀態。如果默認的是圖標化狀態，則在用戶關閉這個區域前都是false。如果默認的是展開狀態，這裡就是true，同時清除文本區域，但不關閉它。

參數

iconify       true值會把SearchView收縮成一個圖標，false值會展開它

　　　　返回值

　　　　　　查詢字符串

 

public void setIconifiedByDefault (boolean iconified)

　　設置搜索欄的默認狀態或者靜止狀態。如果是true，當被按下時，一個單一的搜索圖標就會被默認顯示，同時顯示文本字段和其他按鈕。如果默認的狀態是圖標，在按下關閉按鈕時它就會收縮成那個狀態。這個屬性的改變會立即生效。

　　　　參數

　　　　　　iconified   搜索欄是否默認被圖標化

 

public void setMaxWidth (int maxpixels)

以最寬的像素相看

　　　　相關的XML屬性

                android:maxWidth

 

public void setOnCloseListener (SearchView.OnCloseListener listener)

當用戶關閉SearchView時設置一個監聽器通知用戶

參數

         listener    設置用戶關閉SearchView時的監聽器

 

public void setOnQueryTextFocusChangeListener (View.OnFocusChangeListener listener)

　　設置當查詢區域字段改變時通知用戶的監聽器

參數

         listener    設置焦點更改時的監聽器

 

　　public void setOnQueryTextListener (SearchView.OnQueryTextListener listener)

　　為用戶在SearchView內的操作設置監聽器

參數

         listener    當用戶在SearchView操作時比如說點擊按鈕或者輸入查詢內容時，設置接收回調的監聽器對象

 

　　public void setOnSearchClickListener (View.OnClickListener listener)

　　設置按鈕被按下時的監聽器。在默認情況下當文本字段不可見時才起作用，調用setIconified(false)也可以通知這個監聽器。

參數

listener    當搜索按鈕被點擊或者文本字段編輯取消圖形化時通知監聽器

 

　　public void setOnSuggestionListener (SearchView.OnSuggestionListener listener)

　　設置當一條搜索建議被選中或者點擊的時候的監聽器

參數

listener    選擇搜索建議事件的監聽器

 

　　public void setQuery (CharSequence query, boolean submit)

　　設置文本區域的一個查詢字符串並選擇提交和查詢。

參數

         query        查詢字符串。代替在文本區域已經存在的查詢文本

         submit      是否立即提交查詢或者只更新文本區域的內容

 

　　public void setQueryHint (CharSequence hint)

　　設置在查詢文本區域的提示文本。將覆蓋SearchableInfo中的任何提示。

　　　　相關XML屬性

                 android:queryHint

參數

　　hint    要顯示的提示文本

                  

　　public void setQueryRefinementEnabled (boolean enable)

　　指定如果精確查詢按鈕是否在每條建議的旁邊顯示或者是否根據運營商建議中的設置在個別項目的標志決定。點擊精確查詢的按鈕會用建議中的文本替換查詢文本區域中的字段。這個標志只是在一個SearchableInfo中指定setSearchableInfo(SearchableInfo)且不使用定制的適配器時起作用。

參數

　　　　　　enable      如果所有的條目都有一個精確查詢按鈕剛為true，如果只有帶精確查詢標志的條目需要按鈕，則為false。

　　　　參見

                 SUGGEST_COLUMN_FLAGS

FLAG_QUERY_REFINEMENT

 

　　public void setSearchableInfo (SearchableInfo searchable)

　　給SearchView設置SearchableInfo。SearchableInfo中的屬性用來顯示標簽，提示(hints)，搜索建議，創建打開查詢結果和控制其他功能比如一個聲音按鈕的intents。

參數

　　searchable        對於一個特殊的activiey或者，能從SearchManager中檢索的SearchableInfo，全局的搜索提供者。

 

　　public void setSubmitButtonEnabled (boolean enabled)

　　當查詢不為空時，顯示一個提交按鈕。如果SearchView被用來填充當前activity的內容，並且不會啟動一個單獨的activity，這裡提交按鈕會消失。

參數

　　enabled    設置為True時顯示一個提交請求的按鈕，當不需要請求按鈕時設置為false。

 

　　public void setSuggestionsAdapter (CursorAdapter adapter)

　　如果你願意，你可以設置一個定制的適配器。否則使用默認的適配器來顯示和SearchableInfo相關的建議提供者的建議。

　　　　參見

                setSearchableInfo(SearchableInfo)

 

 

 

SearchView.OnCloseListener

譯者署名：xiaoQLu

譯者鏈接：http://www.cnblogs.com/xiaoQLu

版本：Android 3.0 r1

 

結構

繼承關系

public static interface SearchView.OnCloseListener

        

android.widget.SearchView.OnCloseListener

 

公共方法

public abstract boolean onClose()

　　當用戶嘗試關閉SearchView的時候調用本方法。

　　　　返回值

如果用戶想重寫默認清除文本域的動作，返回true，否則返回false。

 

 

SearchView.OnQueryTextListener

譯者署名：xiaoQLu

版本：Android 3.0 r1

 

結構

繼承關系

public static interface SearchView.OnQueryTextListener

        

android.widget.SearchView.OnQueryTextListener

 

類概述

查詢內容發生改變時調用

 

公共方法

public abstract boolean onQueryTextChange (String newText)

　　當用戶改變查詢內容的時候調用

參數

           　　newText   查詢的文本字段的新內容

　　　　返回值

如果SearchView執行默認的動作，顯示可能出現的建議，剛返回false。如果動作由監聽器處理，剛返回true

                           

public abstract boolean onQueryTextSubmit (String query)

當用戶提交請求時調用。這可能是因為在鍵盤上按下一個鍵或者點擊一個提交按鈕。這個監聽器可以通過返回true來重寫標准的動作，指明由它來處理提交請求。否則返回false讓SearchView把這個請求轉發到與之關聯的intent去處理。

參數

           　　query        要提交的查詢內容

           返回值

如果查詢請求被監聽器處理，剛返回true，如果SearchView執行默認的動作則返回false

 

 

SearchView.OnSuggestionListener

譯者署名：xiaoQLu

版本：Android 2.3 r1

 

結構

繼承關系

Public static interface SearchView.OnSuggestionListener

        

android.widget.SearchView.OnSuggestionListener

 

類概述

選中搜索建議時的回調接口。當SearchableInfo 通過setSearchableInfo(SearchableInfo).特別指定時，才調用這些回調函數。

 

公共方法

public abstract boolean onSuggestionClick (int position)

　　當點擊一條搜索建議時調用        

參數

           　　position    在建議列表中的點擊項的絕對位置。

　　　　返回值

如果監聽器處理這個事件，並且重寫默認的處理方法，處理發送的intent請求或者是在這條目中指定的查詢請求，剛返回true。否則返回false。

        

public abstract boolean onSuggestionSelect (int position)

　　通過導航選中搜索建議時調用    

參數

           　　position    在建議列表中絕對位置。

　　　　返回值

　　　　　　如果監聽器處理這個事件，並且重寫基於選中條目的處理方法，剛返回true。否則返回false。