Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_advdatagrid_ad.html
blob: 729b475415ec337fc53c38c74c6ac6905ab2ac3b [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="AdvancedDataGrid control"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7be0_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>AdvancedDataGrid control</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7be0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be0_verapache"><!-- --></a>
<h1 class="topictitle1">AdvancedDataGrid control</h1>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
expands on the functionality of the standard MX DataGrid control
to add data visualization capabilities to your applications built in
Flex. These capabilities provide greater
control of data display, data aggregation, and data formatting.</p>
<p>For more information on the DataGrid control, see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d9a_verapache">MX
DataGrid control</a>.</p>
<p>There is also a Spark DataGrid control. For more information,
see <a href="flx_spark_datagrid_sdg.html#WSd867f5c5d869105e43810e1112c55502365-8000_verapache">Spark
DataGrid and Grid controls</a>.</p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf0_verapache"><!-- --></a>
<h2 class="topictitle2">About the AdvancedDataGrid control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
extends the capabilities of the standard DataGrid control to improve
data visualization. The following table describes the main data
visualization capabilities of the AdvancedDataGrid control:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e65">
<p>Capability</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e71">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e65 ">
<p>Sorting by multiple columns</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e71 ">
<p>Sort by multiple columns when you click
in the column header. For more information, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache">Sorting
by multiple columns </a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e65 ">
<p>Styling rows and columns</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e71 ">
<p>Use the <samp class="codeph">styleFunction</samp> property
to specify a function to apply styles to rows and columns of the control.
For more information, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf5_verapache">Styling
rows and columns</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e65 ">
<p>Displaying hierarchical and grouped data</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e71 ">
<p>Use an expandable navigation tree in a column
to control the visible rows of the control. For more information,
see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache">Hierarchical
and grouped data display</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e65 ">
<p>Creating column groups</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e71 ">
<p>Collect multiple columns under a single
column heading. For more information, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf3_verapache">Creating
column groups</a>.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e65 ">
<p>Using item renderers</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e71 ">
<p>Span multiple columns with an item renderer
and use multiple item renderers in the same column. For more information,
see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf2_verapache">Using
item renderers with the AdvancedDataGrid control</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Displaying hierarchical and grouped
data</h3>
<div>
<p>One of the most important aspects of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
is its support for the display of hierarchical and grouped data. <em>Hierarchical data</em> is
data already in a structure of parent and child data items. <em>Grouped data</em> is
flat data with no inherent hierarchy. Before passing flat data to
the AdvancedDataGrid control, you specify one or more data fields
that are used to group the flat data into a hierarchy.</p>
<p>To support the display of hierarchical and grouped data, the
AdvancedDataGrid control displays a navigation tree in a column
that lets you navigate the data hierarchy. The following example
shows an AdvancedDataGrid control with a navigation tree in the
first column that controls the visible rows of the control, but
it can be in any column:</p>
<div class="figborder">
<img src="images/ac_simpleGroup.png" alt="AdvancedDataGrid control with a navigation tree in the first column"/>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">Migrating from the DataGrid control</h3>
<div>
<p>Besides the major new features added to the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control described
in the section <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf0_verapache">About
the AdvancedDataGrid control</a>, the AdvancedDataGrid control
adds the following property: </p>
<dl>
<dt class="dlterm">firstVisibleItem</dt>
<dd>
<p>Specifies the item that is currently displayed in the top
row of the AdvancedDataGrid control.</p>
<p>One consideration when
migrating an existing application from the DataGrid control to the
AdvancedDataGrid control is that the data type of many event objects
dispatched by the AdvancedDataGrid control is of type AdvancedDataGridEvent,
not of type DataGridEvent as it is for the DataGrid control. If
your application references the event object by type, you must update
your application so that it uses the correct data type. </p>
<p>To
determine the type of the event object for any event, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe<sup>®</sup>
Flash<sup>®</sup> Platform</a>
</em>.</p>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Example: Creating column groups</h3>
<div>
<p>Column grouping lets you collect multiple columns under
a single column heading. The following example shows the Actual
and Estimate columns grouped under the Revenues column:</p>
<div class="figborder">
<img src="images/ac_simpleColumnGroup.png" alt="The Actual and Estimate columns grouped under the Revenues column"/>
</div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
is defined by the mx.controls.AdvancedDataGrid class and additional
classes in the package mx.controls.advancedDataGridClasses. This
package includes the AdvancedDataGridColumn class that you use to
define a column. </p>
<p>The following code creates the column grouping shown in the previous
image:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/ColumnGroupADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
// Import the data used by the AdvancedDataGrid control.
include "SimpleFlatData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
dataProvider="{dpFlat}"
width="100%" height="100%"&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>This example imports the data used by the AdvancedDataGrid control
from a file named SimpleFlatData.as. You can see the contents of
that file in the topic <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache">Hierarchical
and grouped data display</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache"><!-- --></a>
<h2 class="topictitle2">Sorting by multiple columns </h2>
<div>
<p>By default, the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
displays data in the order specified in the data passed to its <samp class="codeph">dataProvider</samp> property.
The AdvancedDataGrid control also lets you sort data after the control
displays it in a single column or multiple columns.</p>
<p>To disable sorting for an entire AdvancedDataGrid control, set
the <samp class="codeph">AdvancedDataGrid.sortableColumns</samp> property to <samp class="codeph">false</samp>.
To disable sorting for an individual column, set the <samp class="codeph">AdvancedDataGridColumn.sortable</samp> property
to <samp class="codeph">false</samp>.</p>
<p>The way that you sort multiple columns is based on the setting
of the <samp class="codeph">sortExpertMode</samp> property. By default, the <samp class="codeph">sortExpertMode</samp> property
is set to <samp class="codeph">false</samp>. This setting means that you click
in the header area of a column to sort the rows of the AdvancedDataGrid
control by that column. Then you click in the multiple column sort
area of the header to sort by additional columns. To use the Control
key to select every column after the first column to perform sort,
set the <samp class="codeph">sortExpertMode</samp> property to <samp class="codeph">true</samp>. </p>
<p>The following example shows an AdvancedDataGrid control with
three columns with the <samp class="codeph">sortExpertMode</samp> property
set to <samp class="codeph">false</samp>: </p>
<div class="figborder">
<img src="images/ac_multicolumn_sort.png" alt="AdvancedDataGrid control with three columns with the sortExpertMode property set to false"/>
<dl>
<dt class="dlterm">
<strong>A.</strong>
</dt>
<dd>Column header area</dd>
<dt class="dlterm">
<strong>B</strong>
</dt>
<dd>. Multiple column sort area</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ffa_verapache"><!-- --></a><h3 class="sectiontitle">Sort
the columns with sortExpertMode set to false</h3>
<ol>
<li>
<p>Click
in the column header area of any column in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
to sort by that column. For example, click in the column header
for the Artist column to sort that column in ascending order. Click
the Artist column header again to sort in descending order.</p>
</li>
<li>
<p>Click in the multiple column sort area of any other column
header. For example, click in the multiple column sort area of the
Price column to arrange it in ascending order while keeping the
Artist column sorted in descending order. You can now find the least
expensive album for each artist. </p>
</li>
<li>
<p>Click in the multiple column sort area for the Price column
again to arrange it in descending order.</p>
</li>
<li>
<p>Click in the multiple column sort area for any other column
header to include other columns in the sort. </p>
</li>
</ol>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf6_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff9_verapache"><!-- --></a><h3 class="sectiontitle">Sort
the columns with sortExpertMode set to true</h3>
<ol>
<li>
<p>Click
in the column header area of any column in the AdvancedDataGrid control
to sort by that column. For example, click in the column header
for the Artist column to sort that column in ascending order. Click
the Artist column header again to sort in descending order.</p>
</li>
<li>
<p>While holding down the Control key, click in any other column
header. For example, click the column header for the Price column
to arrange it in ascending order while keeping the Artist column
sorted in descending order. You can now find the least expensive
album for each artist. </p>
</li>
<li>
<p>While holding down the Control key, click the column header
for the Price column again to arrange it in descending order.</p>
</li>
<li>
<p>While holding down the Control key, select any other column
header to include other columns in the sort. </p>
</li>
</ol>
<p>The
following code implements multiple column sort when the <samp class="codeph">sortExpertMode</samp> property
is set to <samp class="codeph">true</samp>:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var dpADG:ArrayCollection = new ArrayCollection([
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavement', Album:'Brighten the Corners', Price:11.99},
{Artist:'Saner', Album:'A Child Once', Price:11.99},
{Artist:'Saner', Album:'Helium Wings', Price:12.99},
{Artist:'The Doors', Album:'The Doors', Price:10.99},
{Artist:'The Doors', Album:'Morrison Hotel', Price:12.99},
{Artist:'Grateful Dead', Album:'American Beauty', Price:11.99},
{Artist:'Grateful Dead', Album:'In the Dark', Price:11.99},
{Artist:'Grateful Dead', Album:'Shakedown Street', Price:11.99},
{Artist:'The Doors', Album:'Strange Days', Price:12.99},
{Artist:'The Doors', Album:'The Best of the Doors', Price:10.99}
]);
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid
width="100%" height="100%"
sortExpertMode="true"
dataProvider="{dpADG}"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Artist" /&gt;
&lt;mx:AdvancedDataGridColumn dataField="Album" /&gt;
&lt;mx:AdvancedDataGridColumn dataField="Price" /&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf5_verapache"><!-- --></a>
<h2 class="topictitle2">Styling rows and columns</h2>
<div>
<p>You apply styles to the rows and columns of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
by using callback functions. To control the styling of a row, use
the <samp class="codeph">AdvancedDataGrid.styleFunction</samp> property to
specify the callback function; to control the styling of a column,
use the <samp class="codeph">AdvancedDataGridColumn.styleFunction</samp> property
to specify the callback function. </p>
<p>The callback function specified by the <samp class="codeph">AdvancedDataGrid.styleFunction</samp> property
is invoked first, followed by the function specified by the <samp class="codeph">AdvancedDataGridColumn.styleFunction</samp> property.
Therefore, the </p>
<p>AdvancedDataGrid control applies styles to rows first, and then
to columns.</p>
<p>The callback function must have the following signature: </p>
<pre class="codeblock"> <em>function_name</em>(<em>data</em>:Object, <em>column</em>:AdvancedDataGridColumn):Object</pre>
<p>The function returns an Object that contains one or more <em>styleName:value</em> pairs to
specify a style setting, or null. The <em>styleName</em> field contains
the name of a style property, such as <samp class="codeph">color</samp>, and
the <em>value</em> field contains the value for the style property,
such as 0x00FF00. For example, you could return two styles using
the following code:</p>
<pre class="codeblock"> {color:0xFF0000, fontWeight:"bold"}</pre>
<p>The AdvancedDataGrid control invokes the callback function when
it updates its display, such as when the control is first drawn
on application start up, or when you call the <samp class="codeph">invalidateList()</samp>method.</p>
<p>The examples in this section use callback functions to set the
style of an AdvancedDataGrid control. All of the examples in this
section use the following data from the StyleData.as file:</p>
<pre class="codeblock">[Bindable]
private var dpADG:ArrayCollection = new ArrayCollection([
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavement', Album:'Brighten the Corners', Price:11.99},
{Artist:'Saner', Album:'A Child Once', Price:11.99},
{Artist:'Saner', Album:'Helium Wings', Price:12.99},
{Artist:'The Doors', Album:'The Doors', Price:10.99},
{Artist:'The Doors', Album:'Morrison Hotel', Price:12.99},
{Artist:'Grateful Dead', Album:'American Beauty', Price:11.99},
{Artist:'Grateful Dead', Album:'In the Dark', Price:11.99},
{Artist:'Grateful Dead', Album:'Shakedown Street', Price:11.99},
{Artist:'The Doors', Album:'Strange Days', Price:12.99},
{Artist:'The Doors', Album:'The Best of the Doors', Price:10.99}
]); </pre>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bee_verapache"><!-- --></a>
<h3 class="topictitle3">Styling rows</h3>
<div>
<p>The following example uses the <samp class="codeph">AdvancedDataGrid.styleFunction</samp> property
to specify a callback function to apply styles to the rows of an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
In this example, you use Button controls to select an artist in
the AdvancedDataGrid control. Then the callback function highlights
in red all rows for the selected artist.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleADGRowStyleFunc.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
import mx.controls.advancedDataGridClasses.AdvancedDataGridColumn;
// Include the data for the AdvancedDataGrid control.
include "StyleData.as"
// Artist name to highlight.
protected var artistName:String;
// Event handler to set the selected artist's name
// based on the selected Button control.
public function setArtistName(event:Event):void {
artistName=Button(event.currentTarget).label;
// Refresh row display.
myADG.invalidateList();
}
// Callback function that highlights in red
// all rows for the selected artist.
public function myStyleFunc(data:Object,
col:AdvancedDataGridColumn):Object {
if (data["Artist"] == artistName)
return {color:0xFF0000};
// Return null if the Artist name does not match.
return null;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
dataProvider="{dpADG}"
styleFunction="myStyleFunc"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Artist"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Album"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Price"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="Pavement" click="setArtistName(event);"/&gt;
&lt;mx:Button label="Saner" click="setArtistName(event);"/&gt;
&lt;mx:Button label="The Doors" click="setArtistName(event);"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff6_verapache"><!-- --></a>
<h3 class="topictitle3">Styling columns </h3>
<div>
<p>The following example modifies the example in the previous
section to use a callback function to apply styles to the rows and
one column of an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
In this example, the Price column displays all cells with a price
less than $11.00 in green:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleADGColumnStyleFunc.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
import mx.controls.advancedDataGridClasses.AdvancedDataGridColumn;
// Include the data for the AdvancedDataGrid control.
include "StyleData.as"
// Artist name to highlight.
protected var artistName:String;
// Event handler to set the selected artist's name
// based on the selected Button control.
public function setArtistName(event:Event):void
{
artistName=Button(event.currentTarget).label;
// Refresh row display.
myADG.invalidateList();
}
// Callback function that highlights in red
// all rows for the selected artist.
public function myStyleFunc(data:Object,
col:AdvancedDataGridColumn):Object
{
if (data["Artist"] == artistName)
return {color:0xFF0000};
// Return null if the Artist name does not match.
return null;
}
// Callback function that hightlights in green
// all entries in the Price column
// with a value less than $11.00.
public function myColStyleFunc(data:Object,
col:AdvancedDataGridColumn):Object
{
if(data["Price"] &lt;= 11.00)
return {color:0x00FF00};
return null;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
dataProvider="{dpADG}"
styleFunction="myStyleFunc"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Artist"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Album"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Price"
styleFunction="myColStyleFunc"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="Pavement" click="setArtistName(event);"/&gt;
&lt;mx:Button label="Saner" click="setArtistName(event);"/&gt;
&lt;mx:Button label="The Doors" click="setArtistName(event);"/&gt;
&lt;/mx:HBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff5_verapache"><!-- --></a>
<h3 class="topictitle3">Using a data formatter in a column</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/advancedDataGridClasses/AdvancedDataGridColumn.html" target="_blank">AdvancedDataGridColumn</a> class
contains a <samp class="codeph">formatter</samp> property that lets you pass
a class that implements the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/formatters/IFormatter.html" target="_blank">IFormatter</a> interface
to the column. This includes the Spark formatters such as <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/formatters/CurrencyFormatter.html" target="_blank">CurrencyFormatter</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/formatters/DateTimeFormatter.html" target="_blank">DateTimeFormatter</a>, and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/formatters/NumberFormatter.html" target="_blank">NumberFormatter</a>,
as well as subclasses of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/formatters/Formatter.html" target="_blank">Formatter</a> class,
including the MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/formatters/CurrencyFormatter.html" target="_blank">CurrencyFormatter</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/formatters/DateFormatter.html" target="_blank">DateFormatter</a>,
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/formatters/NumberFormatter.html" target="_blank">NumberFormatter</a>. </p>
<p>The formatter classes convert data into customized strings. For
example, you can use the Spark or MX CurrencyFormatter class to
prefix the value in the Price column with a dollar ($) sign. </p>
<p>You use a formatter class with a callback function specified
by the <samp class="codeph">labelFunction</samp> property or the <samp class="codeph">styleFunction</samp> property.
If you specify a callback function, Flex invokes that formatter
class after invoking the callback functions. </p>
<p>The following example modifies the example from the section <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bee_verapache">Styling
rows</a> to add a CurrencyFormatter class to the Price column
to prefix the price with the $ sign:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleADGRowFormatter.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
import mx.controls.advancedDataGridClasses.AdvancedDataGridColumn;
// Include the data for the AdvancedDataGrid control.
include "StyleData.as"
// Artist name to highlight.
protected var artistName:String;
// Event handler to set the selected artist's name
// based on the selected Button control.
public function setArtistName(event:Event):void
{
artistName=Button(event.currentTarget).label;
// Refresh row display.
myADG.invalidateList();
}
// Callback function that hightlights in red
// all rows for the selected artist.
public function myStyleFunc(data:Object,
col:AdvancedDataGridColumn):Object
{
if (data["Artist"] == artistName)
return {color:0xFF0000};
// Return null if the Artist name does not match.
return null;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
dataProvider="{dpADG}"
styleFunction="myStyleFunc"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Artist"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Album"/&gt;
&lt;mx:AdvancedDataGridColumn width="75" dataField="Price"&gt;
&lt;mx:formatter&gt;
&lt;s:CurrencyFormatter useCurrencySymbol="true"/&gt;
&lt;/mx:formatter&gt;
&lt;/mx:AdvancedDataGridColumn&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Pavement" click="setArtistName(event);"/&gt;
&lt;s:Button label="Saner" click="setArtistName(event);"/&gt;
&lt;s:Button label="The Doors" click="setArtistName(event);"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache"><!-- --></a>
<h2 class="topictitle2">Selecting multiple cells and rows</h2>
<div>
<p>All list-based controls support the <samp class="codeph">allowMultipleSelection</samp> property. Setting
the <samp class="codeph">allowMultipleSelection</samp> property to <samp class="codeph">true</samp> lets
you select more than one item in the control at the same time. For
example, the DataGrid control lets you select multiple rows so that
you can drag and drop them to another DataGrid control.</p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
adds the capability of letting you select multiple cells. You can
drag the selected cells to another AdvancedDataGrid control, copy them
to the clipboard, or perform some other action on the cell data. </p>
<p>You use the <samp class="codeph">selectionMode</samp> property of the AdvancedDataGrid
control, with the <samp class="codeph">allowMultipleSelection</samp> property
to configure multiple selection. The default value of the <samp class="codeph">selectionMode</samp> property
is <samp class="codeph">singleRow</samp>, which means that you can select only
a single row at a time. You can also set the <samp class="codeph">selectionMode</samp> property
to <samp class="codeph">singleCell</samp>, <samp class="codeph">multipleRows</samp> or
to <samp class="codeph">multipleCells</samp>. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff3_verapache"><!-- --></a><h3 class="sectiontitle">Select
contiguous items in the control</h3>
<ol>
<li>
<p>Click the first
item, either a row or cell, to select it.</p>
</li>
<li>
<p>Hold down the Shift key as you select an additional item.</p>
<ul>
<li>
<p>If the <samp class="codeph">selectionMode</samp> property is set to <samp class="codeph">multipleRows</samp>,
click any cell in another row to select multiple, contiguous rows.</p>
</li>
<li>
<p>If the <samp class="codeph">selectionMode</samp> property is set to <samp class="codeph">multipleCells</samp>,
click any cell to select multiple, contiguous cells.</p>
</li>
</ul>
</li>
</ol>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff4_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff2_verapache"><!-- --></a><h3 class="sectiontitle">Select
discontiguous items in the control</h3>
<ol>
<li>
<p>Click the first
item, either a row or cell, to select it.</p>
</li>
<li>
<p>Hold down the Control key as you select an additional item.</p>
<ul>
<li>
<p>If the <samp class="codeph">selectionMode</samp> property is set to <samp class="codeph">multipleRows</samp>,
click any cell in another row to select that single row.</p>
</li>
<li>
<p>If the <samp class="codeph">selectionMode</samp> property is set to <samp class="codeph">multipleCells</samp>,
click any cell to select that single cell.</p>
</li>
</ul>
</li>
</ol>
<p>As
you select cells or rows in the AdvancedDataGrid control, the control
updates the <samp class="codeph">selectedCells</samp> property with information
about your selection. The <samp class="codeph">selectedCells</samp> property
is an Array of Objects where each Object contains a <samp class="codeph">rowIndex</samp> and <samp class="codeph">columnIndex</samp> property
that represents the location of the selected row or cell in the
control. </p>
<p>The value of the <samp class="codeph">selectionMode</samp> property
determines the data in the <samp class="codeph">rowIndex</samp> and <samp class="codeph">columnIndex</samp> properties,
as the following tables describes:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e907">
<p>Value of selectionMode property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e913">
<p>Value of rowIndex and columnIndex properties</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e907 ">
<div class="p">
<pre class="codeblock">none</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e913 ">
<p>No selection allowed in the control, and <samp class="codeph">selectedCells</samp> is
null. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e907 ">
<div class="p">
<pre class="codeblock">singleRow</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e913 ">
<p>Click any cell in the row to select the
row.</p>
<p>After the selection, <samp class="codeph">selectedCells</samp> contains
a single Object: </p>
<div class="p">
<pre class="codeblock">[{rowIndex:<em>selectedRowIndex</em>, columnIndex: -1}]</pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e907 ">
<div class="p">
<pre class="codeblock">multipleRows</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e913 ">
<p>Click any cell in the row to select the
row.</p>
<div class="p">
<ul>
<li>
<p>While holding down the Control key, click
any cell in another row to select the row for discontiguous selection.</p>
</li>
<li>
<p>While holding down the Shift key, click any cell in another
row to select multiple, contiguous rows.</p>
</li>
</ul>
</div>
<p>After
the selection, <samp class="codeph">selectedCells</samp> contains one Object
for each selected row: </p>
<div class="p">
<pre class="codeblock">[{rowIndex: <em>selectedRowIndex1</em>, columnIndex: -1},
{rowIndex: <em>selectedRowIndex2</em>, columnIndex: -1}, ...
{rowIndex: <em>selectedRowIndexN</em>, columnIndex: -1} ] </pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e907 ">
<div class="p">
<pre class="codeblock">singleCell</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e913 ">
<p>Click any cell to select the cell.</p>
<p>After
the selection, <samp class="codeph">selectedCells</samp> contains a single
Object: </p>
<div class="p">
<pre class="codeblock">[{rowIndex: <em>selectedRowIndex</em>, columnIndex:<em>selectedColIndex</em>}] </pre>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e907 ">
<div class="p">
<pre class="codeblock">multipleCells</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e913 ">
<p>Click any cell to select the cell.</p>
<div class="p">
<ul>
<li>
<p>While holding down the Control key, click any cell to select
the cell multiple discontiguous selection.</p>
</li>
<li>
<p>While holding down the Shift key, click any cell to select
multiple, contiguous cells.</p>
</li>
</ul>
</div>
<p>After the selection, <samp class="codeph">selectedCells</samp> contains
one Object for each selected cell: </p>
<div class="p">
<pre class="codeblock">[{rowIndex: <em>selectedRowIndex1</em>, columnIndex: <em>selectedColIndex1</em>},
{rowIndex: <em>selectedRowIndex2</em>, columnIndex: <em>selectedColIndex2</em>},
...
{rowIndex: <em>selectedRowIndexN</em>, columnIndex: <em>selectedColIndexN</em>} ] </pre>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example sets the <samp class="codeph">selectionMode</samp> property
to <samp class="codeph">multipleCells</samp> to let you select multiple cells
in the control. This application uses an event handler for the <samp class="codeph">keyUp</samp> event
to recognize the Control+C key combination and, if detected, copies
the selected cells from the AdvancedDataGrid control to your system’s
clipboard. </p>
<p>After you copy the cells, you can paste the cells
in another location in the Flex application, or paste them in another
application, such as Microsoft Excel. In this example, you paste
them to the TextArea control located at the bottom of the application:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/CellSelectADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
import flash.events.KeyboardEvent;
import flash.system.System;
include "StyleData.as"
// Event handler to recognize when Ctrl-C is pressed,
// and copy the selected cells to the system clipboard.
private function myKeyUpHandler(event:KeyboardEvent):void
{
var keycode_c:uint = 67;
if (event.ctrlKey &amp;&amp; event.keyCode == keycode_c)
{
// Separator used between Strings sent to clipboard
// to separate selected cells.
var separator:String = ",";
// The String sent to the clipboard
var dataString:String = "";
// Loop over the selectedCells property.
// Data in selectedCells is ordered so that
// the last selected cell is at the head of the list.
// Process the data in reverse so
// that it appears in the correct order in the clipboard.
var n:int = event.currentTarget.selectedCells.length;
for (var i:int = 0; i &lt; n; i++)
{
var cell:Object = event.currentTarget.selectedCells[i];
// Get the row for the selected cell.
var data:Object =
event.currentTarget.dataProvider[cell.rowIndex];
// Get the name of the field for the selected cell.
var dataField:String =
event.currentTarget.columns[cell.columnIndex].dataField;
// Get the cell data using the field name.
dataString = data[dataField] + separator + dataString;
}
// Remove trailing separator.
dataString =
dataString.substr(0, dataString.length - separator.length);
// Write dataString to the clipboard.
System.setClipboard(dataString);
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"
dataProvider="{dpADG}"
selectionMode="multipleCells"
allowMultipleSelection="true"
keyUp="myKeyUpHandler(event);"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Artist"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Album"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Price"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;mx:TextArea id="myTA"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache"><!-- --></a>
<h2 class="topictitle2">Hierarchical and grouped data display</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
supports the display of hierarchical and grouped data. To support
this display, the AdvancedDataGrid control displays a navigation tree
in a column that lets you navigate the data hierarchy. </p>
<p>
<em>Hierarchical data</em> is data already in a structure of parent
and child data items. You can pass hierarchical data directly to
the AdvancedDataGrid control. <em>Grouped data</em> is data that starts
out as flat data with no inherent hierarchy. Before passing the
flat data to the AdvancedDataGrid control, you specify one or more
data fields that are used to group the flat data into a hierarchy. </p>
<p>The following code shows hierarchical data in the SimpleHierarchicalData.as
file:</p>
<pre class="codeblock">[Bindable]
private var dpHierarchy:ArrayCollection = new ArrayCollection([
{Region:"Southwest", children: [
{Region:"Arizona", children: [
{Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000}]},
{Region:"Central California", children: [
{Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000}]},
{Region:"Nevada", children: [
{Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000}]},
{Region:"Northern California", children: [
{Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000}]},
{Region:"Southern California", children: [
{Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}]}
]}
]);</pre>
<p>Notice that the data contains a top-level object that contains
a Region field and multiple second-level children. Each second-level
child also contains a Region field and one or more additional children.
The following example shows the AdvancedDataGrid control displaying
this data:</p>
<div class="figborder">
<img src="images/ad_simpleHierarchy.png" alt="Each second-level child also contains a Region field and one or more additional children"/>
</div>
<p>The code for this example is in the section <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bed_verapache">Controlling
the navigation tree of the AdvancedDataGrid control</a>.</p>
<p>To display flat data as a hierarchy, you group the rows of the
flat data before passing the data to the AdvancedDataGrid control.
The following code contains a variation on the hierarchical data
shown in the previous image, but arranges the data in a flat data
structure:</p>
<pre class="codeblock">[Bindable]
private var dpFlat:ArrayCollection = new ArrayCollection([
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000},
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000},
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}
]);</pre>
<p>In this example, the data contains a single level of individual
records with no inherent hierarchy. To group the data, you specify
one or more data fields used to arrange the data in a hierarchy.
The following example shows the AdvancedDataGrid control where the
flat data has been grouped by the Region field of the data:</p>
<div class="figborder">
<img src="images/ac_simpleGroup.png" alt="AdvancedDataGrid control where the flat data has been grouped by the Region field of the data:"/>
</div>
<p>The code for this example is in the section <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bec_verapache">Displaying
grouped data</a>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff0_verapache"><!-- --></a>
<h3 class="topictitle3">Setting the data provider with
hierarchical data</h3>
<div>
<p>To configure the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
to display hierarchical data and the navigation tree, you pass to
the <samp class="codeph">dataProvider</samp> property an instance of the HierarchicalData
class or of the GroupingCollection2 class. Use the HierarchicalData
class when your data is already arranged in a hierarchy. Use the GroupingCollection2
class when your data is in a flat structure. As part of configuring
an instance of the GroupingCollection2 class, you specify one or
more data fields that are used to arrange the flat data in a hierarchy.</p>
<p>When using the AdvancedDataGrid control with hierarchical data,
you might have to free memory when you replace the data provider
of the control. For more information, see the article <a href="http://kb2.adobe.com/cps/897/cpsid_89785.html" target="_blank">Free memory when you replace the data provider
of the AdvancedDataGrid control</a>.</p>
<p>For more information on displaying hierarchical data, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7beb_verapache">Displaying
hierarchical data</a>. For more information on displaying grouped
data, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bec_verapache">Displaying
grouped data</a>.</p>
<p>You can create an instance of the HierarchicalData class or an
instance of the GroupingCollection2 class from any data that you
can use as a data provider. However, the AdvancedDataGrid control
modifies its internal representation of the data as follows: </p>
<ul>
<li>
<p>An Array is represented internally by the AdvancedDataGrid
control as an instance of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayCollection.html" target="_blank">ArrayCollection</a> class.</p>
</li>
<li>
<p>An ArrayCollection class is represented internally by the
AdvancedDataGrid control as an instance of the ArrayCollection class.</p>
</li>
<li>
<p>A String that contains valid XML text is represented internally
by the AdvancedDataGrid control as an instance of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/XMLListCollection.html" target="_blank">XMLListCollection</a> class.</p>
</li>
<li>
<p>An <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/xml/XMLNode.html" target="_blank">XMLNode</a> class
or an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/XMLList.html" target="_blank">XMLList </a>class is represented
internally by the AdvancedDataGrid control as an instance of the
XMLListCollection class. </p>
</li>
<li>
<p>Any object that implements the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ICollectionView.html" target="_blank">ICollectionView</a> interface
is represented internally by the AdvancedDataGrid control as an
instance of the ICollectionView interface.</p>
</li>
<li>
<p>An object of any other data type is wrapped in an Array instance
with the object as its sole entry.</p>
</li>
</ul>
<p>For example, you use an Array to create an instance of the HierarchicalData
class, and then pass that HierarchicalData instance to the <samp class="codeph">AdvancedDataGrid.dataProvider</samp> property.
If you read the data back from the <samp class="codeph">AdvancedDataGrid.dataProvider</samp> property,
it is returned as an ArrayCollection instance. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff0_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7ff0_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fef_verapache"><!-- --></a><h4 class="sectiontitle">Calling
validateNow() after setting the data provider</h4>
<p>In some
situations, you may set the data provider of the AdvancedDataGrid control
to hierarchical or grouped data, and then immediately try to perform
an action based on the new data provider. This typically occurs
when you set the <samp class="codeph">dataProvider</samp> property in ActionScript,
as the following example shows:</p>
<pre class="codeblock"> adg.dataProvider = groupedCollection;
 adg.expandAll();</pre>
<p>In this example, the call to <samp class="codeph">expandAll()</samp> fails
because the AdvancedDataGrid control is in the process of setting
the <samp class="codeph">dataProvider</samp> property, and the <samp class="codeph">expandAll()</samp> method
either processes the old value of the <samp class="codeph">dataProvider</samp> property,
if one existed, or does nothing. </p>
<p>In this situation, you must
insert the <samp class="codeph">validateNow()</samp> method after setting the data
provider. The <samp class="codeph">validateNow()</samp> method validates and
updates the properties and layout of the control, and then redraws
it, if necessary. The following example inserts the <samp class="codeph">validateNow()</samp> method
before the <samp class="codeph">expandAll()</samp> method: </p>
<pre class="codeblock"> adg.dataProvider = groupedCollection;
 adg.validateNow();
 adg.expandAll();</pre>
<p>Do not insert the <samp class="codeph">validateNow()</samp> method
every time you set the <samp class="codeph">dataProvider</samp> property because
it can affect the performance of your application; it is only required
in some situations when you attempt to perform an operation on the
control immediately after setting the <samp class="codeph">dataProvider</samp> property. </p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bed_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bed_verapache"><!-- --></a>
<h3 class="topictitle3">Controlling the navigation tree
of the AdvancedDataGrid control</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
is sometimes referred to as a <em>tree datagrid</em> because a column
of the control uses an expandable tree to determine which rows are
currently visible in the control. Often, the tree appears in the
left-most column of the control, where the first column of the control
is associated with a field of the control’s data provider. That
data field of the data provider provides the text for the labels
of the tree nodes.</p>
<p>In the following example, you populate the AdvancedDataGrid control
with the hierarchal data structure shown in <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache">Hierarchical
and grouped data display</a>. The data contains a top-level object
that contains a Region field, and multiple second-level children.
Each second-level child also contains a Region field and one or
more children.</p>
<p>The AdvancedDataGrid control in this example defines four columns
to display the data: Region, Territory Rep, Actual, and Estimate. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The following image shows the AdvancedDataGrid control created
by this example. The control displays a folder icon to represent
branch nodes of the tree, and a file icon to represent leaf nodes.
The first column of the control is associated with the Region field
of the data provider, so the tree labels display the value of the
Region field.</p>
<div class="figborder">
<img src="images/ad_simpleHierarchy.png" alt="AdvancedDataGrid control where the flat data has been grouped by the Region field of the data:"/>
</div>
<p>Notice that the leaf icon for the tree does not show a label.
This is because the individual records for each territory representative
do not contain a Region field. </p>
<p>While the tree is often positioned in the left-most column of
the control, you can use the <samp class="codeph">treeColumn</samp> property
to specify any column in the control, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/HierarchicalADGCategoriesTreeColumn.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "HierarchicalDataCategories.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid
width="100%" height="100%"
treeColumn="{rep}"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"
childrenField="categories"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn id="rep"
dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fed_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fed_verapache"><!-- --></a>
<h3 class="topictitle3">Setting navigation tree icons and
labels</h3>
<div>
<p>The navigation tree lets you control the icons and labels
used for the branch and leaf nodes. For example, you can display
a tree of labels with no icons, a tree with just folder icons, a
tree with no labels at all, or a tree in its own column that is
not associated with any data field. </p>
<p>The following table describes the style properties of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
that you use to set the tree icons:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e1504">
<p>Style property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e1510">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1504 ">
<div class="p">
<pre class="codeblock">defaultLeafIcon</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1510 ">
<p>Specifies the leaf icon. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1504 ">
<div class="p">
<pre class="codeblock">disclosureClosedIcon</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1510 ">
<p>Specifies the icon that is displayed next
to a closed branch node. The default icon is a black triangle.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1504 ">
<div class="p">
<pre class="codeblock">disclosureOpenIcon</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1510 ">
<p>Specifies the icon that is displayed next
to an open branch node. The default icon is a black triangle.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1504 ">
<div class="p">
<pre class="codeblock">folderClosedIcon</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1510 ">
<p>Specifies the folder closed icon for a branch
node. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1504 ">
<div class="p">
<pre class="codeblock">folderOpenIcon</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e1510 ">
<p>Specifies the folder open icon for a branch
node.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The following example sets the default leaf icon to null to hide
it, and uses custom icons for the folder open and closed icons:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADGTreeIcons.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"
defaultLeafIcon="{null}"
folderOpenIcon="@Embed(source='assets/folderOpenIcon.jpg')"
folderClosedIcon="@Embed(source='assets/folderClosedIcon.jpg')"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>You can also specify the styles by using the <samp class="codeph">setStyle()</samp> method,
and by using an <samp class="codeph">&lt;fx:Style&gt;</samp> tag, as the following
example shows:</p>
<pre class="codeblock"> &lt;fx:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
  s|AdvancedDataGrid {
  defaultLeafIcon:ClassReference(null);
  folderOpenIcon:Embed(source='assets/folderOpenIcon.jpg');
  folderClosedIcon:Embed(source='assets/folderClosedIcon.jpg');
  }
 &lt;/fx:Style&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fec_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fec_verapache"><!-- --></a>
<h3 class="topictitle3">Using the groupIconFunction and
groupLabelFunction properties </h3>
<div>
<p>Use the <samp class="codeph">groupIconFunction</samp> and <samp class="codeph">groupLabelFunction</samp> properties
of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> class
to define callback functions to control the display of the leaf
nodes of the navigation tree. The callback function specified by
the <samp class="codeph">groupIconFunction</samp> property controls the icon,
and the callback function specified by the <samp class="codeph">groupLabelFunction</samp> controls
the label.</p>
<p>The following example uses the <samp class="codeph">groupIconFunction</samp> property
to display a custom icon for the top level node of the navigation
tree, and display the default icon for all other leaf nodes of the
tree: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADGGroupIcon.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
// Embed the icon for the groups.
[Bindable]
[Embed(source="assets/topTreeIcon.png")]
public var icn:Class;
// Define the groupIconFunction callback function.
public function myIconFunc(item:Object, depth:int):Class {
if(depth == 1)
// If this is the top-level of the tree, return the icon.
return icn;
else
// If this is any other level, return null.
return null;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid
width="100%" height="100%"
groupIconFunction="myIconFunc"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be4_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a separate column for
the navigation tree </h3>
<div>
<p>In the examples in <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bf4_verapache">Hierarchical
and grouped data display</a>, the first column also displays
the Region field of the data. Therefore, as you expand the nodes
of the navigation tree, the label of each tree node corresponds
to the value of the Region field in the data provider for that row.
For the leaf nodes of the tree, the data provider does not contain
a value for the Region field, so the labels for the leaf nodes are
blank.</p>
<p>You can also put the navigation tree in its own column, where
the column is not associated with a data field, as the following
example shows: </p>
<div class="figborder">
<img src="images/ad_simpleHierarchyTreeColumn.png" alt="The navigation tree in its own column"/>
</div>
<p>This example does not associate a data field with the column
that contains the tree, so the tree icons appear with no label.
This example also sets the <samp class="codeph">folderClosedIcon</samp>, <samp class="codeph">folderOpenIcon</samp>,
and <samp class="codeph">defaultLeafIcon</samp> properties of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
to null, but does display the disclosure icons so that the user
can still open and close tree nodes. </p>
<p>The following code implements this example. Notice that the first
column is not associated with a data field. Because it is the first
column in the data grid, the AdvancedDataGrid control automatically
uses it to display the navigation tree.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADGTreeColumn.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"
folderClosedIcon="{null}"
folderOpenIcon="{null}"
defaultLeafIcon="{null}"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn headerText="" width="50"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7beb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7beb_verapache"><!-- --></a>
<h2 class="topictitle2">Displaying hierarchical data</h2>
<div>
<p>Hierarchical data is data in a structured format where
the data is already arranged in a hierarchy. To display hierarchical
data in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control,
you set the data provider of the control to an instance of the HierarchicalData
class. The structure of the data in the data provider defines how
the AdvancedDataGrid control displays the data.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe9_verapache"><!-- --></a>
<h3 class="topictitle3">Defining hierarchical data with
an ArrayCollection</h3>
<div>
<p>Using an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayCollection.html" target="_blank">ArrayCollection</a> is
a common way to create hierarchical data, as the following example
shows in the SimpleHierarchicalData.as file. In this example, the
data has three levels – a root level and two child levels:</p>
<p>
</p>
<pre class="codeblock">[Bindable]
private var dpHierarchy:ArrayCollection = new ArrayCollection([
{Region:"Southwest", children: [
{Region:"Arizona", children: [
{Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000}]},
{Region:"Central California", children: [
{Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000}]},
{Region:"Nevada", children: [
{Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000}]},
{Region:"Northern California", children: [
{Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000}]},
{Region:"Southern California", children: [
{Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}]}
]}
]);</pre>
<p>This example uses the <samp class="codeph">children</samp> keyword in the
ArrayCollection definition to define the data hierarchy. The <samp class="codeph">children</samp> keyword
is the default keyword used by the HierarchicalData class to define
the hierarchy. </p>
<p>You can use a different keyword to define the hierarchy. The
following example shows the HierarchicalDataCategories.as file,
which uses the <samp class="codeph">categories</samp> keyword:</p>
<pre class="codeblock">[Bindable]
private var dpHierarchy:ArrayCollection = new ArrayCollection([
{Region:"Southwest", categories: [
{Region:"Arizona", categories: [
{Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000}]},
{Region:"Central California", categories: [
{Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000}]},
{Region:"Nevada", categories: [
{Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000}]},
{Region:"Northern California", categories: [
{Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000}]},
{Region:"Southern California", categories: [
{Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}]}
]}
]);</pre>
<p>Use the <samp class="codeph">HierarchicalData.childrenField</samp> property
to specify the name of the field that defines the hierarchy, as
the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/HierarchicalADGCategories.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "HierarchicalDataCategories.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"
childrenField="categories"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe8_verapache"><!-- --></a>
<h3 class="topictitle3">Displaying hierarchical XML data </h3>
<div>
<p>The examples in the previous section use an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayCollection.html" target="_blank">ArrayCollection</a> to
populate the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
You can also populate the control with hierarchical XML data. The
following example modifies the data from the previous section to format
it as XML, and then passes that data to the AdvancedDataGrid control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADGXML.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.HierarchicalData;
import mx.collections.XMLListCollection;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;fx:XMLList id="dpHierarchyXML" &gt;
&lt;Region Region="Southwest"&gt;
&lt;Region Region="Arizona"&gt;
&lt;Territory_Rep Territory_Rep="Barbara Jennings"
Actual="38865" Estimate="40000"/&gt;
&lt;Territory_Rep Territory_Rep="Dana Binn"
Actual="29885" Estimate="30000"/&gt;
&lt;/Region&gt;
&lt;Region Region="Central California"&gt;
&lt;Territory_Rep Territory_Rep="Joe Smith"
Actual="29134" Estimate="30000"/&gt;
&lt;/Region&gt;
&lt;Region Region="Nevada"&gt;
&lt;Territory_Rep Territory_Rep="Bethany Pittman"
Actual="52888" Estimate="45000"/&gt;
&lt;/Region&gt;
&lt;Region Region="Northern California"&gt;
&lt;Territory_Rep Territory_Rep="Lauren Ipsum"
Actual="38805" Estimate="40000"/&gt;
&lt;Territory_Rep Territory_Rep="T.R. Smith"
Actual="55498" Estimate="40000"/&gt;
&lt;/Region&gt;
&lt;Region Region="Southern California"&gt;
&lt;Territory_Rep Territory_Rep="Alice Treu"
Actual="44985" Estimate="45000"/&gt;
&lt;Territory_Rep Territory_Rep="Jane Grove"
Actual="44913" Estimate="45000"/&gt;
&lt;/Region&gt;
&lt;/Region&gt;
&lt;/fx:XMLList&gt;
&lt;/fx:Declarations&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"
dataProvider="{new HierarchicalData(dpHierarchyXML)}"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="@Region"
headerText="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="@Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="@Actual"
headerText="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="@Estimate"
headerText="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bec_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bec_verapache"><!-- --></a>
<h2 class="topictitle2">Displaying grouped data</h2>
<div>
<p>Grouped data is flat data that you arrange in a hierarchy
for display in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
To group your data, you specify one or more data fields that collect
the data into the hierarchy.</p>
<div class="p">To populate the AdvancedDataGrid control with grouped data, create
an instance of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/GroupingCollection2.html" target="_blank">GroupingCollection2</a> class
from your flat data, and then pass that GroupingCollection2 instance
to the data provider of the AdvancedDataGrid control. When you create
the instance of the GroupingCollection2 from your flat data, you
specify the fields for the data that are used to create the hierarchy. <div class="note"><span class="notetitle">Note:</span> In
the previous release of Flex, you used the GroupingCollection class
with the AdvancedDataGrid control. The GroupingCollection2 class
is new for Flex 4 and provides better performance than GroupingCollection.</div>
</div>
<p>Most of the examples in this section use the following flat data
to create an instance of the GroupingCollection2 class:</p>
<pre class="codeblock">[Bindable]
private var dpFlat:ArrayCollection = new ArrayCollection([
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000},
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000},
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}
]);</pre>
<p>The following image shows an AdvancedDataGrid control that uses
this data as input. This example specifies two fields that are used
to group the data: Region and Territory. The first column of the
AdvancedDataGrid control is associated with the Region field, so
the navigation tree uses the Region field to define the labels for
the leaf nodes of the tree. </p>
<div class="figborder">
<img src="images/ad_SimpleGroupADGMXML.png" alt="The navigation tree in its own column"/>
</div>
<p>The following code implements this example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleGroupADGMXML.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as"
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:grouping&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"/&gt;
&lt;mx:GroupingField name="Territory"/&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The GroupingCollection2 instance reformats the data based on
these fields so that internally it is represented by the GroupingCollection2
instance, as the following example shows:</p>
<p>
</p>
<pre class="codeblock">[{GroupLabel:"Southwest", children:[
{GroupLabel:"Arizona", children:[
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000}]}
{GroupLabel:"Central California", children:[
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000}]}
{GroupLabel:"Nevada", children:[
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000}]}
{GroupLabel:"Northern California", children:[
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000}]}
{GroupLabel:"Southern California", children:[
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}]}
]}]</pre>
<p>Notice that the representation consists of a data hierarchy based
on the Region and Territory fields of the flat data. The GroupingCollection2
instance still contains the original rows of the input flat data,
but those rows are now arranged in a hierarchy based on the grouping
fields. </p>
<p>
</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe6_verapache"><!-- --></a>
<h3 class="topictitle3">Using synchronous or asynchronous
refresh with the AdvancedDataGrid control</h3>
<div>
<p>The <samp class="codeph">GroupingCollection2.refresh()</samp> method
applies the settings of the GroupingCollection2 class to the data.
You must call this method any time you modify the GroupingCollection2
class, such as by setting the <samp class="codeph">grouping</samp>, <samp class="codeph">source</samp>,
or <samp class="codeph">summaries</samp> properties of the GroupingCollection2
class. You also call the <samp class="codeph">GroupingCollection2.refresh()</samp> method
when you modify a GroupingField of the GroupingCollection2 class,
such as by changing the <samp class="codeph">caseInsensitive</samp>, <samp class="codeph">compareFunction</samp>,
or <samp class="codeph">groupingFunction</samp> properties. </p>
<p>Notice that in the previous example, the AdvancedDataGrid control
calls the <samp class="codeph">GroupingCollection2.refresh()</samp> method
in response to the <samp class="codeph">initialize</samp> event of the AdvancedDataGrid
control.</p>
<div class="p">The <samp class="codeph">GroupingCollection2.refresh()</samp> method has
the following signature: <pre class="codeblock">public function refresh(async:Boolean = false, dispatchCollectionEvents:Boolean = false):Boolean</pre>
</div>
<p>Set the <samp class="codeph">async</samp> parameter to <samp class="codeph">false</samp>,
the default value, for synchronous refresh of the groups and any
group summaries. Set it to <samp class="codeph">true</samp> for asynchronous
refresh. </p>
<p>For synchronous refresh, all groups and summaries are updated
together before the method returns. That means your application
cannot perform other processing operations for the duration of the
call. It also prevents the user from interacting with the control
until the refresh completes. Synchronous refresh is optimized for
small data sets. Because a synchronous refresh updates all groups and
summaries together, it has better performance than an asynchronous refresh.
However, for large data sets, users might notice that the application pauses
for the duration of the refresh.</p>
<p>In asynchronous refresh, all groups and summaries are updated
individually. The <samp class="codeph">refresh()</samp> method returns before
the groups and summaries are updated so that your application can
continue execution. Also, the control is updated during the refresh
so that the user can continue to interact with it. For example,
in asynchronous refresh, if the <samp class="codeph">displayItemsExpanded</samp> property
is <samp class="codeph">true</samp>, the navigation tree is updated as new
groups are created.</p>
<p>The overhead of updating groups and summaries individually, rather
than all at once, makes an asynchronous refresh take longer than
a synchronous one. However, for large data sets, your application
continues to operate during the refresh.</p>
<p>The <samp class="codeph">dispatchCollectionEvents</samp> parameter configures
the dispatching of events in synchronous mode. If <samp class="codeph">false</samp>,
the default value, then no events are dispatched during the refresh.
This setting provides the best performance for creating groups and
summaries. If <samp class="codeph">true</samp>, then events are dispatched
as groups and summaries are calculated to update the control. However,
the navigation tree is not updated as new groups are created.</p>
<p>For an asynchronous refresh, the <samp class="codeph">dispatchCollectionEvents</samp> parameter is
always set to <samp class="codeph">true</samp>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe5_verapache"><!-- --></a>
<h3 class="topictitle3">Using the default MXML property
of the GroupingCollection2 class</h3>
<div>
<p>The <samp class="codeph">grouping</samp> property is the default MXML
property of the GroupingCollection2 class, so you can rewrite the
previous example as follows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleGroupADGMXMLDefaultProp.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as"
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"/&gt;
&lt;mx:GroupingField name="Territory"/&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe4_verapache"><!-- --></a>
<h3 class="topictitle3">Setting the name of the GroupLabel
field</h3>
<div>
<p>By default, GroupLabel is the field name for the data items
added to the flat data to create the hierarchy. For an example of
the data structure created by the GroupingCollection2 class that
uses the default field name, see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7bec_verapache">Displaying grouped
data</a>.</p>
<p>Use the <samp class="codeph">Grouping.label</samp> property to specify a
different name so that you can create a different group label for
each level of the generated hierarchy. You should always set the <samp class="codeph">Grouping.label</samp> property
for the top level in your hierarchy. That property is required to
sort the nodes of the navigation tree.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe3_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a column for the GroupLabel
field</h3>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
uses the GroupLabel field to define the labels for the branch nodes
of the navigation tree. One option when displaying grouped data
is to create a column for the top-level data items that the grouping
fields create. For example, you group your flat data by the Region
and Territory fields. These fields appear as the labels for the
branch nodes of the navigation tree, so you omit separate columns
for those fields, as the following example shows:</p>
<div class="figborder">
<img src="images/ad_simpleGroupGroupLabel.png" alt="Create a column for the top-level data items that the grouping fields create"/>
</div>
<p>The following code creates this example. Notice that this example
includes an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/advancedDataGridClasses/AdvancedDataGridColumn.html" target="_blank">AdvancedDataGridColumn</a> instance
for the GroupLabel field, and no column definitions for the Region
and Territory fields.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleGroupADGGroupLabelMXML.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
defaultLeafIcon="{null}"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping&gt;
&lt;mx:GroupingField name="Region"/&gt;
&lt;mx:GroupingField name="Territory"/&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="GroupLabel"
headerText="Region/Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe2_verapache"><!-- --></a>
<h3 class="topictitle3">Creating groups in ActionScript</h3>
<div>
<p>The example in the previous section created the groups
in MXML. However, you could let the user define the grouping at
run time. The following example creates the groups in ActionScript
by using an event handler:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleGroupADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.GroupingField;
import mx.collections.Grouping;
import mx.collections.GroupingCollection2;
import mx.collections.ArrayCollection;
include "SimpleFlatData.as";
[Bindable]
public var myGColl:GroupingCollection2 = new GroupingCollection2();
private var myGrp:Grouping = new Grouping();
private function initDG():void {
// Initialize the GroupingCollection2 instance.
myGColl.source = dpFlat;
// The Grouping instance defines the grouping fields
// in the collection, and the order of the groups
// in the hierarchy.
myGrp.fields =
[new GroupingField("Region"), new GroupingField("Territory")];
myGrp.label = "Region";
// The grouping property contains a Grouping instance.
myGColl.grouping = myGrp;
// Specify the GroupedCollection as the data provider for
// the AdvancedDataGrid control.
myADG.dataProvider=myGColl;
// Refresh the display.
myGColl.refresh();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
creationComplete="initDG();"&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache"><!-- --></a>
<h3 class="topictitle3">Creating summary rows</h3>
<div>
<p>Summary data provides a way for you to extract information
from your data for display in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
For example, you can add summary data that contains the average
value of a field across all rows of your data, that contains the
maximum field value, the minimum field value, or that contains other
types of summaries. </p>
<div class="note"><span class="notetitle">Note:</span> Summary data is not supported for hierarchical
data represented by the HierarchicalData class. You can only create
summary data for data represented by the GroupingCollection2 class.</div>
<p>You create summary data about your groups by using the <samp class="codeph">summaries</samp> property of
the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/GroupingField.html" target="_blank">GroupingField</a> class.
You can display the summary data in an existing row of the AdvancedDataGrid
control, or display it in a separate row. </p>
<p>The following example shows an AdvancedDataGrid control that
displays two summary fields, Min Actual and Max Actual:</p>
<div class="figborder">
<img src="images/ad_summaryGroup.png" alt="AdvancedDataGrid control that displays two summary fields, Min Actual and Max Actual"/>
</div>
<p>The Min Actual and Max Actual fields in the top row correspond
to summaries for all rows in the group, and the Min Actual and Max
Actual fields for each Territory correspond to summaries for all
rows in the territory subgroup.</p>
<p>The following code creates this control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SummaryGroupADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as"
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"&gt;
&lt;mx:summaries&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:fields&gt;
&lt;mx:SummaryField2 dataField="Actual"
label="Min Actual" summaryOperation="MIN"/&gt;
&lt;mx:SummaryField2 dataField="Actual"
label="Max Actual" summaryOperation="MAX"/&gt;
&lt;/mx:fields&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:summaries&gt;
&lt;/mx:GroupingField&gt;
&lt;mx:GroupingField name="Territory"&gt;
&lt;mx:summaries&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:fields&gt;
&lt;mx:SummaryField2 dataField="Actual"
label="Min Actual" summaryOperation="MIN"/&gt;
&lt;mx:SummaryField2 dataField="Actual"
label="Max Actual" summaryOperation="MAX"/&gt;
&lt;/mx:fields&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:summaries&gt;
&lt;/mx:GroupingField&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Min Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Max Actual"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>Notice in this example that you use the <samp class="codeph">GroupingField.summaries</samp> property
to specify the SummaryRow instance. The SummaryRow instance contains
all the information about a data summary. In this example, you use
the <samp class="codeph">summaryPlacement</samp> property to add the summary
data to the grouped data. Optionally, you can add new rows to contain
the summary data. </p>
<div class="p">Each SummaryRow instance specifies one or more SummaryField2
instances that create the data summary. In this example, you use
the <samp class="codeph">dataField</samp> property to specify that the summaries
are determined by the data in the Actual data field, the <samp class="codeph">label</samp> property
to specify the name of the data field created to hold the summary
data, and the <samp class="codeph">summaryOperation</samp> property to specify
how to create the summary for numeric fields. You can specify one
of the following values: <samp class="codeph">SUM</samp>, <samp class="codeph">MIN</samp>, <samp class="codeph">MAX</samp>, <samp class="codeph">AVG</samp>,
or <samp class="codeph">COUNT</samp>. <div class="note"><span class="notetitle">Note:</span> In the previous release of Flex,
you used the SummaryField class to create summary data. The SummaryField2
class is new for Flex 4 and provides better performance than SummaryField.</div>
</div>
<p>Internally, the GroupingCollection2 class represents the grouped
data, with the new summary data fields, as the following example
shows:</p>
<p>
</p>
<pre class="codeblock">[{GroupLabel:"Southwest", Max Actual:55498, Min Actual:29134, children:[
{GroupLabel:"Arizona", Max Actual:38865, Min Actual:29885, children:[
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000}]}
{GroupLabel:"Central California", Max Actual:29134, Min Actual:29134, children:[
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000}]}
{GroupLabel:"Nevada", Max Actual:52888, Min Actual:52888, children:[
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000}]}
{GroupLabel:"Northern California", Max Actual:55498, Min Actual:38805, children:[
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000}]}
{GroupLabel:"Southern California", Max Actual:44985, Min Actual:44913, children:[
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000}]}
]}]</pre>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fe0_verapache"><!-- --></a><h4 class="sectiontitle">Using
the default properties of the GroupingField and SummaryRow classes</h4>
<p>The <samp class="codeph">GroupingField.summaries</samp> property
is the default property for the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/GroupingField.html" target="_blank">GroupingField</a> class,
and the <samp class="codeph">SummaryRow.fields</samp> property is the default property
for the SummaryRow class; therefore, you can omit those properties
in your code and rewrite the previous example, as the following
example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SummaryGroupADGDefProp.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as"
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:SummaryField2 summaryOperation="MIN"
dataField="Actual" label="Min Actual"/&gt;
&lt;mx:SummaryField2 summaryOperation="MAX"
dataField="Actual" label="Max Actual"/&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:GroupingField&gt;
&lt;mx:GroupingField name="Territory"&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:SummaryField2 summaryOperation="MIN"
dataField="Actual" label="Min Actual"/&gt;
&lt;mx:SummaryField2 summaryOperation="MAX"
dataField="Actual" label="Max Actual"/&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:GroupingField&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Min Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Max Actual"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7be6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7be6_verapache"><!-- --></a><h4 class="sectiontitle">Specifying
the display location of the summary data in the AdvancedDataGrid
control</h4>
<p>The SummaryRow class contains the <samp class="codeph">summaryPlacement</samp> property
that determines where the summary data appears in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control.
The following table describes the values of the <samp class="codeph">summaryPlacement</samp> property:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e2298">
<p>Value of summaryPlacement property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e2304">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2298 ">
<div class="p">
<pre class="codeblock">first</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2304 ">
<p>Creates a summary row as the first row in
the group.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2298 ">
<div class="p">
<pre class="codeblock">last</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2304 ">
<p>Creates a summary row as the last row in
the group.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2298 ">
<div class="p">
<pre class="codeblock">group</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2304 ">
<p>Adds the summary data to the row corresponding
to the group.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>The previous example named SummaryGroupADG.mxml
shows an example of summary data added to the group by specifying <samp class="codeph">group</samp> as
the value of the <samp class="codeph">summaryPlacement</samp> property. The
following example shows the same grouped data but with the <samp class="codeph">summaryPlacement</samp> property
set to <samp class="codeph">last</samp>:</p>
<div class="figborder">
<img src="images/ad_summaryGroupLast.png" alt="Grouped data but with the summaryPlacement property set to last"/>
</div>
<p>You
can specify multiple values to the <samp class="codeph">summaryPlacement</samp> property, separated
by a space; for example, a value of <samp class="codeph">last group</samp> specifies
to show the summary at the group level and as the last row of the
group.</p>
<p>Internally, the GroupingCollection2 represents the
grouped data, with the new summary data fields, as the following
example shows:</p>
<p>
</p>
<pre class="codeblock">[{GroupLabel:"Southwest", children:[
{GroupLabel:"Arizona", children:[
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings", Actual:38865, Estimate:40000},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn", Actual:29885, Estimate:30000},
{Max Actual:38865, Min Actual:29885}]}
{GroupLabel:"Central California", children:[
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith", Actual:29134, Estimate:30000},
{Max Actual:29134, Min Actual:29134}]}
{GroupLabel:"Nevada", children:[
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman", Actual:52888, Estimate:45000},
{Max Actual:52888, Min Actual:52888}]}
{GroupLabel:"Northern California", children:[
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum", Actual:38805, Estimate:40000},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith", Actual:55498, Estimate:40000},
{Max Actual:55498, Min Actual:38805}]}
{GroupLabel:"Southern California", children:[
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu", Actual:44985, Estimate:45000},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove", Actual:44913, Estimate:45000},
{Max Actual:44985, Min Actual:44913}]}
{Max Actual:55498, Min Actual:29134}
]}]</pre>
<p>Notice that a new row is added to the entire group
to hold the summary data, and a new row is added to each subgroup
to hold its summary data.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fde_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fde_verapache"><!-- --></a><h4 class="sectiontitle">Creating
multiple summaries</h4>
<p>You can specify multiple SummaryRow
instances in a single <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/GroupingField.html" target="_blank">GroupingField</a> instance.
In the following example, you create summary data to define the following
fields: Min Actual, Max Actual, Min Estimate, and Max Estimate for
the Region group.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SummaryGroupADGMultipleSummaries.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as"
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:SummaryField2 summaryOperation="MIN"
dataField="Actual" label="Min Actual"/&gt;
&lt;mx:SummaryField2 summaryOperation="MAX"
dataField="Actual" label="Max Actual"/&gt;
&lt;/mx:SummaryRow&gt;
&lt;mx:SummaryRow summaryPlacement="group"&gt;
&lt;mx:SummaryField2 summaryOperation="MIN"
dataField="Estimate" label="Min Estimate"/&gt;
&lt;mx:SummaryField2 summaryOperation="MAX"
dataField="Estimate" label="Max Estimate"/&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:GroupingField&gt;
&lt;mx:GroupingField name="Territory"/&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Min Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Max Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Min Estimate"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Max Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fdd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be5_verapache__WS2db454920e96a9e51e63e3d11c0bf65e9f-7fdd_verapache"><!-- --></a><h4 class="sectiontitle">Creating
a custom summary function</h4>
<p>Use the <samp class="codeph">SummaryRow.summaryObjectFunction</samp> property
and the <samp class="codeph">SummaryField2.summaryOperation</samp> property
to add custom summary logic to your application. Your custom summary
can perform many types of actions, but the result of the summary
calculation must be of type Number.</p>
<p>The <samp class="codeph">SummaryRow.summaryObjectFunction</samp> property
defines a callback function that defines an instance of the SummaryObject
class that collects the summary data. The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
adds the SummaryObject instance to the data provider to display
the summary data in the control. Therefore, you define within the
SummaryObject instance the properties to display. In the following
example, the callback function adds a property named Territory_Rep.
This field appears in the Territory Rep column of the control for
the summary row.</p>
<div class="p">The <samp class="codeph">SummaryField2.summaryOperation</samp> property
takes an object that implements the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ISummaryCalculator.html" target="_blank">mx.collections.ISummaryCalculator</a> interface.
That interface defines the following groups of methods: <ul>
<li>
<p>Implement the <samp class="codeph">summaryCalculationBegin()</samp>, <samp class="codeph">calculateSummary()</samp>,
and <samp class="codeph">returnSummary()</samp> methods to compute a summary
of the values.</p>
</li>
<li>
<p>Implement the <samp class="codeph">summaryOfSummaryCalculationBegin()</samp>, <samp class="codeph">calculateSummaryOfSummary()</samp>,
and <samp class="codeph">returnSummaryOfSummary()</samp> methods to compute
a summary of summary values.</p>
</li>
</ul>
</div>
<div class="p">The following definition
for the class MySummaryCalculator implements the ISummaryCalculator
interface to create a class to summarize a field in every other row
of a group:<pre class="codeblock">package myComponents
{
// dpcontrols/adg/myComponents/MySummaryCalculator.as
import mx.collections.ISummaryCalculator;
import mx.collections.SummaryField2;
public class MySummaryCalculator implements ISummaryCalculator
{
public function MySummaryCalculator() {
}
// Define the summary object.
protected var summObj:Object = new Object();
// Define a var to hold the record count.
protected var count:int;
public function summaryCalculationBegin(field:SummaryField2):Object {
// Initialize the variables.
summObj.oddCount = 0;
count = 1;
return summObj;
}
public function calculateSummary(data:Object, field:SummaryField2, rowData:Object):void {
// Only add the current value for every other row.
if (count % 2 != 0)
{
summObj.oddCount = summObj.oddCount + rowData[field.dataField];
}
count++;
}
public function returnSummary(data:Object, field:SummaryField2):Number {
// Return the summary value.
return summObj.oddCount;
}
// Implement these methods if you are creating a summary of summaries.
public function summaryOfSummaryCalculationBegin(value:Object, field:SummaryField2):Object {
return null;
}
public function calculateSummaryOfSummary(value:Object, newValue:Object, field:SummaryField2):void {
}
public function returnSummaryOfSummary(value:Object, field:SummaryField2):Number {
return 0;
}
}
}</pre>
</div>
<p>Notice that this class implements the <samp class="codeph">summaryOfSummaryCalculationBegin()</samp>, <samp class="codeph">calculateSummaryOfSummary()</samp>,
and <samp class="codeph">returnSummaryOfSummary()</samp> methods but leaves
the implementation empty.</p>
<p>The following example implements
callback functions for the <samp class="codeph">summaryObjectFunction</samp> and
use the MySummaryCalculator class to calculate a summary of the
actual sales revenue for every other row of each territory:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SummaryGroupADGCustomSummary.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.IViewCursor;
import mx.collections.SummaryObject;
import mx.controls.advancedDataGridClasses.AdvancedDataGridColumn;
import mx.collections.ArrayCollection;
import myComponents.MySummaryCalculator;
include "SimpleFlatData.as"
// Callback function to create
// the SummaryObject used to hold the summary data.
private function summObjFunc():SummaryObject {
// Define the object containing the summary data.
var obj:SummaryObject = new SummaryObject();
// Add a field containing a value for the Territory_Rep column.
obj.Territory_Rep = "Alternating Reps";
return obj;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
initialize="gc.refresh();"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:GroupingCollection2 id="gc" source="{dpFlat}"&gt;
&lt;mx:Grouping label="Region"&gt;
&lt;mx:GroupingField name="Region"/&gt;
&lt;mx:GroupingField name="Territory"&gt;
&lt;mx:summaries&gt;
&lt;mx:SummaryRow summaryObjectFunction="summObjFunc"
summaryPlacement="first"&gt;
&lt;mx:fields&gt;
&lt;mx:SummaryField2 dataField="Actual"
summaryOperation="{new myComponents.MySummaryCalculator()}"/&gt;
&lt;/mx:fields&gt;
&lt;/mx:SummaryRow&gt;
&lt;/mx:summaries&gt;
&lt;/mx:GroupingField&gt;
&lt;/mx:Grouping&gt;
&lt;/mx:GroupingCollection2&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf3_verapache"><!-- --></a>
<h2 class="topictitle2">Creating column groups</h2>
<div>
<p>You collect multiple columns under a single column heading
by using column groups, as the following example shows:</p>
<div class="figborder">
<img src="images/ac_simpleColumnGroup.png" alt="Collect multiple columns under a single column heading by using column groups"/>
</div>
<p>In this example, you use flat data to populate the data grid,
and group the Actual and Estimate columns under a single column
named Revenues. </p>
<p>To group columns in an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control,
you must do the following: </p>
<ul>
<li>
<p>Use the <samp class="codeph">AdvancedDataGrid.groupedColumns</samp> property,
rather than the <samp class="codeph">AdvancedDataGrid.columns</samp> property,
to specify the columns.</p>
</li>
<li>
<p>Use the AdvancedDataGridColumnGroup class to specify the
column groups.</p>
</li>
</ul>
<p>The following code implements the AdvancedDataGrid control shown
in the previous figure:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/ColumnGroupADG.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
// Import the data used by the AdvancedDataGrid control.
include "SimpleFlatData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
dataProvider="{dpFlat}"
width="100%" height="100%"&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The <samp class="codeph">groupedColumns</samp> property contains instances
of the AdvancedDataGridColumn class and of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/advancedDataGridClasses/AdvancedDataGridColumn.html" target="_blank">AdvancedDataGridColumn</a> class.
Instances of the AdvancedDataGridColumn class appear in the control
as stand-alone columns. All the columns specified in an AdvancedDataGridColumnGroup
instance appear together as a grouped column. </p>
<p>You can add multiple groups to the control. The following example
adds groups named Area and Revenues:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/ColumnGroupADG2Groups.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
dataProvider="{dpFlat}"
width="100%" height="100%"&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Area"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>You can nest groups so that one column group contains multiple
column groups, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/ColumnGroupADG2NestedGroups.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleFlatData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
dataProvider="{dpFlat}"
width="100%" height="100%"&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="All Groups"&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Area"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fdb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fdb_verapache"><!-- --></a>
<h3 class="topictitle3">Dragging and dropping columns in
the group</h3>
<div>
<p>By default, you can drag the columns in a group within
the group to reposition them. You can also drag the entire group
to reposition it in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control. </p>
<p>To disable dragging of all columns in a group, set the <samp class="codeph">AdvancedDataGridColumnGroup.childrenDragEnabled</samp> property
to <samp class="codeph">false</samp>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd9_verapache"><!-- --></a>
<h3 class="topictitle3">Using grouped columns with hierarchical
data</h3>
<div>
<p>You can use column groups with hierarchical data, as well
as flat data. The following example modifies the example in the
section <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7be4_verapache">Creating
a separate column for the navigation tree </a> to group the Actual
and Estimates columns under the Revenues group column:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/SimpleHierarchicalADGGroupCol.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup headerText="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd8_verapache"><!-- --></a>
<h3 class="topictitle3">Specify a data field for the AdvancedDataGridColumnGroup
class</h3>
<div>
<p>The previous examples for column groups do not specify
a data field for the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/advancedDataGridClasses/AdvancedDataGridColumnGroup.html" target="_blank">AdvancedDataGridColumnGroup</a> class.
However, the AdvancedDataGridColumnGroup class is designed to work
with hierarchical data. Therefore, if you specify a data field for
the AdvancedDataGridColumnGroup class, it automatically creates
a column group for the subfields of that data field.</p>
<p>In the following example, the HierarchicalDataForGroupedColumns.as
file defines a hierarchical data set where the Revenues field contains
two subfields, Actual and Estimate:</p>
<p>
</p>
<pre class="codeblock">[Bindable]
private var dpHierarchy:ArrayCollection = new ArrayCollection([
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Barbara Jennings",
Revenues:{Actual:38865, Estimate:40000}},
{Region:"Southwest", Territory:"Arizona",
Territory_Rep:"Dana Binn",
Revenues:{Actual:29885, Estimate:30000}},
{Region:"Southwest", Territory:"Central California",
Territory_Rep:"Joe Smith",
Revenues:{Actual:29134, Estimate:30000}},
{Region:"Southwest", Territory:"Nevada",
Territory_Rep:"Bethany Pittman",
Revenues:{Actual:52888, Estimate:45000}},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"Lauren Ipsum",
Revenues:{Actual:38805, Estimate:40000}},
{Region:"Southwest", Territory:"Northern California",
Territory_Rep:"T.R. Smith",
Revenues:{Actual:55498, Estimate:40000}},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Alice Treu",
Revenues:{Actual:44985, Estimate:45000}},
{Region:"Southwest", Territory:"Southern California",
Territory_Rep:"Jane Grove",
Revenues:{Actual:44913, Estimate:45000}}
]);</pre>
<p>The following example uses this data and specifies the Revenues
field as the value of the <samp class="codeph">AdvancedDataGridColumnGroup.dataField</samp> property,
and creates the following output:</p>
<div class="figborder">
<img src="images/ad_colGroupHierarchData.png" alt="Specify the Revenues field as the value of the AdvancedDataGridColumnGroup.dataField property"/>
</div>
<p>The following code implements this example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/ColumnGroupHierarchData.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "HierarchicalDataForGroupedColumns.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
defaultLeafIcon="{null}"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:groupedColumns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumnGroup dataField="Revenues"&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;/mx:AdvancedDataGridColumnGroup&gt;
&lt;/mx:groupedColumns&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7bf2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7bf2_verapache"><!-- --></a>
<h2 class="topictitle2">Using item renderers with the AdvancedDataGrid
control</h2>
<div>
<p>You customize the appearance and behavior of cells in an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
by creating custom item renderers and item editors. Use the same process
for assigning item editors and item renderers to columns of the AdvancedDataGrid
control as you do with the DataGrid control. </p>
<p>For an introduction to item renderers and item editors, see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
<p>The AdvancedDataGrid control adds capabilities to support item
renderers. These capabilities let you perform the following actions:</p>
<ul>
<li>
<p>Create rows or columns not associated with data in the
data provider. For example, you can create summary rows from the
data provider.</p>
</li>
<li>
<p>Span multiple columns with a renderer.</p>
</li>
<li>
<p>Use multiple renderers in the same column. For example, when
displaying hierarchical data, you can use a different renderer in
the column based on the level of the row in the hierarchy.</p>
</li>
</ul>
<div class="note"><span class="notetitle">Note:</span> These capabilities support item renderers only;
use item editors as you do with the DataGrid control.</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd6_verapache"><!-- --></a>
<h3 class="topictitle3">Using an item renderer</h3>
<div>
<p>To use the item renderer capabilities of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control,
you assign the item renderer to the AdvancedDataGrid control itself,
not to a specific column, by using the <samp class="codeph">AdvancedDataGrid.rendererProviders</samp> property. The
following example assigns an item renderer to the Estimate column:</p>
<pre class="codeblock"> &lt;mx:AdvancedDataGrid&gt;
  &lt;mx:columns&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
  &lt;/mx:columns&gt;
 
  <strong>&lt;mx:rendererProviders&gt;</strong>
  <strong>&lt;mx:AdvancedDataGridRendererProvider </strong>
  <strong>columnIndex="3"</strong>
  <strong>columnSpan="1" </strong>
  <strong>renderer="myComponents.EstimateRenderer"/&gt;</strong>
  <strong>&lt;/mx:rendererProviders&gt;</strong>
 &lt;/mx:AdvancedDataGrid&gt;</pre>
