Android 3.0 r1 API中文文档(106) —— SimpleCursorAdapter
前言
本章内容是android.widget.SimpleCursorAdapter，版本为Android 3.0 r1，附带示例源码，翻译来自"深夜未眠"，欢迎访问它的博客："http://chirs1012f.javaeye.com/"，再次感谢"深夜未眠" ！期待你一起参与Android API的翻译，联系我over140@gmail.com。
声明
欢迎转载，但请保留文章原始出处:)
Android中文翻译组：http://goo.gl/6vJQl
正文
一、结构public class SimpleCusrorAdapter extends ResourceCusorAdpater
java.lang.Object
android.widget.BaseAdapter
android.widget.CursorAdapter
android.widget.ResourceCusorAdapter
android.widget.SimpleCusorAdapter
二、概述
这是一个用起来很方便的适配器类，它主要将Cursor与TexiView或ImageView进行映射。比如，你想设定要展示三列，那么当做好绑定之后，视图就会展示你设定好的那些列；当然了，视图的外观是定义在XML文件里面的，你只需用这个类与视图做好绑定就可以了。与视图绑定有两个阶段。第一阶段：如果SimpleCursorAdapter.ViewBinder可用，将会调用setViewValue(android.view.View, android.database.Cursor, int)方法。该方法返回true就说明绑定成功，否则返回false ，这就到了第二阶段，SimpleCursorAdapter内部开始自行绑定，过程是这样的，若绑定到TextView上，调用setViewText();若绑定到ImageView上，调用setViewImage();如果视图不是TextView或ImageView则抛出IllegalStateException异常。当使用带有过滤器的适配器时，例如，在APIDemo中有个AutoCompleteTextView的例子，我们能使用SimpleCursorAdapter.CursorToStringConverter和接口 FilterQueryProvider来控制过滤过程。更多信息请参考convertToString(android.database.Cursor) 和runQueryOnBackgroundThread(CharSequence)。
三、内部类
public interface SimpleCusorAdapter.ViewBinder
这个内部接口可以在外部通过SimpleCursorAdapter.ViewBinder的方式进行Cursor 与View的绑定。
public interface SimpleCusorAdapter.CursorToStringConverter
这个内部接口可以在外部通过SimpleCursorAdapter.CursorToStringConverter的方式 定义怎样将Cursor转换成字符串。
四、构造函数
public SimpleCursorAdapter (Context context, int layout, Cursor c, String[] from, int[] to)
构造函数启动自动重新查询(auto-requery)。
这个构造器已被标记为弃用(@Deprecated) 。
该方法不推荐使用，Cursor查询操作是执行在应用程序的UI线程当中，那么会导致无响应的情况。另一种方式是使用LoaderManager和CursorLoader来进行。
（译者注：3.0已不推荐使用该构造方法）
参数
context 应用程序上下文，具体来说就是ListView所在的上下文当中。
layout 布局文件的资源定位标识符，也就是说标识了ListView中的item。那么这个布局文件至少包含了参数“to”中的传进来值。
c 数据库游标，如果游标不可用则为null。
from 列名字列表，表示着你要绑定到UI上的列。如果游标不可用则为null。
to 展示参数“from”中的列，也就是说ListView中的视图显示的是参数“from”的列值，这些视图应该都是TextView。如果游标不可用则为null。
public SimpleCursorAdapter (Context context, int layout, Cursor c, String[] from, int[] to,int flags)
该适配器类标准的构造函数。（译者注：3.0新添的构造方法）
参数
context 应用程序上下文，具体来说就是ListView所在的上下文当中。
layout 布局文件的资源定位标识符，也就是说标识了ListView中的item。那么这个布局文件至少包含了参数“to”中的传进来值。
c 数据库游标，如果游标不可用则为null。
from 列名字列表，表示着你要绑定到UI上的列。如果游标不可用则为null。
to 展示参数“from”中的列，也就是说ListView中的视图显示的是参数“from”的列值，这些视图应该都是TextView。如果游标不可用则为null。
flags 这个标志用来决定该适配器的行为。(译者注：Android3.0推荐我们传递CursorAdapter.FLAG_REGISTER_CONTENT_OBSERVER。设置标志用来添加一个监听器，监听着参数cursor的数据是否有更变。)四、公共方法
public void bindView (View view, Context context, Cursor cursor)
绑定所有构造函数中的参数from（字段名）一一绑定到参数to（视图资源ID）。与视图绑定有两个阶段。第一阶段：如果SimpleCursorAdapter.ViewBinder可用，将会调用setViewValue(android.view.View, android.database.Cursor, int)方法。该方法返回true就说明绑定成功，否则返回false ，这就到了第二阶段，SimpleCursorAdapter内部开始自行绑定，过程是这样的，若绑定到TextView上，调用setViewText();若绑定到ImageView上，调用setViewImage();如果视图不是TextView或ImageView则抛出IllegalStateException异常。
参数
view 已存在的视图(View)对象, 也就是早先new出来的。
context 应用程序上下文。
cursor 数据库游标。该游标已经移动到指定位置上。
异常
IllegalStateException 如果绑定的视图中不是TextView或是ImageView则会 抛出这个异常。
参见
bindView(android.view.View, android.content.Context, android.database.Cursor)
setViewBinder(android.widget.SimpleCursorAdapter.ViewBinder)
setViewImage(ImageView, String)
public void changeCursorAndColumns(Cursor c, String[] from, int[] to)
同时更改Cursor与View的映射关系。
参数
c 数据库游标，如果游标不可用则为null。
from 列名字列表，表示着你要绑定到UI上的列。如果游标不可用则为null。
to 展示参数“from”中的列，也就是说ListView中的视图显示的是参数“from”的列值，这些视图应该都是TextView。如果游标不可用则为null。
public CharSequence convertToString (Cursor cursor)
通过CursorToStringConverter接口实现并返回一个CharSequence 类型的值，以表示指定的Cursor。如果没有设置CursorToStringConverter，那么就会用另外的方式进行转换。如果列数为-1，或者 cursor为null返回空串，否则返回cursor.toString()。
参数
cursor 转换为CharSequence的数据库游标。
返回值
返回一个不为null的CharSequence类型来表示参数cursor。
public SimpleCursorAdapter.CursorToStringConverter getCursorToStringConverter ()
返回自定义的SimpleCursorAdapter.CursorToStringConverter的实现。
返回值
如果没有设置SimpleCursorAdapter.CursorToStringConverter，则为null。
参考
setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)
setStringConversionColumn(int)
convertToString(android.database.Cursor)
public int getStringConversionColumn ()
返回转换成String类型的列位置。
返回值
返回列位置，如果没有则返回-1。
参考
convertToString(android.database.Cursor)
setStringConversionColumn(int)
setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)
public SimpleCursorAdapter.ViewBinder getViewBinder ()
返回SimpleCursorAdapter.ViewBinder引用，这个ViewBinder用来将数据绑定到视图上的。
返回值
如果ViewBinder不存在，则返回null。
参考
bindView(android.view.View, android.content.Context, android.database.Cursor)
setViewBinder(android.widget.SimpleCursorAdapter.ViewBinder)
public void setCursorToStringConverter (SimpleCursorAdapter.CursorToStringConverter cursorToStringConverter)
设置String转换器。
参数
cursorToStringConverter String转换器,设置为null就意味着移除。
参考
setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)
setStringConversionColumn(int)
convertToString(android.database.Cursor)
public void setStringConversionColumn (int stringConversionColumn)
设置Cursor中的列要转换成String类型的位置。不过仅当未设置CursorToStringConverter时，这个列才会进行默认转换。
参数
stringConversionColumn 列位置，如果参数为-1，则使用默认转换机制。
参考
convertToString(android.database.Cursor)
setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)
public void setViewBinder (SimpleCursorAdapter.ViewBinder viewBinder)
设置视图绑定器。
参数
viewBinder 视图绑定器，可用为null删除现有的绑定器。
参考
bindView(android.view.View, android.content.Context, android.database.Cursor)
public void setViewImage (ImageView v, String value)
仅当ViewBinder不存在或是当ViewBinder不为ImageView绑定时（也就是setViewValue()返回false），则这个方法会被bindView()调用，以便为ImageView设置图片。默认情况下，参数value作为图片资源ID来看待，否则，会视为图片的Uri。 另外还可以通过过滤器来获得更灵活的设置。
参数
v 图片控件引用
value 图片资源ID，是从Cursor获取到的。
public void setViewText (TextView v, String text)
仅当ViewBinder不存在或是当ViewBinder不为TextView绑定时（也就是setViewValue()返回false），则这个方法会被bindView()调用，以便为TextView设置文本。可用重写适配器从数据库中检索过滤字符串。
参数
v 文本控件引用
value 为文本控件设置的文本信息（译者注：是从Cursor获取到的）。
public Cursor swapCursor (Cursor c)
交换两个Cursor的列以及它们的数据，并最终返回的还是旧的Cursor。不同于changeCursor(Cursor)的是，旧的Cursor非但不会关闭，而且还会返回出去。（译者注： 3.0新添的方法）
参数
c 新的Cursor对象。
返回值
返回旧的Cursor引用，如果参数cursor不可用，则返回null。如果参数cursor与原来的Cursor引用相同，那么也返回null。五、补充
文章精选
ArrayAdapter和SimpleCursorAdapter例子
Android API : SimpleCursorAdapter()
示例代码
Demo_SimpleCursorAdapter（深夜未眠）.rar
SimpleCursorAdapter.CursorToStringConverter
译者署名： 深夜未眠
译者链接：http://chris1012f.javaeye.com/
版本：Android 3.0 r1
正文
一、结构
public static interface SimpleCusrorAdapter.CursorToStringConverter
java.lang.Object
android.widget.SimpleCursorAdapter.CursorToStringConverter
二、概述
这个内部接口可以在外部通过SimpleCursorAdapter.CursorToStringConverter的方式定义怎样将Cursor转换成字符串。
参见
convertToString(android.database.Cursor)
三、公共方法
public abstract CharSequence convertToString (Cursor cursor)
返回CharSequence类型的值，用来表示参数cursor。
参数
cusor 需要转换成CharSequence类型的数据库游标。
返回值
返回代表参数cursor的非空字符串。
SimpleCursorAdapter.ViewBinder
译者署名： 深夜未眠
译者链接：http://chris1012f.javaeye.com/
版本：Android 3.0 r1
正文
一、结构
public static interface SimpleCusrorAdapter.ViewBinder
java.lang.Object
android.widget.SimpleCursorAdapter.ViewBinder
这个内部接口可以在外部通过SimpleCursorAdapter.ViewBinder的方式进行Cursor 与View的绑定。Android推荐我们采用这种方式进行绑定操作，而不是沿用SimpleCursorAdapter内部的方式。
参见
bindView(android.view.View, android.content.Context, android.database.Cursor)
setViewImage(ImageView, String)
public abstract boolean setViewValue (View view, Cursor cursor, int columnIndex)
将指定的列数据绑定到指定的视图上。当ViewBinder处理时，这个方法必须返回true。如果这个方法返回false， SimpleCursorAdapter将用自己的方式进行绑定操作。
参数
view 被绑定的视图。
cursor 数据库游标，绑定数据从它这里获取
columnIndex 列位置，能够在数据库游标中寻找到。
返回值
返回true意味着数据与视图已经绑定上，否则为未绑定上。
