com.sawyer.advadapters.widget

Class RolodexArrayAdapter<G,C>

java.lang.Object

android.widget.BaseExpandableListAdapter

com.sawyer.advadapters.widget.PatchedExpandableListAdapter

com.sawyer.advadapters.widget.RolodexArrayAdapter<G,C>

All Implemented Interfaces:

ExpandableListAdapter, Filterable, HeterogeneousExpandableList

public abstract class RolodexArrayAdapter<G,C>
extends PatchedExpandableListAdapter
implements Filterable

For use with an ExpandableListView, The rolodex adapters are specifically designed to tackle the problem of organizing existing data on the fly without the need to pre-compute the groupings nor actually store the grouping data itself. Instead of having to organize your data ahead of time, you can simply pass in a list of arbitrary data and provide one simple method which determines the groupings it belongs to. Though not required, ideally this relationship would be derived from the data itself. For example, populating the adapter with a list of Person objects could derive it's groupings based on the last name. Just like an old-school rolodex.

The RolodexArrayAdapter uses a Map to organize the data under each group. The children within each grouping are backed by an ArrayList. The data can be easily modified and filtered in various ways and allows numerous display and sorting options. Additionally full support for ChoiceMode is available. By default this class delegates view generation and defining the filtering logic to subclasses.

Because of the background filtering process, all methods which mutates the underlying data are internally synchronized. This ensures a thread safe environment for internal write operations. If filtering is not required, it's strongly recommended to use the NFRolodexArrayAdapter instead.

Nested Class Summary

Nested classes/interfaces inherited from class com.sawyer.advadapters.widget.PatchedExpandableListAdapter

PatchedExpandableListAdapter.ChoiceMode, PatchedExpandableListAdapter.ChoiceModeListener

Constructor Summary

Constructors

Constructor and Description
RolodexArrayAdapter(Context activity) Constructor
RolodexArrayAdapter(Context activity, C[] items) Constructor
RolodexArrayAdapter(Context activity, Collection<C> items) Constructor

Method Summary

Modifier and Type	Method and Description
void	add(C childItem) Adds the specified items at the end of the adapter.
void	addAll(C... childItems) Adds the specified child items at the end of the adapter.
void	addAll(Collection<? extends C> childItems) Adds the specified Collection at the end of the adapter.
boolean	areGroupsSorted()
void	clear() Remove all elements from the adapter.
boolean	contains(C childItem) Tests whether this adapter contains the specified child item.
abstract G	createGroupFor(C childItem) Creates a new group object which represents the parent of the given child item.
C	getChild(int groupPosition, int childPosition)
long	getChildId(int groupPosition, int childPosition)
int	getChildrenCount(int groupPosition)
Filter	getFilter()
ArrayList<C>	getFilteredList()
G	getGroup(int groupPosition)
ArrayList<C>	getGroupChildren(int groupPosition) Gets all the children associated with the given group.
int	getGroupCount()
G	getGroupFor(C childItem) Retrieves a group object for the given child.
G	getGroupFromCacheFor(C childItem) Override to provide a caching mechanism for retrieving a group item.
long	getGroupId(int groupPosition)
ArrayList<C>	getList()
void	notifyDataSetChanged()
void	remove(C childItem) Removes the first occurrence of the specified child item from the adapter.
void	removeAll(Collection<? extends C> childItems) Convenience method which removes all occurrences in the adapter of each item in the specified collection.
void	retainAll(Collection<?> childItems) Removes all children items from this adapter that are not contained in the specified collection.
void	setList(Collection<? extends C> childItems) Resets the adapter to store a new list of children items.
void	setNotifyOnChange(boolean notifyOnChange) Controls whether methods that change the list (add(C), remove(C), clear()) automatically call notifyDataSetChanged().
void	sortAllChildren() Sorts the children of each grouping using the natural order of the items themselves.
void	sortAllChildren(Comparator<? super C> comparator) Sorts the children of each grouping using the specified comparator.
void	sortGroup(int groupPosition) Sorts the children of the specified group using the natural order of the children themselves.
void	sortGroup(int groupPosition, Comparator<? super C> comparator) Sorts the children of the specified group using the specified comparator.
void	update(int groupPosition, int childPosition, C childItem) Updates the item at the specified position in the adapter with the specified item.

Methods inherited from class com.sawyer.advadapters.widget.PatchedExpandableListAdapter