<p>The <samp class="codeph">rendererProviders</samp> property contains an Array
of AdvancedDataGridRendererProvider instances. Each <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/advancedDataGridClasses/AdvancedDataGridRendererProvider.html" target="_blank">AdvancedDataGridRendererProvider</a> instance
defines the characteristics for a single item renderer. </p>
<p>In the previous example, the AdvancedDataGridRendererProvider
instance specifies to use the EstimateRenderer for column 3, where
the first column in the control is column 0, and the renderer spans
a single column. If you set the <samp class="codeph">columnSpan</samp> property
to 0, the renderer spans all columns in the row.</p>
<p>Rather than using the column index to assign the renderer, you
specify an <samp class="codeph">id</samp> property for the column, and then
use the <samp class="codeph">column</samp> property to associate the renderer
with the column, as the following example shows:</p>
<pre class="codeblock"> &lt;mx:AdvancedDataGrid&gt;
  &lt;mx:columns&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
  &lt;mx:AdvancedDataGridColumn id="estCol" dataField="Estimate"/&gt;
  &lt;/mx:columns&gt;
 
  &lt;mx:rendererProviders&gt;
  &lt;mx:AdvancedDataGridRendererProvider
  <strong>column="{estCol}"</strong>
  columnSpan="1"
  renderer="myComponents.EstimateRenderer"/&gt;
  &lt;/mx:rendererProviders&gt;
 &lt;/mx:AdvancedDataGrid&gt;</pre>
