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

 

前言

　　本章内容是android.widget.SearchView，版本为Android 3.1 r1，为Android 3.0 r1新增API，翻译来自"xiaoQLu"，欢迎访问它的博客："http://www.cnblogs.com/xiaoQLu"，再次感谢"xiaoQLu" ！期待你一起参与Android API的翻译，联系我[email protected]。

 

声明

　　欢迎转载，但请保留文章原始出处:)

　　　　博客园：http://www.cnblogs.com/

　　　　Android中文翻译组：http://goo.gl/6vJQl

 

结构

继承关系

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)

 

补充

文章精选

Android ApiDemo示例解析(36)：App->Search->Invoke Search

SearchView默认扩展

           SearchViewを使用してListViewのアイテムにフィルターをかける

 

 

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

译者链接：http://www.cnblogs.com/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

译者链接：http://www.cnblogs.com/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 。