You use the <s:DataGrid> tag to
define a Spark DataGrid control
in MXML. Specify an id value if you intend to refer
to a component elsewhere in your MXML, either in another tag or
in an ActionScript block.
The DataGrid control uses a list-based data provider to supply
the data to display. The data provider consists of a list of objects
called items. Each item corresponds to one row of the DataGrid
control. Each grid column typically corresponds to one property
of each row item. For more information, see Data providers and collections.
You can specify data in several different ways. In the simplest
case, use the <s:ArrayList> and <fx:Object> tags
to define the entries. Each Object defines a row of the DataGrid
control. The properties of each Object define the column entries
for the row, as the following example shows:
The executing SWF file for the previous example is shown below:
Note: You do not have to specify the dataProvider tag
in MXML because dataProvider is the default property
of the DataGrid control.
By default, each column displays one property from each data
provider item. Each column heading displays the name of the associated
property in the data provider item.
The index of rows in the DataGrid control is zero-based, meaning
values are 0, 1, 2, ... , n ‑ 1, where n is the total
number of items in the data provider. Column indexes are also zero-based.
Therefore, if you select the first cell in the second row, the row
index is 1 and the column index is 0.
Passing data to a DataGrid control
Specify the data provider for the DataGrid control
by using the dataProvider property. The data type
of the dataProvider property is IList. That
lets you use an ArrayList, ArrayCollection,
or any other class that implements IList as the data provider.
ArrayList is a lightweight implementation of IList that is useful
if you do not support row sorting in the DataGrid control. To support
row sorting, use a class that implements the ICollectionView interface,
such as ListCollectionView. Typically, you use a subclass of ListCollectionView,
such as ArrayCollection or XMLListCollection,
as the data provider to support row sorting.
Each row in the data grid corresponds to one item in the data
provider. Data provider items can define their properties in differing
orders. By default, the order of the columns corresponds to the
order of the properties as defined in the first item in the data
provider.
If a data provider item omits a property or a value for a property,
the DataGrid control displays an empty cell in the corresponding
column for that row.
Flex lets you populate a DataGrid control
from an ActionScript variable definition or from a Flex data model.
The following example populates a DataGrid control by using a variable:
<?xml version="1.0" encoding="utf-8"?>
<!-- dpcontrols\sparkdpcontrols\SparkDGPassedData.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
initialize="initData();">
<fx:Script>
<![CDATA[
import mx.collections.*;
private var dgArray:Array = [
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavement', Album:'Brighten the Corners', Price:11.99}];
[Bindable]
public var initDG:ArrayCollection;
// Initialize initDG variable from the Array.
public function initData():void {
initDG = new ArrayCollection(dgArray);
}
]]>
</fx:Script>
<s:DataGrid id="myGrid"
width="350" height="200"
dataProvider="{initDG}"/>
</s:Application>
The executing SWF file for the previous example is shown below:
In this example, you bind the variable initDG to
the <s:dataProvider> property.
The following example populates the DataGrid control from XML
data. In this example, you define the XML data by using the XMLList
class. You then create an XMLListCollection object from the XMLList:
The executing SWF file for the previous example is shown below:
You can use Flex data access components: HTTPService, WebService,
and RemoteObject,
to supply data to the DataGrid. To use a remote data source to provide
data, you represent the result of the remote service with the appropriate object,
as follows:
A RemoteObject component automatically returns an ArrayCollection for
any data that is represented on the server as a java.util.List object,
and you can use the returned object directly.
For HTTPService and WebService results, cast the result data
to a collection class if the data changes or if you use the same
result in multiple places (the latter case is more efficient). As
a rule, use an ArrayCollection for serialized (list-based) objects
and an XMLListCollection for
XML data.
The following code snippet shows this use, casting a list returned
by a web service to an ArrayCollection:
A GridColumn object
represents each column in a DataGrid control. By default, the DataGrid control
creates a column for every property in the first item of the data
provider.
Use the DataGrid.columns property to explicitly
define the columns of the DataGrid. By explicitly defining the columns,
you can set the column order, set column visibility, and set additional
column properties.
The data type of the columns property is IList.
That lets you use an ArrayList, ArrayCollection, or any other class
that implements IList as the data provider. Most of the applications
in this document use ArrayList to set the columns property.
To support column sorting, use a class that implements the ICollectionView interface,
such as ListCollectionView. Typically, you use a subclass of ListCollectionView,
such as ArrayCollection, as the data provider.
Note: You can only sort the columns of the DataGrid programmatically
by sorting the IList passed to the columns property.
That is, you cannot use the mouse to drag a column to rearrange
the columns.
Use the GridColumn.dataField property to specify
the property of the data provider items displayed in a column, as
the following example shows:
The executing SWF file for the previous example is shown below:
When you use the <s:columns> tag, the
DataGrid only displays the columns corresponding to the specified
GridColumn objects. In this example, you only define columns for
the Album and Price properties of the data provider. Therefore,
the DataGrid does not display a column for the Price property.
You can reorder the columns by changing the order of the GridColumn
objects, as the following example shows:
In this example, you specify that the Price column is the first
column in the DataGrid control, and that the Album column is the
second.
You can also use the <s:GridColumn> tag
to set other options. The following example uses the headerText property
to set the name of the column to a value different from the default
name of Album, and uses the width property to set
an explicit column width:
Rather than explicitly set the width of a column, you can define
a typical item for the DataGrid control. The DataGrid uses the typical
item, and any item renderer associated with a column, to compute
the initial width of each column that does not specify an explicit
width. Use the typicalItem property to specify
the data item, as the following example shows:
The executing SWF file for the previous example is shown below:
Sorting the columns of the Spark DataGrid control
By default, the DataGrid control
displays rows in the order specified in the data items passed to
its dataProvider property. The control lets you
sort data based on the cell value of a single column. To sort ascending
order of a column, select the column header. Select it again to
sort in descending order.
To disable sorting for the control, set the DataGrid.sortableColumns property
to false. To disable sorting for an individual
column, set the GridColumn.sortable property to false.
Create a custom sort by implementing a sort compare function.
You can define a different sort compare function for each column
of the control. For more information, see Create a custom sort for the Spark DataGrid control.
Hiding and displaying columns
If you display a column at some times, but not at others,
you can specify the GridColumn class visible property
to hide or show the column. The following example lets you hide
or show the album price by clicking a button:
