package spark.components
{

/**
 *  Displays a row of column headers and separators aligned with the grid's layout.  
 * 
 *  Headers are rendererd with the headerRenderer and separators with the columnSeparator.
 *  The layout, which can not be changed, is virtual: renderers and separators that have been 
 *  scrolled out of view are reused.
 */
public class GridColumnHeaderGroup extends Group implements IDataGridElement, IFocusManagerComponent 
{
    /**
     *  The IGridItemRenderer class used to renderer each column header.
     * 
     *  @default null
     */
    public function get headerRenderer():IFactory
    public function set headerRenderer(value:IFactory):void

    /**
     *  A visual element that's displayed in between each column.
     * 
     *  @default null
     */
    public function get columnSeparator():IFactory
    public function set columnSeparator(value:IFactory):void

    /**
     *  The DataGrid that defines the column layout and horizontal scroll position for this component.
     *  This property is set by the DataGrid after its grid skin part has been added.
     * 
     *  @default null
     */
    public function get dataGrid():DataGrid
    public function set dataGrid(value:DataGrid):void

    /**
     *  The container for columnSeparator visual elements.  By default it's an 
     *  element of the GridColumnHeaderGroup's overlay.
     */
    public function get overlayGroup():Group
    public function set overlayGroup(value:Group):void

    /**
     *  A vector of column indices corresponding to the header renderers
     *  which currently have their sort indicators visible.
     * 
     *  @default []
     */
    public function get visibleSortIndicatorIndices():Vector.<int>
    public function set visibleSortIndicatorIndices(value:Vector.<int>):void

    /**
     *  Returns true if the sort indicator for the specified column is visible.
     * 
     *  This is just a more effient version of:
     *      visibleSortIndicatorIndices.indexOf(columnIndex) != -1
     */
    public function isSortIndicatorVisible(columnIndex:int):Boolean

    /**
     *  Horizontal space on either side of a column separator that's considered to be 
     *  part of the separator for the sake of mouse event dispatching.
     * 
     *  Separators are often just one pixel wide which makes interacting with them difficult.
     *  This value is used by getSeparatorIndexAt() to give separators a wider
     *  berth, so that separator events are dispatched when the mouse is closer than 
     *  separatorMouseWidth to the horizontal midpoint of a separator. 
     * 
     *  @default 5
     */
    public function get separatorMouseWidth():Number
    public function set separatorMouseWidth(value:Number):void

    /**
     *  Returns the column index corresponding to the specified coordinates,
     *  or -1 if the coordinates are out of bounds. The coordinates are 
     *  resolved with respect to the GridColumnHeaderGroup layout target.
     * 
     *  If all of the columns or rows for the grid have not yet been scrolled
     *  into view, the returned index may only be an approximation, 
     *  based on the DataGrid's typicalItem
     *  
     *  @param x The pixel's x coordinate relative to the columnHeaderGroup
     *  @param y The pixel's y coordinate relative to the columnHeaderGroup
     *  @return the index of the column or -1 if the coordinates are out of bounds. 
     */
    public function getHeaderIndexAt(x:Number, y:Number):int

    /**
     *  Returns the column separator index corresponding to the specified 
     *  coordinates, or -1 if the coordinates don't overlap a separator. The 
     *  coordinates are resolved with respect to the GridColumnHeaderGroup layout target.
     * 
     *  A separator is considered to "overlap" the specified location if the
     *  x coordinate is within separatorMouseWidth of separator's
     *  horizontal midpoint.
     *  
     *  The separator index is the same as the index of the column on the left
     *  (assuming that this component's layoutDirection is "rtl").  That means 
     *  that all column headers are flanked by two separators, except for the first
     *  visible column, which just has a separator on the right, and the last visible
     *  column, which just has a separator on the left.
     * 
     *  If all of the columns or rows for the grid have not yet been scrolled
     *  into view, the returned index may only be an approximation, 
     *  based on DataGrid's typicalItem.
     *  
     *  @param x The pixel's x coordinate relative to the columnHeaderGroup
     *  @param y The pixel's y coordinate relative to the columnHeaderGroup
     *  @return the index of the column or -1 if the coordinates don't overlap a separator.
     */
    public function getSeparatorIndexAt(x:Number, y:Number):int

    /**
     *  If the requested header renderer is visible, returns a reference to 
     *  the header renderer currently displayed for the specified column. 
     *  Note that once the returned header renderer is no longer visible it 
     *  may be recycled and its properties reset.  
     * 
     *  If the requested header renderer is not visible then, 
     *  each time this method is called, a new header renderer is created.  The
     *  new item renderer is not visible
     * 
     *  The width of the returned renderer is the same as for item renderers
     *  returned by DataGrid/getItemRendererAt().
     *  
     *  @param columnIndex The 0-based column index of the header renderer's column
     *  @return The item renderer or null if the column index is invalid.
     */
    public function getHeaderRendererAt(columnIndex:int):IGridItemRenderer

    /**
     *  Returns the current pixel bounds of the specified header (renderer), or null if 
     *  no such column exists.  Header bounds are reported in GridColumnHeaderGroup coordinates.
     * 
     *  If all of the visible columns preceeding the specified column have not 
     *  yet been scrolled into view, the returned bounds may only be an approximation, 
     *  based on all of the Grid's typicalItems.
     * 
     *  @param columnIndex The 0-based index of the column. 
     *  @return A Rectangle that represents the column header's pixel bounds, or null.
     */  
    public function getHeaderBounds(columnIndex:int):Rectangle
}
}

package spark.components.gridClasses
{
    /**
     *  DataGrid visual elements that must remain in sync with the grid's layout and scroll
     *  position must implement this interface.   When the DataGrid's grid skin part is added, 
     *  it will set its IDataGridElements' dataGrid property (the grid's owner is the DataGrid). 
     *  IDataGridElements should respond to this by adding listeners for dataGrid.grid scroll 
     *  position changes.  When the DataGrid is changed in a way that affects row/colunm layout, 
     *  all IDataGridElements will be invalidated.
     */
    public interface IDataGridElement extends IVisualElement, IInvalidating
    {
        /**
         *  The DataGrid whose layout and grid scroll position this element must stay in sync with.
         */
        function get dataGrid():DataGrid;
        function set dataGrid(value:DataGrid):void;        
    }
}

/**
 *  Dispatched when the mouse button is pressed over a column header.
 *
 *  @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 GridColumnHeaderGroup.
 *
 *  @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 column header.
 *
 *  @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 column header.
 *
 *  @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 column header.
 *
 *  @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 column header.
 *
 *  @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>


/**
 *  Dispatched when the mouse button is pressed over a column header.
 *
 *  @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 SEPARATOR_MOUSE_DOWN event if the mouse moves before 
 *  the button is released.
 *
 *  @eventType spark.events.GridEvent.SEPARATOR_MOUSE_DRAG
 */
<a href="Event%28name%3D%26quot%3BseparatorMouseDrag%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="separatorMouseDrag", type="spark.events.GridEvent")</a>

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

/**
 *  Dispatched when the mouse enters the area defined by a column 
 *  separator and separatorMouseWidth.
 *
 *  @eventType spark.events.GridEvent.SEPARATOR_ROLL_OVER
 */
<a href="Event%28name%3D%26quot%3BseparatorRollOver%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="separatorRollOver", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse leaves the area defined by a column 
 *  separator and separatorMouseWidth.
 *
 *  @eventType spark.events.GridEvent.SEPARATOR_ROLL_OUT
 */
<a href="Event%28name%3D%26quot%3BseparatorRollOut%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="separatorRollOut", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse is clicked over a column header separator.
 *
 *  @eventType spark.events.GridEvent.SEPARATOR_CLICK
 */
<a href="Event%28name%3D%26quot%3BseparatorClick%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="separatorClick", type="spark.events.GridEvent")</a>

/**
 *  Dispatched when the mouse is double-clicked over a column 
 *  header separator.
 *
 *  @eventType spark.events.GridEvent.SEPARATOR_DOUBLE_CLICK
 */
<a href="Event%28name%3D%26quot%3BseparatorDoubleClick%26quot%3B%2C%20type%3D%26quot%3Bspark.events.GridEvent%26quot%3B%29">Event(name="separatorDoubleClick", type="spark.events.GridEvent")</a>

/**
 *  Bottom inset, in pixels, for all header renderers. 
 * 
 *  @default 0
 */
<a href="Style%28name%3D%26quot%3BpaddingBottom%26quot%3B%2C%20type%3D%26quot%3BNumber%26quot%3B%2C%20format%3D%26quot%3BLength%26quot%3B%2C%20inherit%3D%26quot%3Bno%26quot%3B%29">Style(name="paddingBottom", type="Number", format="Length", inherit="no")</a>

/**
 *  Left inset, in pixels, for the first header renderer. 
 * 
 *  @default 0
 */
<a href="Style%28name%3D%26quot%3BpaddingLeft%26quot%3B%2C%20type%3D%26quot%3BNumber%26quot%3B%2C%20format%3D%26quot%3BLength%26quot%3B%2C%20inherit%3D%26quot%3Bno%26quot%3B%29">Style(name="paddingLeft", type="Number", format="Length", inherit="no")</a>

/**
 *  Right inset, in pixels, for the last header renderer. 
 * 
 *  @default 0
 */
<a href="Style%28name%3D%26quot%3BpaddingRight%26quot%3B%2C%20type%3D%26quot%3BNumber%26quot%3B%2C%20format%3D%26quot%3BLength%26quot%3B%2C%20inherit%3D%26quot%3Bno%26quot%3B%29">Style(name="paddingRight", type="Number", format="Length", inherit="no")</a>

/**
 *  Top inset, in pixels, for all header renderers. 
 * 
 *  @default 0
 */
<a href="Style%28name%3D%26quot%3BpaddingTop%26quot%3B%2C%20type%3D%26quot%3BNumber%26quot%3B%2C%20format%3D%26quot%3BLength%26quot%3B%2C%20inherit%3D%26quot%3Bno%26quot%3B%29">Style(name="paddingTop", type="Number", format="Length", inherit="no")</a>