Android中文API (110) —— CursorTreeAdapter

前言

　　本章內容是android.widget.CursorTreeAdapter，版本為Android 3.0 r1，翻譯來自"深夜未眠。
 

 

 

正文

　　一、結構

 

public abstract class CusrorTreeAdapter

         extends BaseExpandableListAdpater implements Filterable

 

java.lang.Object

android.widget.BaseExpandableListAdapter

         android.widget.CursorTreeAdapter

 

直接子類

         ResourceCursorTreeAdapter

間接子類

SimpleCursorTreeAdapter

 

 

　　二、概述

　　　　通過該適配類可以用一連續的游標(Coursor)對象訪問數據庫，並將查詢出來的數據展示到可伸縮的列表視圖(ExpandableListView)部件上。頂層游標(Cursor)對象(在構造器中指定)顯示全部組，後面的游標(Cursor)對象從getChildrenCursor(Cursor)獲取並展示子元素組。其中游標攜帶的結果集中必須有個名為“_id”的列，否則這個類不起任何作用。

 

　　三、構造函數

 

　　　　public CursorTreeAdapter (Cursor cursor, Context context)

           構造函數。每當數據庫的數據發生改變時，適配器將調用requery()重新查詢以顯示最新的數據。

                  參數

 　　cursor       為組(groups)提供數據的游標(Coursor)

                  context    應用程序上下文。

 

　　　　public CursorTreeAdapter (Cursor cursor, Context context, boolean autoRequery)

           構造函數。

                   參數

  　　cursor       為組(groups)提供數據的游標(Coursor)

                   context    應用程序上下文。

                         autoRequery 設置為true時，每當數據庫的數據發生改變時，適配器將調用requery()重新查詢以顯示最新的數據。

 

 

　　四、公共方法

 

　　public void changeCursor (Cursor cursor)

　　更改相關的游標為新傳入的游標。如果游標已經存在則先關閉這個已存在的游標。

　　參數

                            cursor               新游標(Cursor)對象。

 

　　public CharSequence convertToString (Cursor cursor)

　　將cursor轉換成CharSequence。子類應該重寫這個方法並轉換它們的結果。這個方法的默認實現是：當cursor為空時返回一個空串，否則直接返回調用cursor的toString()方法。

　　參數

                            cursor               將cursor轉換成CharSequence對象。                 

           返回值

                   返回CharSequence類型的值（譯者注：這個值是通過轉換參數cursor類型而獲得的。）

 

　　public Cursor getChild (int groupPosition, int childPosition)

           獲取指定組中的指定子元素的相關數據。

                  參數

                            groupPosition 組位置（該組內部含有子元素）

                            childPosition    子元素位置（相對於其它子元素）

                  返回值

                            返回指定子元素數據。

 

　　public long getChildId (int groupPosition, int childPosition)

　　獲取指定組中的指定子元素ID，這個ID在組裡一定是唯一的。聯合ID（參見getCombinedChildId(long, long)）在所有條目（所有組和所有元素）中也是唯一的。

                  參數

                            groupPosition 組位置（該組內部含有子元素）

                            childPosition    子元素位置（相對於其它子元素）

                  返回值

                  子元素關聯ID。

 

           public View getChildView (int groupPosition, int childPosition, boolean isLastChild,  View convertView, ViewGroup parent)

　　獲取一個視圖對象，顯示指定組中的指定子元素數據。

                  參數

                            groupPosition 組位置（該組內部含有子元素）

                            childPosition   子元素位置（決定返回哪個視圖）

                            isLastChild    子元素是否處於組中的最後一個

　　　　convertView 重用已有的視圖(View)對象。注意：在使用前你應該檢查一下這個視圖對象是否非空並且這個對象的類型是否合適。由此引伸出，如果該對象不能被轉換並顯示正確的數據，這個方法就會調用getChildView(int, int, boolean, View, ViewGroup)來創建一個視圖(View)對象。

                            parent            返回的視圖(View)對象始終依附於的視圖組。

                  返回值

                            指定位置上的子元素返回的視圖對象

 

　　public int getChildrenCount (int groupPosition)

           獲取指定組中的子元素個數

                  參數

                           groupPosition 組位置（決定返回哪個組的子元素個數）

                  返回值

                           返回組中的子元素個數

 