<p>The <samp class="codeph">depth</samp> property lets you associate the renderer
with a specific level in the hierarchy of the navigation tree of
an AdvancedDataGrid control, where the depth of the top-most node
in the navigation tree is 1. The following example associates the
renderer with the third level of a navigation tree:</p>
<pre class="codeblock">  &lt;mx:rendererProviders&gt;
  &lt;mx:AdvancedDataGridRendererProvider
  columnIndex="3"
  <strong>depth="3" </strong>
  columnSpan="1"
  renderer="myComponents.EstimateRenderer"/&gt;
  &lt;/mx:rendererProviders&gt;</pre>
<p>In the previous example, the AdvancedDataGrid control uses the
default renderer for the column until you expand it to the third
level of the navigation tree, and then it uses EstimateRenderer
component. You use the <samp class="codeph">depth</samp> property to assign
different renderers to the same column, where the <samp class="codeph">depth</samp> property specifies
the renderer to use for each level of the tree.</p>
<p>A renderer can span multiple columns. In the following example,
you create a renderer that spans two columns:</p>
<pre class="codeblock"> &lt;mx:AdvancedDataGrid&gt;
  &lt;mx:columns&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Territory_Rep" headerText="Territory Rep"/&gt;
  &lt;mx:AdvancedDataGridColumn id="actCol" dataField="Actual"/&gt;
  &lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
  &lt;/mx:columns&gt;
 
  &lt;mx:rendererProviders&gt;
  &lt;mx:AdvancedDataGridRendererProvider
  column="{actCol}"
  depth="3"
  <strong>columnSpan="2" </strong>
  renderer="myComponents.SummaryRenderer"/&gt;
  &lt;/mx:rendererProviders&gt;
 &lt;/mx:AdvancedDataGrid&gt;</pre>
