package spark.components
{

/**
 *  Dispatched when the mouse button is pressed over a Grid cell.
 *
 *  @eventType spark.events.GridEvent.GRID_MOUSE_DOWN
 */
<a href="Event%28name%3D%26quot%3BgridMouseDown%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridMouseDown", type="spark.events.GridEvent")</a>


/**
 *  Dispatched after a GRID_MOUSE_DOWN event if the mouse moves before the button is released.
 *
 *  @eventType spark.events.GridEvent.GRID_MOUSE_DRAG
 */
<a href="Event%28name%3D%26quot%3BgridMouseDrag%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridMouseDrag", type="spark.events.GridEvent")</a>

/**
 *  Dispatched after a GRID_MOUSE_DOWN event when the mouse button is released, even
 *  if the mouse is no longer within the Grid.
 *
 *  @eventType spark.events.GridEvent.GRID_MOUSE_UP
 */
<a href="Event%28name%3D%26quot%3BgridMouseUp%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridMouseUp", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse enters a grid cell.
 *
 *  @eventType spark.events.GridEvent.GRID_ROLL_OVER
 */
<a href="Event%28name%3D%26quot%3BgridRollOver%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridRollOver", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse leaves a grid cell.
 *
 *  @eventType spark.events.GridEvent.GRID_ROLL_OUT
 */
<a href="Event%28name%3D%26quot%3BgridRollOut%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridRollOut", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse is clicked over a cell
 *
 *  @eventType spark.events.GridEvent.GRID_CLICK
 */
<a href="Event%28name%3D%26quot%3BgridClick%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridClick", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse is double clicked over a cell
 *
 *  @eventType spark.events.GridEvent.GRID_DOUBLE_CLICK
 */
<a href="Event%28name%3D%26quot%3BgridDoubleClick%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="gridDoubleClick", type="spark.events.GridEvent")</a>

public class Grid extends Group
{
    /**
     *  This method is called when a MOUSE_DOWN event occurs within the grid and 
     *  for all subsequent MOUSE_MOVE events until the button is released (even if the 
     *  mouse leaves the grid).  The last event in such a "down drag up" gesture is 
     *  always a MOUSE_UP.  By default this method dispatches GRID_MOUSE_DOWN, 
     *  GRID_MOUSE_DRAG, or a GRID_MOUSE_UP event in response to the the corresponding
     *  mouse event.  The GridEvent's rowIndex, columnIndex, column, item, and itemRenderer 
     *  properties correspond to the grid cell under the mouse.  
     * 
     *  @param event A MOUSE_DOWN, MOUSE_MOVE, or MOUSE_UP MouseEvent from a down/move/up gesture initiated within the grid.
     */    
    protected function grid_mouseDownDragUpHandler(event:MouseEvent):void

    /**
     *  This method is called whenever a MOUSE_MOVE event occurs within the grid
     *  without the button pressed.  By default it dispatches a GRID_ROLL_OVER for the
     *  first MOUSE_MOVE GridEvent whose location is within a grid cell, and a 
     *  GRID_ROLL_OUT GridEvent when the mouse leaves a cell.  Listeners are guaranteed
     *  to receive a GRID_ROLL_OUT event for every GRID_ROLL_OVER event.
     * 
     *  @param event A MOUSE_MOVE MouseEvent within the grid, without the button pressed.
     * 
     *  @langversion 3.0
     *  @playerversion Flash 10
     *  @playerversion AIR 2.0
     *  @productversion Flex 4.5
     */    
    protected function grid_mouseMoveHandler(event:MouseEvent):void

    /**
     *  This method is called whenever a ROLL_OUT occurs on the grid.
     *  By default it dispatches a GRID_ROLL_OUT event.
     * 
     *  @param event A ROLL_OUT MouseEvent from the grid.
     */       
    protected function grid_mouseRollOutHandler(event:MouseEvent):void

    /**
     *  This method is called whenever a CLICK MouseEvent occurs on the grid if both
     *  the corresponding down and up events occur within the same grid cell.
     *  By default it dispatches a GRID_CLICK event.
     * 
     *  @param event A CLICK MouseEvent from the grid.
     */       
    protected function grid_clickHandler(event:MouseEvent):void

    /**
     *  This method is called whenever a DOUBLE_CLICK MouseEvent occurs on the grid
     *  if the corresponding sequence of down and up events occur within the same grid cell.
     *  By default it dispatches a GRID_DOUBLE_CLICK event.
     * 
     *  @param event A DOUBLE_CLICK MouseEvent from the grid.     
     */       
    protected function grid_doubleClickHandler(event:MouseEvent):void

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

}
}

/**
 *  An extended mouse event that includes additional grid specific information based
 *  on the event's location relative to a grid cell: the row and column index, the 
 *  GridColumn object, the dataProvider item that corresponds to the row, and the 
 *  item renderer.  GridEvents are dispatched by the Grid class.
 * 
 *  <p>In general, GridEvents have a one to one correspondence with MouseEvents.  They are 
 *  dispatched in response to mouse events that have "bubbled" from some Grid descendant
 *  to the Grid itself.   One significant difference is that listeners are guaranteed to
 *  see an entire down-drag-up mouse gesture, even if the drag and up parts of the
 *  gesture do not occur over the grid.   The gridMouseDrag event corresponds to a 
 *  mouse move event with the button held down.</p> 
 * 
 *  @see spark.components.Grid
 */
public class GridEvent extends MouseEvent
{
    /**
     *  The value of the type property for a gridMouseDown GridEvent.
     *
     *  @eventType gridMouseDown
     */    
    public static const GRID_MOUSE_DOWN:String = "gridMouseDown";

