Flex SDK Wiki

# Spark DataGrid Selection - Functional and Design Specification ---- ### Introduction To simplify writing grid mouse event handlers, the Grid redispatches mouse events as GridEvents with additional information about the cell where the mouse event occurred. The DataGrid adds GridEvent listeners to its grid skin part to enable mouse selection and scrolling. The GridEvent class extends MouseEvent and adds Grid specific properties: * `rowIndex:int` - The index of the row where the event occurred. * `columnIndex:int` - The index of the column where the event occurred. * `column:GridColumn` - The column where the event occurred. * `grid:Grid` - The Grid associated with this event. * `item:Object` - The dataProvider item for this row. * `itemRenderer:IGridItemRenderer` - The itemRenderer that displayed this cell. All of the properties from the MouseEvent that triggered the GridEvent are carried over to the GridEvent. 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. GridEvents bubble from the Grid to the the DataGrid that contains it, so listeners may be added to either component. ### Grid, DataGrid API Description The API for the Grid class shown below is incomplete, only the methods and metadata relevant to this document are shown. The event metadata listed here is present in both DataGrid and Grid classes. package spark.components { /** * Dispatched when the mouse button is pressed over a Grid cell. * * @eventType spark.events.GridEvent.GRID_MOUSE_DOWN */ Event(name="gridMouseDown", type="spark.events.GridEvent") /** * Dispatched after a GRID_MOUSE_DOWN event if the mouse moves before the button is released. * * @eventType spark.events.GridEvent.GRID_MOUSE_DRAG */ Event(name="gridMouseDrag", type="spark.events.GridEvent") /** * 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 */ Event(name="gridMouseUp", type="spark.events.GridEvent") /** * Dispatched when the mouse enters a grid cell. * * @eventType spark.events.GridEvent.GRID_ROLL_OVER */ Event(name="gridRollOver", type="spark.events.GridEvent") /** * Dispatched when the mouse leaves a grid cell. * * @eventType spark.events.GridEvent.GRID_ROLL_OUT */ Event(name="gridRollOut", type="spark.events.GridEvent") /** * Dispatched when the mouse is clicked over a cell * * @eventType spark.events.GridEvent.GRID_CLICK */ Event(name="gridClick", type="spark.events.GridEvent") /** * Dispatched when the mouse is double clicked over a cell * * @eventType spark.events.GridEvent.GRID_DOUBLE_CLICK */ Event(name="gridDoubleClick", type="spark.events.GridEvent") 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 } } ### GridEvent API Description /** * 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. * *

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.

* * @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 type property for a separatorMouseDrag GridEvent. * * @eventType separatorMouseDrag */ public static const SEPARATOR_MOUSE_DRAG:String = "separatorMouseDrag"; /** * The value of the type property for a separatorClick GridEvent. * * @eventType separatorClick */ public static const SEPARATOR_CLICK:String = "separatorClick"; /** * The value of the type property for a separatorDoubleClick GridEvent. * * @eventType separatorDoubleClick */ public static const SEPARATOR_DOUBLE_CLICK:String = "separatorDoubleClick"; /** * The value of the type property for a separatorMouseDown GridEvent. * * @eventType separatorMouseDown */ public static const SEPARATOR_MOUSE_DOWN:String = "separatorMouseDown"; /** * The value of the type property for a separatorMouseUp GridEvent. * * @eventType separatorMouseUp */ public static const SEPARATOR_MOUSE_UP:String = "separatorMouseUp"; /** * The value of the type property for a separatorRollOut GridEvent. * * @eventType separatorRollOut */ public static const SEPARATOR_ROLL_OUT:String = "separatorRollOut"; /** * The value of the type 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; } }