Android中文API (110) —— CursorTreeAdapter

前言

　　本章内容是android.widget.CursorTreeAdapter，版本为Android 3.0 r1，翻译来自"深夜未眠"，欢迎访问它的博客："http://chirs1012f.javaeye.com/"，再次感谢"深夜未眠" ！期待你一起参与Android API的翻译，联系我[email protected]。

 

声明

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

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

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

 

正文

　　一、结构

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

 

　　七、公告

　　　　预计翻译组第五个合集与2011年4月6日发布，敬请期待！