clearChoices, collapseAll, expandAll, expandAll, getCheckedChildCount, getCheckedChildIds, getCheckedChildPositions, getCheckedGroupCount, getCheckedGroupIds, getCheckedGroupPositions, getChildView, getChildView, getChoiceMode, getContext, getGroupView, getGroupView, hasAutoExpandingGroups, hasStableIds, isChildChecked, isChildSelectable, isGroupChecked, isGroupSelectable, onRestoreInstanceState, onSaveInstanceState, setChildChecked, setChoiceMode, setGroupChecked, setMultiChoiceModeListener, setOnChildClickListener, setOnGroupClickListener, startActionMode

Methods inherited from class android.widget.BaseExpandableListAdapter

areAllItemsEnabled, getChildType, getChildTypeCount, getCombinedChildId, getCombinedGroupId, getGroupType, getGroupTypeCount, isEmpty, notifyDataSetInvalidated, onGroupCollapsed, onGroupExpanded, registerDataSetObserver, unregisterDataSetObserver

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RolodexArrayAdapter

public RolodexArrayAdapter(Context activity)

Constructor

Parameters:

activity - Context used for inflating views

RolodexArrayAdapter

public RolodexArrayAdapter(Context activity,
                           C[] items)

Constructor

Parameters:

activity - Context used for inflating views

items - The items to represent within the adapter.

RolodexArrayAdapter

public RolodexArrayAdapter(Context activity,
                           Collection<C> items)

Constructor

Parameters:

activity - Context used for inflating views

items - The items to represent within the adapter.

Method Detail

add

public void add(C childItem)

Adds the specified items at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

childItem - The child item to add at the end of the adapter.

addAll

public void addAll(Collection<? extends C> childItems)

Adds the specified Collection at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

childItems - The Collection of children items to add at the end of the adapter.

addAll

@SafeVarargs
public final void addAll(C... childItems)

Adds the specified child items at the end of the adapter. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

childItems - The child items to add at the end of the adapter.

areGroupsSorted

public boolean areGroupsSorted()

Returns:

Whether groups are automatically sorted. Default is true.

clear

public void clear()

Remove all elements from the adapter.

contains

public boolean contains(C childItem)

Tests whether this adapter contains the specified child item.

Parameters:

childItem - The child item to search for

Returns:

true if the child item is an element of this adapter. false otherwise

createGroupFor

public abstract G createGroupFor(C childItem)

Creates a new group object which represents the parent of the given child item. This is used to determine what group the child item will fall under. Do not attempt to return a cached group object here. See getGroupFromCacheFor(Object) for that behavior.

It's recommended that the group object returned is immutable, or whose hashcode is based on an immutable field(s). A mutable object is fine so long as it's not modified during the lifespan of this adapter.

Parameters:

childItem - The child item for which a group instance will be created for.

Returns:

An immutable group class object which represents the given child item. Do not return null.

getChild

public C getChild(int groupPosition,
                  int childPosition)

Specified by:

getChild in interface ExpandableListAdapter

getChildId

public long getChildId(int groupPosition,
                       int childPosition)

Specified by:

getChildId in interface ExpandableListAdapter

getChildrenCount

public int getChildrenCount(int groupPosition)

Specified by:

getChildrenCount in interface ExpandableListAdapter

getFilter

public Filter getFilter()

Specified by:

getFilter in interface Filterable

getFilteredList

public ArrayList<C> getFilteredList()

Returns:

The shown filtered list. If no filter is applied, then the original list is returned.

getGroup

public G getGroup(int groupPosition)

Specified by:

getGroup in interface ExpandableListAdapter

getGroupChildren

public ArrayList<C> getGroupChildren(int groupPosition)

Gets all the children associated with the given group.

Parameters:

groupPosition - The position of the group.

Returns:

the ArrayList of children found within the specified group.

getGroupCount

public int getGroupCount()

Specified by:

getGroupCount in interface ExpandableListAdapter

getGroupFor

public final G getGroupFor(C childItem)

Retrieves a group object for the given child. Attempts to look in cache before requesting to construct one. By default nothing is cached. Override getGroupFromCacheFor(Object) if you wish to provide your own cache implementation.

Parameters:

childItem - Child item to look for

Returns:

Group associated with child. Will never return null.

getGroupFromCacheFor

