v17/leanback/src/android/support/v17/leanback/widget/StaggeredGrid.java - fp2-dev/platform/frameworks/support - Gitiles

 /*
  * Copyright (C) 2014 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
  * in compliance with the License. You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software distributed under the License
  * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
 package android.support.v17.leanback.widget;

 import android.support.v4.util.CircularArray;

 import java.io.PrintWriter;
 import java.util.ArrayList;
 import java.util.List;

 /**
  * 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.
  *
  * <p>
  * 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:
  * <ul>
  *   <li>Only one row (e.g., a single row listview)</li>
  *   <li> Each item has the same length (not staggered at all)</li>
  * </ul>
  *
  * <p>
  * This class is abstract and can be replaced with different implementations.
  */
 abstract class StaggeredGrid {

     /**
      * TODO: document this
      */
     public static interface Provider {
         /**
          * Return how many items are in the adapter.
          */
         public abstract int getCount();

         /**
          * Create the object at a given row.
          */
         public abstract void createItem(int index, int row, boolean append);
     }

     /**
      * Location of an item in the grid. For now it only saves row index but
      * more information may be added in the future.
      */
     public final static class Location {
         /**
          * The index of the row for this Location.
          */
         public final int row;

         /**
          * Create a Location with the given row index.
          */
         public Location(int row) {
             this.row = row;
         }
     }

     /**
      * TODO: document this
      */
     public final static class Row {
         /**
          * first view start location
          */
         public int low;
         /**
          * last view end location
          */
         public int high;
     }

     protected Provider mProvider;
     protected int mNumRows = 1; // mRows.length
     protected Row[] mRows;
     protected CircularArray<Location> mLocations = new CircularArray<Location>(64);
     private ArrayList<Integer>[] mTmpItemPositionsInRows;
     protected boolean mReversedFlow;

     /**
      * A constant representing a default starting index, indicating that the
      * developer did not provide a start index.
      */
     public static final int START_DEFAULT = -1;

     // the first index that grid will layout
     protected int mStartIndex = START_DEFAULT;
     // the row to layout the first index
     protected int mStartRow = START_DEFAULT;

     protected int mFirstIndex = -1;

     public void setReversedFlow(boolean reversedFlow) {
         mReversedFlow = reversedFlow;
     }

     /**
      * Sets the {@link Provider} for this staggered grid.
      *
      * @param provider The provider for this staggered grid.
      */
     public void setProvider(Provider provider) {
         mProvider = provider;
     }

     /**
      * 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.
      */
     public final void setRows(Row[] row) {
         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);
         }
     }

     /**
      * Returns the number of rows in the staggered grid.
      */
     public final int getNumRows() {
         return mNumRows;
     }

     /**
      * 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
      */
     public final void setStart(int startIndex, int startRow) {
         mStartIndex = startIndex;
         mStartRow = startRow;
     }

     /**
      * Returns the first index in the staggered grid.
      */
     public final int getFirstIndex() {
         return mFirstIndex;
     }

     /**
      * Returns the last index in the staggered grid.
      */
     public final int getLastIndex() {
         return mFirstIndex + mLocations.size() - 1;
     }

     /**
      * Returns the size of the saved {@link Location}s.
      */
     public final int getSize() {
         return mLocations.size();
     }

     /**
      * Returns the {@link Location} at the given index.
      */
     public final Location getLocation(int index) {
         if (mLocations.size() == 0) {
             return null;
         }
         return mLocations.get(index - mFirstIndex);
     }

     /**
      * Removes the first element.
      */
     public final void removeFirst() {
         mFirstIndex++;
         mLocations.popFirst();
     }

     /**
      * Removes the last element.
      */
     public final void removeLast() {
         mLocations.popLast();
     }

     public final void debugPrint(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();
         }
     }

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

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

     protected final Location appendItemToRow(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;
     }

     /**
      * Append items until the high edge reaches upTo.
      */
     public abstract void appendItems(int toLimit);

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

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

     protected final Location prependItemToRow(int itemIndex, int rowIndex) {
         Location loc = new Location(rowIndex);
         mFirstIndex = itemIndex;
         mLocations.addFirst(loc);
         mProvider.createItem(itemIndex, rowIndex, false);
         return loc;
     }

     /**
      * 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.
      */
     public final List<Integer>[] getItemPositionsInRows(int startPos, int endPos) {
         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;
     }

     /**
      * Prepend items until the low edge reaches downTo.
      */
     public abstract void prependItems(int toLimit);

     /**
      * 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.
      *
      * <p>
      * TODO: document this better
      */
     public abstract void stripDownTo(int itemIndex);
 }
	/*
	* Copyright (C) 2014 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
	* in compliance with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software distributed under the License
	* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
	* or implied. See the License for the specific language governing permissions and limitations under
	* the License.
	*/
	package android.support.v17.leanback.widget;

	import android.support.v4.util.CircularArray;

	import java.io.PrintWriter;
	import java.util.ArrayList;
	import java.util.List;

	/**
	* 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.
	*
	* <p>
	* 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:
	* <ul>
	* <li>Only one row (e.g., a single row listview)</li>
	* <li> Each item has the same length (not staggered at all)</li>
	* </ul>
	*
	* <p>
	* This class is abstract and can be replaced with different implementations.
	*/
	abstract class StaggeredGrid {

	/**
	* TODO: document this
	*/
	public static interface Provider {
	/**
	* Return how many items are in the adapter.
	*/
	public abstract int getCount();

	/**
	* Create the object at a given row.
	*/
	public abstract void createItem(int index, int row, boolean append);
	}

	/**
	* Location of an item in the grid. For now it only saves row index but
	* more information may be added in the future.
	*/
	public final static class Location {
	/**
	* The index of the row for this Location.
	*/
	public final int row;

	/**
	* Create a Location with the given row index.
	*/
	public Location(int row) {
	this.row = row;
	}
	}

	/**
	* TODO: document this
	*/
	public final static class Row {
	/**
	* first view start location
	*/
	public int low;
	/**
	* last view end location
	*/
	public int high;
	}

	protected Provider mProvider;
	protected int mNumRows = 1; // mRows.length
	protected Row[] mRows;
	protected CircularArray<Location> mLocations = new CircularArray<Location>(64);
	private ArrayList<Integer>[] mTmpItemPositionsInRows;
	protected boolean mReversedFlow;

	/**
	* A constant representing a default starting index, indicating that the
	* developer did not provide a start index.
	*/
	public static final int START_DEFAULT = -1;

	// the first index that grid will layout
	protected int mStartIndex = START_DEFAULT;
	// the row to layout the first index
	protected int mStartRow = START_DEFAULT;

	protected int mFirstIndex = -1;

	public void setReversedFlow(boolean reversedFlow) {
	mReversedFlow = reversedFlow;
	}

	/**
	* Sets the {@link Provider} for this staggered grid.
	*
	* @param provider The provider for this staggered grid.
	*/
	public void setProvider(Provider provider) {
	mProvider = provider;
	}

	/**
	* 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.
	*/
	public final void setRows(Row[] row) {
	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);
	}
	}

	/**
	* Returns the number of rows in the staggered grid.
	*/
	public final int getNumRows() {
	return mNumRows;
	}

	/**
	* 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
	*/
	public final void setStart(int startIndex, int startRow) {
	mStartIndex = startIndex;
	mStartRow = startRow;
	}

	/**
	* Returns the first index in the staggered grid.
	*/
	public final int getFirstIndex() {
	return mFirstIndex;
	}

	/**
	* Returns the last index in the staggered grid.
	*/
	public final int getLastIndex() {
	return mFirstIndex + mLocations.size() - 1;
	}

	/**
	* Returns the size of the saved {@link Location}s.
	*/
	public final int getSize() {
	return mLocations.size();
	}

	/**
	* Returns the {@link Location} at the given index.
	*/
	public final Location getLocation(int index) {
	if (mLocations.size() == 0) {
	return null;
	}
	return mLocations.get(index - mFirstIndex);
	}

	/**
	* Removes the first element.
	*/
	public final void removeFirst() {
	mFirstIndex++;
	mLocations.popFirst();
	}

	/**
	* Removes the last element.
	*/
	public final void removeLast() {
	mLocations.popLast();
	}

	public final void debugPrint(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();
	}
	}

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

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

	protected final Location appendItemToRow(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;
	}

	/**
	* Append items until the high edge reaches upTo.
	*/
	public abstract void appendItems(int toLimit);

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

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

	protected final Location prependItemToRow(int itemIndex, int rowIndex) {
	Location loc = new Location(rowIndex);
	mFirstIndex = itemIndex;
	mLocations.addFirst(loc);
	mProvider.createItem(itemIndex, rowIndex, false);
	return loc;
	}

	/**
	* 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.
	*/
	public final List<Integer>[] getItemPositionsInRows(int startPos, int endPos) {
	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;
	}

	/**
	* Prepend items until the low edge reaches downTo.
	*/
	public abstract void prependItems(int toLimit);

	/**
	* 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.
	*
	* <p>
	* TODO: document this better
	*/
	public abstract void stripDownTo(int itemIndex);
	}