package spark.components
{

public class Grid extends Group
{
    /**
     *  If necessary, set the verticalScrollPosition and horizontalScrollPosition 
     *  properties so that the specified cell is completely visible.  If columnIndex
     *  is -1, then just adjust the verticalScrollPosition so that the specified
     *  row is visible.
     */
    public function ensureCellIsVisible(rowIndex:int, columnIndex:int = -1):void

    /**
     *  True if the specified cell is at least partially visible.  If columnIndex == -1 then 
     *  true is returned if the specified row is at least partially visible.
     *  
     *  @param rowIndex The 0-based row index of the item renderer's cell.
     *  @param columnIndex The 0-based column index of the item renderer's cell.
     *  @return True if the specified cell (or row if columnIndex == -1) is at least partially visible
     */ 
    public function isCellVisible(rowIndex:int, columnIndex:int = -1):Boolean

    /**
     *  Return the dataProvider indices of the currently visible rows.  Note that the 
     *  item renderers for the first and last rows may only be partially visible.  The 
     *  returned vector's contents are in the order they're displayed.
     * 
     *  @return A vector of the visible row indices.
     */ 
    public function getVisibleRowIndices():Vector.<int>

    /**
     *  Return the indices of the currently visible columns.  Note that the 
     *  item renderers for the first and last columns may only be partially visible.  The 
     *  returned vector's contents are in the order they're displayed.
     * 
     *  The following example function uses this method to compute a vector of 
     *  visible GridColumn objects.
     * 
     *  function getVisibleColumns():Vector.&lt;GridColumn&gt;
     *  {
     *      var visibleColumns = new Vector.&lt;GridColumn&gt;;
     *      for each (var columnIndex:int in grid.getVisibleColumnIndices())
     *          visibleColumns.push(grid.columns.getItemAt(columnIndex));
     *      return visibleColumns;
     *  }
     * 
     * 
     *  @return A vector of the visible column indices.
     */ 
    public function getVisibleColumnIndices():Vector.<int>

    /**
     *  Returns the current pixel bounds of the specified cell, or null if no such cell exists.
     *  Cell bounds are reported in grid coordinates.
     * 
     *  If all of the columns for the the specfied row and all of the rows preceeding 
     *  it have not yet been scrolled into view, the returned bounds may only be an approximation, 
     *  based on all of the columns' typicalItems.
     * 
     *  @param rowIndex The 0-based index of the row.
     *  @param columnIndex The 0-based index of the column. 
     *  @return A Rectangle that represents the cell's pixel bounds, or null.
     */ 
    public function getCellBounds(rowIndex:int, columnIndex:int):Rectangle

    /**
     *  Returns the current pixel bounds of the specified row, or null if no such row exists.
     *  Row bounds are reported in grid coordinates.

     *  If all of the columns for the the specfied row and all of the rows preceeding 
     *  it have not yet been scrolled into view, the returned bounds may only be an approximation, 
     *  based on all of the columns' typicalItems.
     * 
     *  @param rowIndex The 0-based index of the row.
     *  @return A Rectangle that represents the row's pixel bounds, or null.
     */
    public function getRowBounds(rowIndex:int):Rectangle

    /**
     *  Returns the current pixel bounds of the specified column, or null if no such column exists.
     *  Column bounds are reported in grid coordinates.
     * 
     *  If all of the cells in the specified column have not yet been scrolled into view, the 
     *  returned bounds may only be an approximation, based on the column's typicalItem.
     *  
     *  @param columnIndex The 0-based index of the column. 
     *  @return A Rectangle that represents the column's pixel bounds, or null.
     */
    public function getColumnBounds(columnIndex:int):Rectangle

    /**
     *  Return the row and column indices of the cell that overlaps the pixel at the 
     *  specified grid coordinate.
     *  If no such cell exists, null is returned.
     * 
     *  The example function below uses this method to compute the value of the 
     *  dataField for a grid cell.
     *  
     *  function getCellData(x:Number, y:Number):Object
     *  {
     *      var cell:CellPosition = getCellAt(x, y);
     *      if (!cell)
     *          return null;
     *      var GridColumn:column = grid.columns.getItemAt(cell.columnIndex);
     *      return grid.dataProvider.getItemAt(cell.rowIndex)<a href="column.dataField">column.dataField</a>;
     *  }
     * 
     *  @param x The pixel's x coordinate relative to the grid.
     *  @param y The pixel's y coordinate relative to the grid.
     *  @return The cell position or null.  
     */
    public function getCellAt(x:Number, y:Number):CellPosition

    /**
     *  Returns a vector of CellPosition objects which specify the row and
     *  column indices of the cells that overlap the specified grid region.  If no
     *  such cells exist, an empty vector is returned.
     *  
     *  @param x The x coordinate of the pixel at the origin of the region, relative to the grid.
     *  @param x The x coordinate of the pixel at the origin of the region, relative to the grid. 
     *  @return A vector of CellPositions.
     */
    public function getCellsAt(x:Number, y:Number, w:Number, h:Number):Vector.<CellPosition>

    /**
     *  Returns a reference to the item renderer currently displayed at the 
     *  specified cell.  If the requested item renderer is not visible then 
     *  (each time this method is called) a new item renderer is created.  If 
     *  the specified is invalid, e.g. if rowIndex == -1, 
     *  then null is returned.
     * 
     *  @param rowIndex The 0-based row index of the item renderer's cell.
     *  @param columnIndex The 0-based column index of the item renderer's cell.
     *  @return The item renderer
     */
    public function getItemRendererAt(rowIndex:int, columnIndex:int):IGridItemRenderer

    /**
     *  If the specified cell is visible, it is redisplayed.  
     *  If variableRowHeight=true, 
     *  then doing so may cause the height of the corresponding row to change.
     * 
     *  If columnIndex is -1, then the entire row is invalidated.  
     *  Similarly if rowIndex is -1, then the entire column is invalidated.
     * 
     *  This method should be called when there is a change to any aspect of 
     *  the data provider item at rowIndex that might have some 
     *  impact on the way the  specified cell is displayed. 
     *  Calling this method is similar to calling the
     *  dataProvider.itemUpdated() method, which advises the Grid that all rows
     *  displaying the specified item should be redisplayed.  
     *  Using this method can be relatively efficient, since it narrows 
     *  the scope of the change to a single cell.
     * 
     *  @param rowIndex The 0-based row index of the cell that changed, or -1.
     *
     *  @param column Index The 0-based column index of the cell that changed or -1.
     */
    public function invalidateCell(rowIndex:int, columnIndex:int):void;

    /**
     *  Clears cached column width data that had been based on the 
     *  typicalItem property, and requests a new layout pass.   
     *  Call this method if some aspect of the typicalItem 
     *  has changed that should be reflected by the Grid's layout.  
     * 
     *  This method is called automatically if the typicalItem 
     *  is changed directly. That means if the property is set to a new value 
     *  that is not "==" to current value.
     */
    public function invalidateTypicalItemRenderer():void;

    //... Remaining Grid API appears elsewhere in this spec
}
}