Android適配器之—SimpleCursorAdapter

結構

繼承關係

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()