public G getGroupFromCacheFor(C childItem)

Override to provide a caching mechanism for retrieving a group item. Caching can help reduce the number of createGroupFor(Object) invocations. By default, no caching is provided by the adapter. This method normally returns null.

It's only recommended to implement this method if one of the following are true:

• You can pre-populate the cache with all the child to group relations.
• The cache will be lazy-loaded and saved for later re-use.
• Instantiating your group object is a pretty hefty call.
• You are constantly mutating the adapter.

Pulling from cache is primarily used when mutating the adapter. It is never used nor needed by any of the getters.

Additionally, the group object returned should be immutable, or whose hashcode is based on an immutable field(s). A mutable object is fine so long as it's not modified during the lifespan of this adapter.

Parameters:

childItem - The child item for which a group object will be returned for.

Returns:

The group object from cache which represents the given child item. Null if the group is not found in cache.

getGroupId

public long getGroupId(int groupPosition)

Specified by:

getGroupId in interface ExpandableListAdapter

getList

public ArrayList<C> getList()

Returns:

The original (unfiltered) list of items stored within the Adapter

setList

public void setList(Collection<? extends C> childItems)

Resets the adapter to store a new list of children items. Convenient way of calling clear(), then addAll(Collection) without having to worry about an extra notifyDataSetChanged() invoked in between. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

childItems - New list of children items to store within the adapter.

notifyDataSetChanged

public void notifyDataSetChanged()

Overrides:

notifyDataSetChanged in class BaseExpandableListAdapter

remove

public void remove(C childItem)

Removes the first occurrence of the specified child item from the adapter.

Parameters:

childItem - The child item to remove.

removeAll

public void removeAll(Collection<? extends C> childItems)

Convenience method which removes all occurrences in the adapter of each item in the specified collection.

Parameters:

childItems - The collection of child items to remove

retainAll

public void retainAll(Collection<?> childItems)

Removes all children items from this adapter that are not contained in the specified collection.

Parameters:

childItems - The collection of children items to retain

setNotifyOnChange

public void setNotifyOnChange(boolean notifyOnChange)

Controls whether methods that change the list (add(C), remove(C), clear()) automatically call notifyDataSetChanged(). If set to false, caller must manually call notifyDataSetChanged() to have the changes reflected in the attached view.

The default is true, and calling notifyDataSetChanged() resets the flag to true.

Parameters:

notifyOnChange - if true, modifications to the list will automatically call notifyDataSetChanged()

sortAllChildren

public void sortAllChildren()

Sorts the children of each grouping using the natural order of the items themselves. This requires the items to have implemented Comparable and is equivalent of passing null to sortAllChildren(Comparator). This will not sort groups themselves.

Throws:

ClassCastException - If the comparator is null and the stored items do not implement Comparable, or if compareTo throws for any pair of items.

sortAllChildren

public void sortAllChildren(Comparator<? super C> comparator)

Sorts the children of each grouping using the specified comparator. This will not sort groups themselves.

Parameters:

comparator - Used to sort the child items contained in this adapter. Null to use an item's Comparable interface.

Throws:

ClassCastException - If the comparator is null and the stored items do not implement Comparable, or if compareTo throws for any pair of items.

sortGroup

public void sortGroup(int groupPosition)

Sorts the children of the specified group using the natural order of the children themselves. This requires the child items to have implemented Comparable and is equivalent of passing null to sortGroup(int, Comparator). This will not sort groups themselves.

Throws:

ClassCastException - If the comparator is null and the stored children do not implement Comparable, or if compareTo throws for any pair of items.

sortGroup

public void sortGroup(int groupPosition,
                      Comparator<? super C> comparator)

Sorts the children of the specified group using the specified comparator. This will not sort groups themselves.

Parameters:

comparator - Used to sort the child items contained within a group. Null to use an item's Comparable interface.

Throws:

ClassCastException - If the comparator is null and the stored children do not implement Comparable, or if compareTo throws for any pair of items.

update

public void update(int groupPosition,
                   int childPosition,
                   C childItem)

Updates the item at the specified position in the adapter with the specified item. This operation does not change the overall size of the adapter but will relocate the item to a new group if needed. Will repeat the last filtering request if invoked while filtered results are being displayed.

Parameters:

groupPosition - The group location at which to put the specified child

childPosition - The child location at which to put the specified item

childItem - The new item to replace with the old