　　public Cursor getCursor ()

           返回當前適配器綁定的Cursor對象。

　　返回值

                            Cursor對象。

 

　　public Filter getFilter ()

           返回一個可以通過一種過濾模式來約束數據的過濾器。

           這個方法通常在Adapter類中實現。

　　返回值

                            返回一個用來限制數據的過濾器(Filter)對象。

 

　　public FilterQueryProvider getFilterQueryProvider ()

　　返回一個提供過濾的查詢過濾器。若過濾器為null，則不再過濾。

　　返回值

                            返回當前過濾器對象，如果不存在返回null。

                   參考

                   getFilterQueryProvider()

 

　　public Cursor getGroup (int groupPosition)

　　獲取指定組中的數據

                  參數

                            groupPosition 組位置

                  返回值

                           返回組中的數據，也就是該組中的子元素數據。

 

　　public int getGroupCount ()

           獲取組的個數

                  返回值

                           組的個數

 

　　public long getGroupId (int groupPosition)

           獲取指定組的ID，這個組ID必須是唯一的。聯合ID(參見getCombinedGroupId(long))在所有條目(所有組和所有元素)中也是唯一的。

                  參數

                            groupPosition  組位置

                  返回值

                            返回組ID

 

　　public View getGroupView (int groupPosition, boolean isExpanded, View convertView, ViewGroup parent)

           獲取顯示指定組的視圖對象。這個方法僅返回關於組的視圖對象，要想獲取子元素的視圖對象，就需要調用getChildView(int, int, boolean, View, ViewGroup)。

　　　　　　參數

                 　　groupPosition 組位置（決定返回哪個視圖）

                　　 isExpanded   該組是展開狀態還是伸縮狀態

　　　　convertView  重用已有的視圖對象。注意：在使用前你應該檢查一下這個視圖對象是否非空並且這個對象的類型是否合適。由此引伸出，如果該對象不能被轉換並顯示正確的數據，這個方法就會調用getGroupView(int, boolean, View, ViewGroup)來創建一個視圖(View)對象。

                   parent            返回的視圖對象始終依附於的視圖組。

         　　返回值

                   返回指定組的視圖對象

 

　　　　public boolean hasStableIds ()

　　　　組和子元素是否持有穩定的ID,也就是底層數據的改變不會影響到它們。

      　　返回值

                            返回一個Boolean類型的值，如果為TRUE，意味著相同的ID永遠引用相同的對象。

 

           public boolean isChildSelectable (int groupPosition, int childPosition)

           是否選中指定位置上的子元素。

                  參數

                            groupPosition 組位置（該組內部含有子元素）

                            childPosition  子元素位置

                  返回值

                  是否選中子元素

 

           public void notifyDataSetChanged (boolean releaseCursors)

           通知數據集已改變，該方法還為任何帶有緩存功能的游標提供不用釋放資源的可選功能。

                  參數

                  releaseCursors 是否釋放任何帶有緩沖功能的游標資源

 

           public void notifyDataSetChanged ()

           該方法內部實現了在每個觀察者上面調用onChanged事件。每當發現數據集有改變的情況，或者讀取到數據的新狀態時，就會調用此方法。

 

           public void notifyDataSetInvalidated ()

           該方法內部實現了在每個觀察者上面調用onInvalidated事件。每當發現數據集監控有改變的情況，比如該數據集不再有效，就會調用此方法。

 

           public void onGroupCollapsed (int groupPosition)

           當指定組收縮狀態的時候調用此方法。

                  參數

                            groupPosition 指定組收縮狀態

 

　　public Cursor runQueryOnBackgroundThread (CharSequence constraint)

　　執行含指定約束的查詢。此查詢依賴於適配器的過濾器。查詢是由FilterQueryProvider提供。如果沒有指定FilterQueryProvider，當前cursor不過濾只返回。該方法會通過changeCursor(Cursor)方法返回一個Cursor對象，並且關閉掉先前的Cursor對象。這個方法始終在後台線程執行，而不是在應用程序的主線程（或是UI線程）中運行。規定：當參數constraint為null或為空時，該方法返回原始結果。

      　　參數

                   constraint 當某個查詢需要過濾功能，使用參數constraint作為約束條件。

