Flex SDK Wiki

# Spark DataGrid - Functional and Design Specification ---- ## Glossary **cell** \- One element of a grid; the intersection of a row and column. **column heading, column header** \- A column heading is the title that appears above one column, and the column header is the group that contains all of the column headings. **data item** \- An element of the grid's dataProvider. Different aspects of a single data item are used to display all of the cells in a grid row. **grid** \- A two dimensional table of cells, like a simple spreadsheet or an HTML table. **indicator** \- A visual element that highlights a property of a grid cell or row. **IPE** \- An [ItemPendingError](AsyncListView%20Specification). Some dataProviders backed by remote collections throw an IPE to indicate that the requested data item isn't available yet. **item renderer** \- A visual element used to render the contents of a grid cell. Also the factory (IFactory) used to create the visual elements. And sadly: also the class that such a factory represents. **row, column** \- The vertical and horizontal addresses of a grid cell. **separator** \- A visual element placed in between rows or columns. **smooth scrolling** \- For DataGrid: indicates that the scrollbar thumb corresponds to the pixel origin of the grid's viewport. In contrast to row-quantized scrolling, where the first grid row displayed is always completely visible because the scrollbar thumb's position correspond to a row index, not a pixel offset. ## Summary and Background DataGrid is a Spark component that displays a mutable list of data items in a scrollable table or "grid", one item per row. Each of the grid's columns displays a value based on the item for the corresponding row. The DataGrid's list of columns is mutable: columns can be moved, added, and removed. The DataGrid displays a row of column headings above the scrollable grid. Column headings are used to identify what's displayed in each column and the and can be configured to sort the [DatGrid](Spark%20DataGrid)'s list according to a per-column sort key. Columns can be interactively resized or moved. Each grid cell can contain any Flex visual element, from simple graphic elements, to complex forms. DataGrid supports interactive (and progamatic) row or cell selection based on mouse or keyboard input. Single and multiple selection modes are supported. DataGrid also supports interactively editing row or cell values. DataGrid can support large grids efficiently. It's possible to smoothly scroll through a list of tens of thousands of rows (items) and hundreds of columns. Row heights can vary and can be automatically sized to reflect their contents. Initial column widths can be based on the rendered size of a typical data item. DataGrid is skinnable. The DataGrid skin is responsible for laying out the grid, column header, and scroller and for configuring the graphic elements used to render visual elements used as indicators, separators, and backgrounds. The DataGrid skin can also provide a default item renderer, used to display the contents of each cell, for columns that don't specify one. The Spark DataGrid is quite similar to MX version, both in terms of overall structure and features. Some notable differences: * Spark DataGrid is not a List subclass. This was done for both implementation and semantic reasons. Not extending s:List affords the DataGrid implementation much flexibility and eliminates the need to carry forward properties and features designed to enable list uses cases like menus and combo boxes. * The MX DataGrid's scrollbars control the first visible row, i.e. scrolling is always in row-sized increments. The Spark DataGrid supports "smooth scrolling", i.e. moving the scrollbar's thumb changes the pixel origin of the DataGrid's viewport. This is the most common scrolling mode for grids and tables in other toolkits, or for tabular data renderer with HTML. * All visual elements of the Spark DataGrid can be defined declaratively, in MXML, including the (row) hover and selection indicators, row and column separators. The MX DataGrid required subclassing to change many of these visual elements. * To simplify writing custom mouse event handlers, Spark DataGrid redispatches mouse events that occur over the grid as "[GridEvents](Data%20Grid%20Mouse%20Events)". [GridEvents](Data%20Grid%20Mouse%20Events) add the row and column location of the event and simplify handling press-drag-release mouse events by guaranteeing that listeners will receive events that correspond to the entire gesture, even if the mouse leaves the grid. * Spark DataGrid columns don't support styles directly as their MX counterparts do. In Spark one can use the styleName property for item renderers instead. * This version of the Spark DataGrid does not support locked rows and columns or "grouped" headers. A future release will add these features. * The Spark DataGrid doesn't include intrinsic support for [ItemPendingError](AsyncListView%20Specification) (IPE) handling. This support is available separately, with the [ASycnListView](AsyncListView%20Specification) wrapper class. ## Usage Scenarios Disclaimer: The usage scenarios in this section focus on the [GridColumn](Data%20Grid%20Visuals) [GridItemRenderer](Data%20Grid%20Visuals) classes as well as DataGrid's visual element properties. The goal of this section is to highlight the Spark DataGrid features that are substantially different from the MX DataGrid class. It is not intended to be a comprehensive overview of the API. DataGrid displays the items in its IList dataProvider according to its list of [GridColumn](Data%20Grid%20Visuals)s. Here's a complete application example in MXML: <s:application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark"> <fx:script> import mx.collections.IList; Bindable public var gridData:IList = new ArrayList([ {firstName: "Fred", lastName: "Flintsone", food: "hamburger", drink: "beer"}, // ... more similar objects ]); </fx:script> <s:datagrid id="user-content-dataGrid" dataprovider="{gridData}" width="100%" height="100%"> <s:columns> <s:arraylist> <s:gridcolumn datafield="firstName"> <s:gridcolumn datafield="lastName"> <s:gridcolumn datafield="food"> <s:gridcolumn datafield="drink"> </s:gridcolumn></s:gridcolumn></s:gridcolumn></s:gridcolumn></s:arraylist> </s:columns> </s:datagrid> </s:application> In this example the DataGrid's dataProvider is a list of objects, which of which contains firstName, lastName, food, and drink properties. The DataGrid includes one column for each property and the [GridColumn](Data%20Grid%20Visuals) dataField property is used to select the dataProvider item property to display in that column. This example takes advantage of the fact that the default itemRenderer displays the string value of data\[column.dataField\], where data is dataProvider.getItemAt(rowIndex), aka the "data item" for the specified grid row. ### Custom Item Renderers A [GridColumn](Data%20Grid%20Visuals)'s itemRenderer is an IVisualElement that implements [IGridItemRenderer](Data%20Grid%20Visuals). The [GridItemRenderer](Data%20Grid%20Visuals) base class is a Group that implements [IGridItemRenderer](Data%20Grid%20Visuals) and is convenient for creating custom item renderers. The code fragment below is a replacement for the first two [GridColumns](Data%20Grid%20Visuals) in the previous example. It defines a single [GridColumn](Data%20Grid%20Visuals) with a custom itemRenderer that displays both the firstName and lastName properties by binding to the [GridItemRenderer's](Data%20Grid%20Visuals)'s data property: <s:gridcolumn> <s:itemrenderer> <fx:component> <s:griditemrenderer> <s:label text="{data.firstName} {data.lastName}" left="10" right="5" paddingtop="10" paddingbottom="5"> </s:label></s:griditemrenderer> </fx:component> </s:itemrenderer> </s:gridcolumn> Note: for simplicity's sake we haven't made each property of the dataProvider's items bindable. Although the example will correctly display the initial value of each data item property, the binding system will issue a warning because it can not track subequent changes to these properties. A real application whose item renderer was bound to data item properties would have to ensure that those properties were defined with the Bindable metadata. In this case the [GridItemRenderer](Data%20Grid%20Visuals) just contains a single Label. In addition to including a bindable data property that corresponds to the dataProvider item for the current row, [GridItemRenderer](Data%20Grid%20Visuals) has bindable rowIndex and column properties that specify the current row index and [[GridColumn](Data%20Grid%20Visuals). Cell item renderers can bind to these properties as well, for example: <s:gridcolumn> <s:itemrenderer> <fx:component> <s:griditemrenderer> <s:label text="{rowIndex}" left="10" right="5" paddingtop="10" paddingbottom="5"> </s:label></s:griditemrenderer> </fx:component> </s:itemrenderer> </s:gridcolumn> This column just displays the current row number (rowIndex). Item renderers aren't required to use data binding to configure their visual elements. It can be more efficient and flexible to override the [GridItemRenderer](Data%20Grid%20Visuals) prepare() method, which is called after the item renderer has been configured and just before it's displayed. The example below is a generic checkbox item renderer that displays the boolean value selected by the column's dataField: <s:griditemrenderer xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark"> <fx:script> column.dataField as Boolean; } ]]> </fx:script> <s:checkbox id="user-content-valueDisplay"> </s:checkbox></s:griditemrenderer> The prepare() hasBeenRecycled parameter lets the method know if the renderer has just been created, or if it's being reused. In some cases developers might want to do one-time item renderer initializations when hasBeenRecycled=false. ### Additional DataGrid Visual Elements: Indicators, Separators, Row Backgrounds Not all of the visual elements of a DataGrid can be displayed with item renderers. Row and column separators and row backgrounds are visual elements that would be clumsy to render, if each item renderer was responsibe for contributing one cell's worth of the overall visual. Even visual aspects like the selection or hover indicators, which are the exclusive responsibility of item renderers in the Spark List, are rendered separately in the Spark DataGrid. This is because the shape of these indicators depends on the selection mode. If the DataGrid's selectionMode is "row" or "multipleRows", then the indicators span each affected row. In addition to the per-column item renderer, DataGrid defines six skin parts that are used to display repeating elements and indicators: **selectionIndicator** \- A visual element that's displayed for each selected row or cell (depends on the DataGrid selectionMode property). **caretIndicator** \- A single visual element that's displayed for the caret row or cell (depends on the DataGrid selectionMode property). **hoverIndicator** \- A single visual element that's displayed for the row or cell under the mouse (depends on the DataGrid selectionMode property). **rowSeparator** \- A visual element that's displayed in between each row. **columnSeparator** \- A visual element that's displayed in between each column. **rowBackground** \- A visual element that's displayed for each row. It's used to implement the alternatingRowColors style. All of these DataGrid IFactory skin parts are required to be IVisualElements. In many cases they're just GraphicElements like Rects or Lines, which can be renderered quite efficiently because the Flex runtime's "display object sharing" support uses a single DisplayObject to render all of them. Just like item renderers, these visual elements are internally pooled and recycled, to avoid the cost creating and adding them when the DataGrid is scrolled. A DataGrid skin, defined as a subclass of the default DataGridSkin, can replace one or more default visual element skin parts by including the new values in an fx:Declarations section. For example, to define a DataGrid skin derived from the default, with new values for the caretIndicator and selectionIndicator: <spark:datagridskin xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:spark="spark.skins.spark.*"> <fx:declarations> <fx:component id="user-content-caretIndicator"> <s:rect> <s:stroke> <s:solidcolorstroke color="0xFFBC7A" weight="2"> </s:solidcolorstroke></s:stroke> </s:rect> </fx:component> <fx:component id="user-content-selectionIndicator"> <s:rect> <s:fill> <s:solidcolor color="0xC082FF"> </s:solidcolor></s:fill> </s:rect> </fx:component> </fx:declarations> </spark:datagridskin> ### Further Reading This survey of DataGrid features is by no means comprehensive, more details about the corrresponding APIs follow. Note that in most cases capabilities that were present in the MX DataGrid, save the ones explicitly listed in the "Summary and Background" section, are also available in the Spark Datagrid, usually with the same API. ## API The skinnable DataGrid component is really a special purpose container for its Grid and a [GridColumnHeaderGroup](Data%20Grid%20Visuals) skin parts. It's the Grid component that actually displays the rows and columns and manages the selection, caret and so on. The DataGrid's skin is responsible for arranging these elements and a Scroller. Structually the DataGrid is similar to the Spark List component, which also delegates responsibility for displaying its items to a separate, non-skinnable, component, the [DataGroup](Spark%20DataGroup). Most of the [DataGroup](Spark%20DataGroup)'s properties and methods are just "covers" for its grid skin part. The DataGrid adds its own mouse and keyboard event handling to support Grid selection, cell editing, and scrolling. Similarly, DataGrid event handlers added to the [GridColumnHeaderGroup](Data%20Grid%20Visuals) enable interactive column operations, like resizing. The DataGrid displays its dataProvider, an IList whose Object elements are referred to as "data items" or just "items". Each row in the DataGrid displays different aspects of a data item, one aspect per column. Rows and columns define grid "cells" and a cell's location is typically defined by a pair of "rowIndex", "columnIndex" integers. The DataGrid's columns define the aspect of the data item to be displayed and the "item renderer" used to display it. The DataGrid's columns are also defined by an IList and each column must be an instance of [GridColumn](Data%20Grid%20Visuals)]. Typically the [GridColumn](Data%20Grid%20Visuals)'s "dataField" property is used to define the data item property to be displayed (as a string) in that column. All of the cells in a column are displayed with the same item renderer, a factory that produces instances of [IGridItemRenderer](Data%20Grid%20Visuals). The figure below illustrates how DataGrid has been factored into classes and parts:  The "indicator" suffix is used to identify visual elements that reflect the state of the row or cell. Not shown is the "rowSeparator", which is displayed in between rows. To make reviewing the complete specifications for all of the classes a little more manageable, they have been broken down into several categories. The material for each category appears in a separate document. Note that the Grid and DataGrid classes have a great deal of API in common, because DataGrid "covers" many of the methods and properties defined by its grid skin part. * [Visuals](Data%20Grid%20Visuals) The visual elements for Grid and DataGrid. This document covers the Grid, DataGrid, [GridColumn](Data%20Grid%20Visuals), [GridItemRenderer](Data%20Grid%20Visuals), [IGridItemRenderer](Data%20Grid%20Visuals) classes and interfaces. * [Column Headers](Data%20Grid%20Column%20Headers) The default value of the DataGrid's columnHeaderGroup skin part is a GridColumnHeaderGroup. * [Layout](Data%20Grid%20Layout) How the DataGrid computes row heights, column widths, and its measured size. * [Mouse Events](Data%20Grid%20Mouse%20Events) The Grid class dispatches some grid-specific events in response to mouse events, to simplify event handling for features like selection. This document covers the Grid and [GridEvent](Data%20Grid%20Mouse%20Events) classes. * [Selection](Data%20Grid%20Selection) The Grid class provides a rich selection model and the DataGrid adds mouse and keyboard handlers that use it. This document covers the Grid and DataGrid, [GridSelectionMode](Data%20Grid%20Selection), [GridCaretEvent](Data%20Grid%20Selection), [GridSelectionEvent](Data%20Grid%20Selection) classes. * [Geometry](Data%20Grid%20Geometry) Grid and DataGrid provide an API that exposes the visible and overall geometry of the grid. This document covers the DataGrid and Grid classes. * [DataGrid Skin](Data%20Grid%20Skin) The DataGrid's skin is responsible for laying it the grid, columnHeaderGroup, and scroller skin parts. This document covers the DataGrid and DataGridSkin classes. * [DataGrid Editing](Data%20Grid%20Editing) This document covers the support for cell editing and for keyboard focus management within the DataGrid. ## B Features _Detail features here that are to be considered for B Feature time._ ## Examples and Usage _Include examples of how this feature would be used in practice, from MXML and_ _ActionScript_ _code, or from the command line, or from other mechanisms as appropriate_ ## Additional Implementation Details _Enter implementation/design details for the feature here. This section may be updated after the spec signs off._ ## Compiler Work _Will this feature require any compiler changes? If so, describe here, if not already included in the Detailed Description._ * _any new compiler switches (flex-config.xml configuration)_ * _proposed workflow changes_ * _changes to the Compiler API - example, a logger or localization manager now required_ ## Backwards Compatibility ### Syntax changes _List any syntax changes (MXML tags, attributes, AS syntax changes) that may affect backward compatibility with existing applications._ _Does any part of this feature support the \-compatibility-version compiler argument?_ ### Behavior _List any changes to existing MXML tags, attributes, etc._ ### Warnings/Deprecation _Clearly identify anything that existing features that will become deprecated. Identify any warnings that will be issued (if any) as a result. Identify recommended documentation changes that should accompany._ ## Accessibility _Describe any accessibility considerations._ ## Performance Performance goals below are based on a 952-cell Spark DataGrid of 28 columns by 34 rows, using the default item renderer. The Windows XP benchmark machine referenced below is an Intel Core2 CPU 6400 @ 2.13GHz with 2GB of RAM. The performance goals will be as follows: * Vertical page scrolling will occur at no worse a pps rate than the 4.0 MX DataGrid achieved on shipped FP 10.1, on both Windows and Mac. * E.g., on our WinXP benchmark machine, 8.52 pps. * Horizontal page scrolling will occur at no worse a pps rate than the 4.0 MX DataGrid achieved on shipped FP 10.1, on both Windows and Mac. * E.g., on our WinXP benchmark machine, 2.51 pps. * Creation (startup) time will be no worse than for the 4.0 MX DataGrid on shipped FP 10.1, on both Windows and Mac. * E.g., on our WinXP benchmark machine, 984 ms. * No more memory will be used than by the 4.0 MX DataGrid on shipped FP 10.1. * E.g., on our WinXP benchmark machine, 18.83 MB. ## Globalization _All components that deal with text will need to be globalization-aware. This means that text in any supported language can be used with the component._ _The component must use the Unicode character set (mostly comes for free from Flash Player) and must interoperate with IME's (Input Method Editors) for foreign languages (also mostly supported via Flash Player)._ _Globalization also includes issues with date/time formatting and currency formatting for specific locales._ _European (French, German, etc.) and Asian (Japanese, Korean, Chinese) languages are of particular concern._ _Note any specific globalization issues here._ ## Localization ### Compiler Features _Command-line help descriptions should be added to sdk/modules/compiler/src/java/flex2/configuration_en.properties and configuration_ja.properties._ _Error/warning messages that are related to the compiler core (flex2.compiler.\* packages) should be added to sdk/modules/compiler/src/java/flex2/compiler_en.properties and compiler_ja.properties._ _Error/warning messages that are related to the linker (flex2.linker.\* packages) should be added to sdk/modules/compiler/src/java/flex2/linker_en.properties and linker_ja.properties._ _CompilerMessage_ _subclasses should be created to support the messages in the .properties files._ _The \_ja.properties files are unicode-escaped files._ ### Framework Features _List the RTE message strings that will require localization. (They must all come from .properties files.)_ _List all UI text that will require localization, such as the month and day names in a_ _DateChooser__. (All such text must all come from .properties files.)_ _List all UI images, skins, sounds, etc. that will require localization._ _Discuss any locale-specific formatting requirements for numbers, dates, currency, etc._ _Discuss any locale-specific sorting requirements._ ## Cross-Platform Considerations _Does this feature apply differently to Windows versus Mac platforms, or require different testing depending on platform?_ ## Issues and Recommendations _Enumerate open issues needing resolution, along with recommended solutions, if any._ \\