    /**
     *  The value of the type property for a gridMouseDrag GridEvent.  This event is
     *  only dispatched when a listener has handled a mouseDown event, and then only while the
     *  mouse moves with the button held down.
     *
     *  @eventType gridMouseDrag
     */    
    public static const GRID_MOUSE_DRAG:String = "gridMouseDrag";

    /**
     *  The value of the type property for a gridMouseUp GridEvent.
     *
     *  @eventType gridMouseUp
     */    
    public static const GRID_MOUSE_UP:String = "gridMouseUp";

    /**
     *  The value of the type property for a gridClick GridEvent.
     *
     *  @eventType gridClick
     */    
    public static const GRID_CLICK:String = "gridClick";

    /**
     *  The value of the type property for a gridDoubleClick GridEvent.
     *
     *  @eventType gridDoubleClick
     */    
    public static const GRID_DOUBLE_CLICK:String = "gridDoubleClick";

    /**
     *  The value of the type property for a gridRollOver GridEvent.
     *
     *  @eventType gridRollOver
     */    
    public static const GRID_ROLL_OVER:String = "gridRollOver";

    /**
     *  The value of the type property for a gridRollOut GridEvent.
     *
     *  @eventType gridRollOut
     */    
    public static const GRID_ROLL_OUT:String = "gridRollOut";

    /**
     *  The value of the <code>type</code> property for a separatorMouseDrag GridEvent.
     *
     *  @eventType separatorMouseDrag
     */  
    public static const SEPARATOR_MOUSE_DRAG:String = "separatorMouseDrag";

    /**
     *  The value of the <code>type</code> property for a separatorClick GridEvent.
     *
     *  @eventType separatorClick
     */      
    public static const SEPARATOR_CLICK:String = "separatorClick";

    /**
     *  The value of the <code>type</code> property for a separatorDoubleClick GridEvent.
     *
     *  @eventType separatorDoubleClick
     */      
    public static const SEPARATOR_DOUBLE_CLICK:String = "separatorDoubleClick";

    /**
     *  The value of the <code>type</code> property for a separatorMouseDown GridEvent.
     *
     *  @eventType separatorMouseDown
     */  
    public static const SEPARATOR_MOUSE_DOWN:String = "separatorMouseDown";

    /**
     *  The value of the <code>type</code> property for a separatorMouseUp GridEvent.
     *
     *  @eventType separatorMouseUp
     */      
    public static const SEPARATOR_MOUSE_UP:String = "separatorMouseUp";

    /**
     *  The value of the <code>type</code> property for a separatorRollOut GridEvent.
     *
     *  @eventType separatorRollOut
     */      
    public static const SEPARATOR_ROLL_OUT:String = "separatorRollOut";

    /**
     *  The value of the <code>type</code> property for a separatorRollOver GridEvent.
     *
     *  @eventType separatorRollOver
     */  
    public static const SEPARATOR_ROLL_OVER:String = "separatorRollOver";

    /**
     *  GridEvents dispatched by the Grid class in response to MouseEvents are constructed with
     *  the incoming mouse event's properties.   The grid event's x,y location, i.e. the value of
     *  its localX and localY properties, is defined relative to the entire grid, not just the 
     *  part of the grid that has been scrolled into view.   Similarly, the event's row and column
     *  indices may correspond to a cell that has not been scrolled into view.
     *
     *  @param type Distinguishes the mouse gesture that caused this event to be dispatched.
     *  @param bubbles Specifies whether the event can bubble up the display list hierarchy.
     *  @param cancelable Specifies whether the behavior associated with the event can be prevented.
     *  @param localX The event's x coordinate relative to grid.
     *  @param localY The event's y coordinate relative to grid.
     *  @param relatedObject The relatedObject property of the MouseEvent that triggered this GridEvent.
     *  @param itemRenderer The visible item renderer where the event occurred or null.
     *  @param ctrlKey Whether the Control key is down.
     *  @param altKey Whether the Alt key is down.
     *  @param shiftKey Whether the Shift key is down.
     *  @param buttonDown Whether the Control key is down.
     *  @param delta Not used.
     *  @param rowIndex The index of the row where the event occurred, or -1.
     *  @param columnIndex The index of the column where the event occurred, or -1.
     *  @param column The column where the event occurred or null.
     *  @param item The dataProvider item at rowIndex.
     */
    public function GridEvent(
        type:String,
        bubbles:Boolean = false,
        cancelable:Boolean = false,
        localX:Number = NaN,
        localY:Number = NaN,        
        relatedObject:InteractiveObject = null,
        ctrlKey:Boolean = false,
        altKey:Boolean = false,
        shiftKey:Boolean = false,
        buttonDown:Boolean = false,
        delta:int = 0,
        rowIndex:int = -1,
        columnIndex:int = -1,
        column:GridColumn = null,
        item:Object = null,
        itemRenderer:IGridItemRenderer = null,)

    /**
     *  The index of the row where the event occurred, or -1 if the event
     *  did not occur over a grid row.
     */
    public var rowIndex:int;

    /**
     *  The index of the column where the event occurred, or -1 if the event did not occur
     *  over a grid column.
     */
    public var columnIndex:int;

    /**
     *  The column where the event occurred, or null if the event did not occur
     *  over a column.
     */
    public var column:GridColumn;

    /**
     *  The Grid associated with this event.
     */
    public function get grid():Grid;

    /**
     *  The dataProvider item for this row, or null if the event did not occur over 
     *  a grid row.
     */    
    public var item:Object;

    /**
     *  The itemRenderer that displayed this cell, or null if the event did not occur over
     *  a visible cell. 
     */       
    public var itemRenderer:IGridItemRenderer;
}
}