　　返回值

                            返回含有新的查詢結果的Cursor。

　　參考

           getFilter()

　　getFilterQueryProvider()

                 setFilterQueryProvider(android.widget.FilterQueryProvider)

 

　　　　public void setChildrenCursor (int groupPosition, Cursor childrenCursor)

　　　　為指定組子元素設置游標(Cursor)，並關閉已存在的游標。這個方法是非常有用的，當進行異步查詢操作的時候用來避免UI發生阻塞的情況。

      　　參數

                  groupPosition  組位置(組中的哪個子元素要設置游標對象)

                        childrenCursor 組子元素的游標(Cursor)

 

　　　　public void setFilterQueryProvider (FilterQueryProvider filterQueryProvider)

　　設置一個過濾器，用來過濾當前的Cursor對象。當這個適配器需要進行過濾操作時， runQuery(CharSequence)方法被調用。

      　　參數

                   filterQueryProvider  過濾生成器對象，設置為null時，就相當於移除了該生       成器 。

                  參考

                            getFilterQueryProvider()

                            runQueryOnBackgroundThread(CharSequence)

 

　　　　public void setGroupCursor (Cursor cursor)

　　　　設置組游標對象。

                  參數

                           cursor 設置組游標對象，並關閉已存在的游標對象。

 

 

　　五、受保護方法

 

　　　　protected abstract void bindChildView (View view, Context context, Cursor cursor,           boolean isLastChild)

　　　　用游標(Coursor)的方式將子元素數據綁定在一個已存在的視圖(View)對象上。

                  參數

                            view              已存在的視圖(View)對象, 也就是之前new出來的。

                            context          應用程序上下文對象

                            cursor            獲取數據的游標對象，它已經移動到正確的位置

                            IsLastChild   子元素是否處於組中的最後一個

 

　　　　protected abstract void bindGroupView (View view, Context context, Cursor cursor,        boolean isExpanded)

　　　　用游標(Coursor)的方式將組數據綁定在一個已存在的視圖(View)對象上。

                  參數

                            view              已存在的組視圖(View)對象, 也就是早先new出來的。

                            context          應用程序上下文對象，它已經移動到正確的位置

                            cursor            獲取數據的游標對象

                            isExpanded  該組是展開狀態還是伸縮狀態

 

　　　　protected abstract Cursor getChildrenCursor (Cursor groupCursor)

　　　　獲取指定組中的子元素游標對象。子類必須實現這個方法，用於在指定組中返回子元素數據。

　　如果你想用異步查詢的方式避免UI阻塞的情況發生，可能會返回null或是在稍後調用setChildrenCursor(int, Cursor)。

　　你有責任在Activity生命周期中管理這個游標對象，有一個非常好的思路：使用managedQuery(Uri, String[], String, String[], String)來管理它們。在某些情況下，適配器本身會使游標停止工作，但這個特例不會總是出現，所以我們要確保有效地管理好游標對象。

                   參數

                            groupCursor 組游標對象，決定返回哪個組中的子元素游標對象。

                   返回值

                            返回指定組中的子元素游標對象或者為null。

 

　　　　protected abstract View newChildView (Context context, Cursor cursor, boolean     isLastChild, ViewGroup parent)

　　　　創建一個新的子元素視圖並持有指向數據的游標cursor。

                   參數

                            context          應用程序上下文對象

                            cursor            獲取數據的游標對象，它已經移動到正確的位置

                            IsLastChild  子元素是否處於組中的最後一個

                            parent     新視圖(View)所依附於的父對象。

 

　　　　protected abstract View newGroupView (Context context, Cursor cursor, boolean isExpanded, ViewGroup parent)

　　　　創建一個新的組視圖並持有組中指向數據的游標cursor。

                  參數

                            context          應用程序上下文對象

                            cursor            獲取數據的游標對象，它已經移動到正確的位置

                            isExpanded  該組是否展開狀態

                            　　　　parent      新視圖(View)所依附於的父對象。

 

 

　　六、補充
 

 

         文章精選

                   說說定制自己的CursorAdapter