<p>The previous example uses a single renderer that spans the Actual
and Estimate columns to display a combined view of the data for
these columns. For an implementation of the SummaryRenderer component,
see <a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7be2_verapache">Using
a renderer to generate column data</a>.</p>
<p>The following table describes the properties of the AdvancedDataGridRendererProvider
class that you use to configure the renderer:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e2910">
<p>Property</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e2916">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">column</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The ID of the column for which the renderer
is used. If you omit this property, you can use the <samp class="codeph">columnIndex</samp> property
to specify the column. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">columnIndex</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The column index for which the renderer
is used, where the first column has an index of 0.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">columnSpan</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The number of columns that the renderer
spans. Set this property to 0 to span all columns. The default value
is 1.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">dataField</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The data field in the data provider for
the renderer. This property is optional. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">depth</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The depth in the tree at which the renderer
is used, where the top-most node of the tree has a depth of 1. Use
this property when the renderer should be used only when the tree
is expanded to a certain depth, not for all nodes in the tree. By
default, the control uses the renderer for all levels of the tree.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">renderer</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The renderer.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2910 ">
<div class="p">
<pre class="codeblock">rowSpan</pre>
</div>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e2916 ">
<p>The number of rows that the renderer spans.
The default value is 1. </p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7be2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7be2_verapache"><!-- --></a>
<h3 class="topictitle3">Using a renderer to generate column
data</h3>
<div>
<p>The following example shows the results when an item renderer
is used to calculate the value of the Difference column of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control:</p>
<div class="figborder">
<img src="images/ad_hierarchSimpleRenderer.png" alt="An item renderer used to calculate the value of the Difference column"/>
</div>
<p>This example defines a column with the <samp class="codeph">id</samp> of
diffCol that is not associated with a data field in the data provider.
Instead, you use the <samp class="codeph">rendererProvider</samp> property
to assign an item renderer to the column. The item renderer calculates the
difference between the actual and estimate values, and then displays
a message based on whether the representative exceeded or missed
their estimate. </p>
<p>The following code implements this example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/HierarchicalADGSimpleRenderer.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"
width="750"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
include "SimpleHierarchicalData.as";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid width="100%" height="100%"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="Region"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Territory_Rep"
headerText="Territory Rep"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Actual"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="Estimate"/&gt;
&lt;mx:AdvancedDataGridColumn id="diffCol"
headerText="Difference"/&gt;
&lt;/mx:columns&gt;
&lt;mx:rendererProviders&gt;
&lt;mx:AdvancedDataGridRendererProvider column="{diffCol}"
depth="3" renderer="myComponents.SummaryRenderer"/&gt;
&lt;/mx:rendererProviders&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The following code shows the SummaryRenderer component:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/myComponents/SummaryRenderer.mxml --&gt;
&lt;mx:Label xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark" textAlign="center"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
override public function set data(value:Object):void
{
// Calculate the difference.
var diff:Number =
Number(value["Actual"]) - Number(value["Estimate"]);
if (diff &lt; 0)
{
// If Estimate was greater than Actual,
// display results in red.
setStyle("color", "red");
text = "Undersold by " + usdFormatter.format(diff);
}
else
{
// If Estimate was less than Actual,
// display results in green.
setStyle("color", "green");
text = "Exceeded estimate by " + usdFormatter.format(diff);
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;s:CurrencyFormatter id="usdFormatter"
useCurrencySymbol="true" negativeCurrencyFormat="1"/&gt;
&lt;/fx:Declarations&gt;
&lt;/mx:Label&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf65e9f-7fd4_verapache"><!-- --></a>
<h3 class="topictitle3">Using an item renderer that spans
an entire row</h3>
<div>
<p>You can use an item renderer with a hierarchical data set
to display an entire row of data. The following example shows a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/charts/PieChart.html" target="_blank">PieChart</a> control
that displays the data from the detail field of the hierarchical
data set. Each row contains detailed information about sales revenues
for the representative, which is rendered as a segment of the pie
chart:</p>
<div class="figborder">
<img src="images/ad_pieChartRenderer.png" alt="PieChart control that displays the data from the detail field of the hierarchical data set. "/>
</div>
<p>The following code implements this example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/GroupADGChartRenderer.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var dpHierarchy:ArrayCollection= new ArrayCollection([
{name:"Barbara Jennings", region: "Arizona", total:70, children:[
{detail:[{amount:5},{amount:10},{amount:20},{amount:45}]}]},
{name:"Dana Binn", region: "Arizona", total:130, children:[
{detail:[{amount:15},{amount:25},{amount:35},{amount:55}]}]},
{name:"Joe Smith", region: "California", total:229, children:[
{detail:[{amount:26},{amount:32},{amount:73},{amount:123}]}]},
{name:"Alice Treu", region: "California", total:230, children:[
{detail:[{amount:159},{amount:235},{amount:135},{amount:155}]}
]}
]);
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
variableRowHeight="true"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="name" headerText="Name"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="total" headerText="Total"/&gt;
&lt;/mx:columns&gt;
&lt;mx:rendererProviders&gt;
&lt;mx:AdvancedDataGridRendererProvider
dataField="detail"
renderer="myComponents.ChartRenderer"
columnIndex="0"
columnSpan="0"/&gt;
&lt;/mx:rendererProviders&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The following code renders the ChartRenderer.mxml component: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/myComponents/ChartRenderer.mxml --&gt;
&lt;mx:VBox height="200" width="100%" xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;mx:PieChart dataProvider="{data.detail}"
width="100%"
height="100%"
showDataTips="true"&gt;
&lt;mx:series&gt;
&lt;mx:PieSeries labelPosition="callout" field="amount"/&gt;
&lt;/mx:series&gt;
&lt;/mx:PieChart&gt;
&lt;/mx:VBox&gt;</pre>
<p>You can modify this example to display the PieChart control in
a column. In the following example, you add a Detail column to the
control, and then specify that the item renderer is for column 2
of the control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/adg/GroupADGChartRendererOneRow.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
private var dpHierarchy:ArrayCollection= new ArrayCollection([
{name:"Barbara Jennings", region: "Arizona", total:70, children:[
{detail:[{amount:5},{amount:10},{amount:20},{amount:45}]}]},
{name:"Dana Binn", region: "Arizona", total:130, children:[
{detail:[{amount:15},{amount:25},{amount:35},{amount:55}]}]},
{name:"Joe Smith", region: "California", total:229, children:[
{detail:[{amount:26},{amount:32},{amount:73},{amount:123}]}]},
{name:"Alice Treu", region: "California", total:230, children:[
{detail:[{amount:159},{amount:235},{amount:135},{amount:155}]}
]}
]);
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:AdvancedDataGrid id="myADG"
width="100%" height="100%"
variableRowHeight="true"&gt;
&lt;mx:dataProvider&gt;
&lt;mx:HierarchicalData source="{dpHierarchy}"/&gt;
&lt;/mx:dataProvider&gt;
&lt;mx:columns&gt;
&lt;mx:AdvancedDataGridColumn dataField="name" headerText="Name"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="total" headerText="Total"/&gt;
&lt;mx:AdvancedDataGridColumn dataField="detail" headerText="Detail"/&gt;
&lt;/mx:columns&gt;
&lt;mx:rendererProviders&gt;
&lt;mx:AdvancedDataGridRendererProvider
dataField="detail"
renderer="myComponents.ChartRenderer"
columnIndex="2"/&gt;
&lt;/mx:rendererProviders&gt;
&lt;/mx:AdvancedDataGrid&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db8_verapache"><!-- --></a>
<h2 class="topictitle2">Keyboard navigation</h2>
<div>
<p>The following keystrokes are built into the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/AdvancedDataGrid.html" target="_blank">AdvancedDataGrid</a> control
to let users navigate the control: </p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e3188">
<p>Keyboard action</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d14444e3194">
<p>Key assignments</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>Standard </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<div class="p">
<ul>
<li>
<p>Use the Up and Down Arrow keys
to scroll vertically by one row.</p>
</li>
<li>
<p>Type characters to do incremental type-ahead look-ups in
the first column.</p>
</li>
<li>
<p>Use the Home and End keys to move to the first and last rows.</p>
</li>
<li>
<p>Use the Page Up and Page Down keys to move to the last visible
row and then scroll vertically by the number of rows specified by
the <samp class="codeph">rowcount</samp> property.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>In editable mode</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<div class="p">
<ul>
<li>
<p>Use the Tab and Shift+Tab keys
to move to the next and previous cells, and start editing.</p>
</li>
<li>
<p>Use the Escape or Control+Period keys to cancel editing.</p>
</li>
<li>
<p>Use the Enter key based on the value of the <samp class="codeph">AdvancedDataGridColumn.editorUsesEnterKey</samp> property:</p>
</li>
<li>
<p>If <samp class="codeph">editorUsesEnterKey=true</samp>, the Enter key
is considered to be part of the input text.</p>
</li>
<li>
<p>If <samp class="codeph">editorUsesEnterKey=false</samp>, if single-line
editor, the Enter key saves the item and moves down a row.</p>
</li>
<li>
<p>If you use the Tab key to move focus to the AdvancedDataGrid
control, focus is placed on the position of the last edited item.</p>
</li>
<li>
<p>Use the Control click keys to select multiple discontiguous
items.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>For the expandable tree</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<div class="p">
<ul>
<li>
<p>Use the Multiply key on the number
pad (asterisk) to open or close all nodes under the current node,
with no animation.</p>
</li>
<li>
<p>Use the Add key on the number pad or the Space key to open
nodes with animation.</p>
</li>
<li>
<p>Use the Subtract key on the number pad to close nodes with
animation.</p>
</li>
<li>
<p>Use the Control+Shift+Space key to open a closed node, or
close an open node.</p>
</li>
<li>
<p>Use the Control+Shift+Right Arrow key to open a closed node,
or select the parent node of a leaf node.</p>
</li>
<li>
<p>Use the Control+Shift+Left Arrow to close open nodes. </p>
</li>
<li>
<p>Use the Up and Down Arrow keys to move up and down one row.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>For column headers </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<div class="p">
<ul>
<li>
<p>Use the arrow keys to move focus
to a column header.</p>
</li>
<li>
<p>The first Space key pressed when a column header has focus
sorts the column in descending order. Each subsequent press of the
Space key toggles the sort order between ascending and descending
order.</p>
</li>
<li>
<p>Use the Control+Space keys when a header has focus to sort
multiple columns.</p>
</li>
<li>
<p>Use the Left Arrow and Right Arrow keys to move to the previous
or next header, without column wrapping.</p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>To scroll vertically and horizontally in
pages</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<div class="p">
<ul>
<li>
<p>The first Page Up or Page Down
key pressed move to the first or last visible row. The next Page
Up or Page Down key pressed scrolls vertically up or down by a page,
which corresponds to the number of visible rows.</p>
</li>
<li>
<p>Use the Shift+Page Up and Shift+Page Down keys to move to
first or last visible column. </p>
</li>
</ul>
</div>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3188 ">
<p>To move focus out of AdvancedDataGrid while
editing is in progress</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d14444e3194 ">
<p>When you set <samp class="codeph">AdvancedDataGrid.editable=true</samp> or <samp class="codeph">AdvancedDataGridColumn=true</samp>:</p>
<div class="p">
<ul>
<li>
<p>Use the Tab key to move focus to the AdvancedDataGrid control.</p>
</li>
<li>
<p>Use the Tab key again to move focus to the next component.</p>
</li>
<li>
<p>Use the Left, Right, Up, and Down Arrow keys to move between
cells.</p>
</li>
<li>
<p>Use the Shift+Home and Shift+End keys to move to the first
and last column in current row. </p>
</li>
<li>
<p>Cells are only selected by default, they are not editable.</p>
</li>
<li>
<p>Press the F2 key to make a cell editable.</p>
</li>
<li>
<p>Use the arrow keys to move the cursor in the editing area.</p>
</li>
<li>
<p>Use the Escape key to cancel editing.</p>
</li>
<li>
<p>Use the Enter key to commit editing changes. </p>
</li>
<li>
<p>Same behavior as when <samp class="codeph">editable=true</samp>, but
the F2 key does not make the cell editable.</p>
</li>
<li>
<p>Use the Home and End keys to move to first and last rows.</p>
</li>
<li>
<p>Use the Page Up and Page Down keys to move to the previous
and next pages.</p>
</li>
</ul>
</div>
<p>When focus is on the AdvancedDataGrid
control:</p>
<div class="p">
<ul>
<li>
<p>Use the Left, Right, Up, and Down Arrow
keys to move between cells.</p>
</li>
<li>
<p>Use the Shift+Home and Shift+End keys to move to the first
and last column in current row. </p>
</li>
<li>
<p>Cells are only selected by default, they are not editable.</p>
</li>
<li>
<p>Press the F2 key to make a cell editable.</p>
</li>
<li>
<p>Use the arrow keys to move the cursor in the editing area.</p>
</li>
<li>
<p>Use the Escape key to cancel editing.</p>
</li>
<li>
<p>Use the Enter key to commit editing changes. </p>
</li>
<li>
<p>Same behavior as when <samp class="codeph">editable=true</samp>, but
the F2 key does not make the cell editable.</p>
</li>
<li>
<p>Use the Home and End keys to move to first and last rows.</p>
</li>
<li>
<p>Use the Page Up and Page Down keys to move to the previous
and next pages.</p>
</li>
</ul>
</div>
<p>When editing the cell:</p>
<div class="p">
<ul>
<li>
<p>Use the arrow keys to move the cursor in the editing area.</p>
</li>
<li>
<p>Use the Escape key to cancel editing.</p>
</li>
<li>
<p>Use the Enter key to commit editing changes. </p>
</li>
<li>
<p>Same behavior as when <samp class="codeph">editable=true</samp>, but
the F2 key does not make the cell editable.</p>
</li>
<li>
<p>Use the Home and End keys to move to first and last rows.</p>
</li>
<li>
<p>Use the Page Up and Page Down keys to move to the previous
and next pages.</p>
</li>
</ul>
</div>
<p>When you set <samp class="codeph">AdvancedDataGrid.editable=false</samp> or <samp class="codeph">AdvancedDataGridColumn=false</samp>:</p>
<div class="p">
<ul>
<li>
<p>Same behavior as when <samp class="codeph">editable=true</samp>, but
the F2 key does not make the cell editable.</p>
</li>
<li>
<p>Use the Home and End keys to move to first and last rows.</p>
</li>
<li>
<p>Use the Page Up and Page Down keys to move to the previous
and next pages.</p>
</li>
</ul>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<p/>
</div>
<p>Adobe and Adobe Flash Platform are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>