FileDocCategorySizeDatePackage
StaggeredGrid.javaAPI DocAndroid 5.1 API9466Thu Mar 12 22:22:56 GMT 2015android.support.v17.leanback.widget

StaggeredGrid

public abstract class StaggeredGrid extends Object
A dynamic data structure that maintains staggered grid position information for each individual child. The algorithm ensures that each row will be kept as balanced as possible when prepending and appending a child.

You may keep view {@link StaggeredGrid.Location} inside StaggeredGrid as much as possible since prepending and appending views is not symmetric: layout going from 0 to N will likely produce a different result than layout going from N to 0 for the staggered cases. If a user scrolls from 0 to N then scrolls back to 0 and we don't keep history location information, edges of the very beginning of rows will not be aligned. It is recommended to keep a list of tens of thousands of {@link StaggeredGrid.Location}s which will be big enough to remember a typical user's scroll history. There are situations where StaggeredGrid falls back to the simple case where we do not need save a huge list of locations inside StaggeredGrid:

  • Only one row (e.g., a single row listview)
  • Each item has the same length (not staggered at all)

This class is abstract and can be replaced with different implementations.

Fields Summary
protected Provider
mProvider
protected int
mNumRows
protected Row[]
mRows
protected android.support.v4.util.CircularArray
mLocations
private ArrayList[]
mTmpItemPositionsInRows
protected boolean
mReversedFlow
public static final int
START_DEFAULT
A constant representing a default starting index, indicating that the developer did not provide a start index.
protected int
mStartIndex
protected int
mStartRow
protected int
mFirstIndex
Constructors Summary
Methods Summary
protected final android.support.v17.leanback.widget.StaggeredGrid$LocationappendItemToRow(int itemIndex, int rowIndex)

        Location loc = new Location(rowIndex);
        if (mLocations.size() == 0) {
            mFirstIndex = itemIndex;
        }
        mLocations.addLast(loc);
        mProvider.createItem(itemIndex, rowIndex, true);
        return loc;
    
public abstract voidappendItems(int toLimit)
Append items until the high edge reaches upTo.

public final voiddebugPrint(java.io.PrintWriter pw)

        for (int i = 0, size = mLocations.size(); i < size; i++) {
            Location loc = mLocations.get(i);
            pw.print("<" + (mFirstIndex + i) + "," + loc.row + ">");
            pw.print(" ");
            pw.println();
        }
    
public final intgetFirstIndex()
Returns the first index in the staggered grid.

        return mFirstIndex;
    
public final java.util.List[]getItemPositionsInRows(int startPos, int endPos)
Return array of Lists for all rows, each List contains item positions on that row between startPos(included) and endPositions(included). Returned value is read only, do not change it.

        for (int i = 0; i < mNumRows; i++) {
            mTmpItemPositionsInRows[i].clear();
        }
        if (startPos >= 0) {
            for (int i = startPos; i <= endPos; i++) {
                mTmpItemPositionsInRows[getLocation(i).row].add(i);
            }
        }
        return mTmpItemPositionsInRows;
    
public final intgetLastIndex()
Returns the last index in the staggered grid.

        return mFirstIndex + mLocations.size() - 1;
    
public final android.support.v17.leanback.widget.StaggeredGrid$LocationgetLocation(int index)
Returns the {@link Location} at the given index.

        if (mLocations.size() == 0) {
            return null;
        }
        return mLocations.get(index - mFirstIndex);
    
protected final intgetMaxHighRowIndex()

        int maxHighRowIndex = 0;
        for (int i = 1; i < mNumRows; i++) {
            if (mRows[i].high > mRows[maxHighRowIndex].high) {
                maxHighRowIndex = i;
            }
        }
        return maxHighRowIndex;
    
protected final intgetMaxLowRowIndex()

        int maxLowRowIndex = 0;
        for (int i = 1; i < mNumRows; i++) {
            if (mRows[i].low > mRows[maxLowRowIndex].low) {
                maxLowRowIndex = i;
            }
        }
        return maxLowRowIndex;
    
protected final intgetMinHighRowIndex()

        int minHighRowIndex = 0;
        for (int i = 1; i < mNumRows; i++) {
            if (mRows[i].high < mRows[minHighRowIndex].high) {
                minHighRowIndex = i;
            }
        }
        return minHighRowIndex;
    
protected final intgetMinLowRowIndex()

        int minLowRowIndex = 0;
        for (int i = 1; i < mNumRows; i++) {
            if (mRows[i].low < mRows[minLowRowIndex].low) {
                minLowRowIndex = i;
            }
        }
        return minLowRowIndex;
    
public final intgetNumRows()
Returns the number of rows in the staggered grid.

        return mNumRows;
    
public final intgetSize()
Returns the size of the saved {@link Location}s.

        return mLocations.size();
    
protected final android.support.v17.leanback.widget.StaggeredGrid$LocationprependItemToRow(int itemIndex, int rowIndex)

        Location loc = new Location(rowIndex);
        mFirstIndex = itemIndex;
        mLocations.addFirst(loc);
        mProvider.createItem(itemIndex, rowIndex, false);
        return loc;
    
public abstract voidprependItems(int toLimit)
Prepend items until the low edge reaches downTo.

public final voidremoveFirst()
Removes the first element.

        mFirstIndex++;
        mLocations.popFirst();
    
public final voidremoveLast()
Removes the last element.

        mLocations.popLast();
    
public voidsetProvider(android.support.v17.leanback.widget.StaggeredGrid$Provider provider)
Sets the {@link Provider} for this staggered grid.

param
provider The provider for this staggered grid.

        mProvider = provider;
    
public voidsetReversedFlow(boolean reversedFlow)


        
        mReversedFlow = reversedFlow;
    
public final voidsetRows(android.support.v17.leanback.widget.StaggeredGrid$Row[] row)
Sets the array of {@link Row}s to fill into. For views that represent a horizontal list, this will be the rows of the view. For views that represent a vertical list, this will be the columns.

param
row The array of {@link Row}s to be filled.

        if (row == null || row.length == 0) {
            throw new IllegalArgumentException();
        }
        mNumRows = row.length;
        mRows = row;
        mTmpItemPositionsInRows = new ArrayList[mNumRows];
        for (int i = 0; i < mNumRows; i++) {
            mTmpItemPositionsInRows[i] = new ArrayList(32);
        }
    
public final voidsetStart(int startIndex, int startRow)
Set the first item index and the row index to load when there are no items.

param
startIndex the index of the first item
param
startRow the index of the row

        mStartIndex = startIndex;
        mStartRow = startRow;
    
public abstract voidstripDownTo(int itemIndex)
Strip items, keep a contiguous subset of items; the subset should include at least one item on every row that currently has at least one item.

TODO: document this better