Android 3.0 r1 API中文文檔(106) —— SimpleCursorAdapter

前言

　　本章內容是android.widget.SimpleCursorAdapter，版本為Android 3.0 r1，附帶示例源碼，翻譯來自"深夜未眠"。 
 

正文

　　一、結構

 

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)

                            getViewBinder()

                            setViewBinder(android.widget.SimpleCursorAdapter.ViewBinder)

                            setViewImage(ImageView, String)

                            setViewText(TextView, 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)

           getStringConversionColumn()

           setStringConversionColumn(int)

           convertToString(android.database.Cursor)

 

　　public int getStringConversionColumn ()

           返回轉換成String類型的列位置。

　　返回值

                 　　返回列位置，如果沒有則返回-1。

　　參考

                            convertToString(android.database.Cursor)

                            setStringConversionColumn(int)

                 setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)

                            getCursorToStringConverter()

 

　　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)

 　　        getStringConversionColumn()

 　　        setStringConversionColumn(int)

 　　        convertToString(android.database.Cursor)

 

　　public void setStringConversionColumn (int stringConversionColumn)

　　設置Cursor中的列要轉換成String類型的位置。不過僅當未設置CursorToStringConverter時，這個列才會進行默認轉換。

                   參數

                            stringConversionColumn 列位置，如果參數為-1，則使用默認轉換機制。

                   參考

    　　     convertToString(android.database.Cursor)

  　　       getStringConversionColumn()

 　　        setCursorToStringConverter(android.widget.SimpleCursorAdapter.CursorToStringConverter)

  　　       getCursorToStringConverter()

 

　　public void setViewBinder (SimpleCursorAdapter.ViewBinder viewBinder)

　　設置視圖綁定器。

                   參數

                            viewBinder 視圖綁定器，可用為null刪除現有的綁定器。

                   參考

     　　    bindView(android.view.View, android.content.Context, android.database.Cursor)

    　　     getViewBinder()

 

　　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)

                   setViewText(TextView, String)

 

 

　　三、公共方法

 

　　public abstract boolean setViewValue (View view, Cursor cursor, int columnIndex)

　　將指定的列數據綁定到指定的視圖上。當ViewBinder處理時，這個方法必須返回true。如果這個方法返回false， SimpleCursorAdapter將用自己的方式進行綁定操作。

                   參數

                            view                         被綁定的視圖。

                            cursor                      數據庫游標，綁定數據從它這裡獲取

                            columnIndex          列位置，能夠在數據庫游標中尋找到。

                   返回值

                            返回true意味著數據與視圖已經綁定上，否則為未綁定上。