Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_dpcontrols_dpc.html
blob: 729113ed56c7157cc360178c177856a9e3db303a [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="MX data-driven controls"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7d7e_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>MX data-driven controls</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7d7e_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d7e_verapache"><!-- --></a>
<h1 class="topictitle1">MX data-driven controls</h1>
<div>
<p>
Several
MX controls take input from a data provider, an object that contains
data. For example, a Tree control reads data from a data provider
to define the structure of the tree and any associated data assigned
to each tree node. </p>
<p>Several of the controls that use a data provider let you visualize
complex data, and there are different ways to populate these controls
by using a data provider. The following topics also provide information
on data providers and controls that use data providers:</p>
<ul>
<li>
<p>
<a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a> contains details on data providers
and how to use collections as data providers.</p>
</li>
<li>
<p>
<a href="flx_menucontrols_mc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d7b_verapache">Menu-based
controls</a> contains information on using Menu, MenuBar, and PopUpMenuButton
controls.</p>
</li>
<li>
<p>
<a href="flx_advdatagrid_ad.html#WS2db454920e96a9e51e63e3d11c0bf69084-7be0_verapache">AdvancedDataGrid
control</a> contains information on using the AdvancedDataGrid
control, which expands on the functionality of the standard DataGrid control
to add data visualization features to your Flex application.</p>
</li>
<li>
<p>
<a href="flx_olapdatagrid_ol.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b38_verapache">OLAPDataGrid
control</a> contains information on using the OLAPDataGrid control,
which lets you aggregate large amounts of data for easy display
and interpretation.</p>
</li>
</ul>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d90_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d90_verapache"><!-- --></a>
<h2 class="topictitle2">MX List control</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/List.html" target="_blank">List</a> control
displays a vertical list of items. Its functionality is very similar
to that of the <samp class="codeph">SELECT</samp> form element in HTML. It
often contains a vertical scroll bar that lets users access the
items in the list. An optional horizontal scroll bar lets users
view items when the full width of the list items is unlikely to
fit. The user can select one or more items from the list.</p>
<p>Flex also includes the Spark List control. When possible, it’s
best that you use the Spark List control. For more information,
see <a href="flx_spark_dpcontrols_sdp.html#WSc2368ca491e3ff923c946c5112135c8ee9e-7fff_verapache">Spark
List control</a>.</p>
<div class="note"><span class="notetitle">Note:</span> The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/HorizontalList.html" target="_blank">HorizontalList</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TileList.html" target="_blank">TileList</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DataGrid.html" target="_blank">DataGrid</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Menu.html" target="_blank">Menu</a>, and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Tree.html" target="_blank">Tree</a> controls
are derived from the MX List control or its immediate parent, the
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/listClasses/ListBase.html" target="_blank">ListBase</a> class.
As a result, much of the information for the List control applies
to these controls.</div>
<p>
For complete reference
information, 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>
<p>The following image shows a List control:</p>
<div class="figborder">
<img src="images/dpc_list_example.png" alt="List control"/>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff5_verapache"><!-- --></a>
<h3 class="topictitle3">List control sizing</h3>
<div>
<p>If you specify <samp class="codeph">horizontalScrollPolicy="on"</samp>,
the default width of a List control does not change; it is still
large enough to display the widest visible label. If you set <samp class="codeph">horizontalScrollPolicy="on"</samp>,
and specify a List control pixel width, you can use the <samp class="codeph">measureWidthOfItems()</samp> method
to ensure that the scroll bar rightmost position corresponds to
the right edge of the content, as the following example shows. Notice
that the additional 5 pixels ensures that the rightmost character
of the text displays properly.</p>
<pre class="codeblock"> &lt;mx:List id="li2"
width="200" horizontalScrollPolicy="on"
maxHorizontalScrollPosition="{li2.measureWidthOfItems() - li2.width +5}"&gt;</pre>
<p>The preceding line ensures that the rightmost position of the
scroll bar puts the end of the longest measured list item near the
right edge of the List control. Using this technique, however, can
reduce application efficiency, so you might consider using explicit
sizes instead.</p>
<p>Lists, and all subclasses of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/listClasses/ListBase.html" target="_blank">ListBase</a> class,
determine their sizes when a style changes or the data provider
changes.</p>
<p>If you set a <samp class="codeph">width</samp> property that is less than
the width of the longest label and specify the <samp class="codeph">horizontalScrollPolicy="off"</samp>,
labels that exceed the control width are clipped.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd9_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a List control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:List&gt;</samp> tag to define a List control.
Specify an <samp class="codeph">id</samp> value if you intend to refer to a
component elsewhere in your MXML, either in another tag or in an
ActionScript block.</p>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/List.html" target="_blank">List</a> control
uses a list-based data provider. For more information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data providers
and collections</a>.</p>
<p>You specify the data for the List control by using the <samp class="codeph">dataProvider</samp> property of
the control. However, because <samp class="codeph">dataProvider</samp> is the
List control’s default property, you do not have to specify a <samp class="codeph">dataProvider</samp> child
tag of the <samp class="codeph">&lt;mx:List&gt;</samp> tag. In the simplest
case for creating a static List control, you need only put <samp class="codeph">&lt;fx:String&gt;</samp> tags
in the control body, because Flex also automatically interprets
the multiple tags as an Array of Strings, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ListDataProvider.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:List&gt;
&lt;mx:dataProvider&gt;
&lt;fx:String&gt;AK&lt;/fx:String&gt;
&lt;fx:String&gt;AL&lt;/fx:String&gt;
&lt;fx:String&gt;AR&lt;/fx:String&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:List&gt;
&lt;/s:Application&gt;</pre>
<p>Because the data in this example is inline static data, it is
not necessary to explicitly wrap it in an ArrayList or ArrayCollection
object. However, when working with data that could change, it is
always best to specify a list or collection explicitly; for more
information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>
The index
of items in the List control is zero-based, which means that values
are 0, 1, 2, ... , <em>n</em> - 1, where <em>n</em> is the total number
of items. The value of the item is its label text. </p>
<p>You typically use events to handle user interaction with a List
control. The following example code adds a handler for a <samp class="codeph">change</samp> event
to the List control. Flex broadcasts a <samp class="codeph">mx.ListEvent.CHANGE</samp> event
when the value of the control changes due to user interaction. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ListChangeEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.Event;
public function changeEvt(event:Event):void {
forChange.text=event.currentTarget.selectedItem.label + " " +
event.currentTarget.selectedIndex;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:List width="35" change="changeEvt(event)"&gt;
&lt;fx:Object label="AL" data="Montgomery"/&gt;
&lt;fx:Object label="AK" data="Juneau"/&gt;
&lt;fx:Object label="AR" data="Little Rock"/&gt;
&lt;/mx:List&gt;
&lt;mx:TextArea id="forChange" width="150"/&gt;
&lt;/s:Application&gt;</pre>
<p>
In this example,
you use two properties of the List control, <samp class="codeph">selectedItem</samp> and <samp class="codeph">selectedIndex</samp>,
in the event handler. Every <samp class="codeph">change</samp> event updates
the TextArea control with the label of the selected item and the
item’s index in the control. </p>
<p>The <samp class="codeph">target</samp> property of the object passed to
the event handler contains a reference to the List control. You
can reference any control property by using the event’s <samp class="codeph">currentTarget</samp> property.
The <samp class="codeph">currentTarget.selectedItem</samp> field contains a
copy of the selected item. If you populate the List control with
an Array of Strings, the <samp class="codeph">currentTarget.selectedItem</samp> field
contains a String. If you populate it with an Array of Objects,
the <samp class="codeph">currentTarget.selectedItem</samp> field contains the
Object that corresponds to the selected item, so, in this case, <samp class="codeph">currentTarget.selectedItem.label</samp> refers
to the selected item’s label field.</p>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-8000_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Using a label function</h4>
<div>
<p>You can pass a label function to the List control to provide
logic that determines the text that appears in the control. The
label function must have the following signature:</p>
<pre class="codeblock"> <em>labelFunction</em>(<em>item</em>:Object):String</pre>
<p>The <samp class="codeph">
<em>item</em>
</samp> parameter passed in by the Label
control contains the list item object. The function must return
the string to display in the List control.</p>
<div class="note"><span class="notetitle">Note:</span> Most subclasses of <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/listClasses/ListBase.html" target="_blank">ListBase</a> also
take a <samp class="codeph">labelFunction</samp> property with the signature
described above. For the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DataGrid.html" target="_blank">DataGrid</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/dataGridClasses/DataGridColumn.html" target="_blank">DataGridColumn</a> controls,
the method signature is <samp class="codeph">labelFunction</samp>
<samp class="codeph">
<em>(</em>
</samp>
<samp class="codeph">item</samp>
<samp class="codeph">
<em>:Object, dataField:DataGridColumn):String</em>
</samp>,
where <samp class="codeph">item</samp> contains the DataGrid item object, and <samp class="codeph">dataField</samp> specifies
the DataGrid column.</div>
<p>
The following example uses a function
to combine the values of the <samp class="codeph">label</samp> and <samp class="codeph">data</samp> fields
for each item for display in the List control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ListLabelFunction.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx" &gt;
&lt;fx:Script&gt;
&lt;![CDATA[
public function myLabelFunc(item:Object):String {
return item.data + ", " + item.label;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;mx:ArrayList id="myDP"&gt;
&lt;mx:source&gt;
&lt;fx:Object label="AL" data="Montgomery"/&gt;
&lt;fx:Object label="AK" data="Juneau"/&gt;
&lt;fx:Object label="AR" data="Little Rock"/&gt;
&lt;/mx:source&gt;
&lt;/mx:ArrayList&gt;
&lt;/fx:Declarations&gt;
&lt;mx:List dataProvider="{myDP}" labelFunction="myLabelFunc"/&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> This example uses an<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayList.html" target="_blank"> ArrayList</a> object
as the data provider. You should always use a list or collection
as the data provider when the data can change at run time. For more
information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7fff_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Displaying DataTips</h4>
<div>
<p>
DataTips are similar
to ToolTips, but display text when the mouse pointer hovers over
a row in a List control. Text in a List control that is longer than
the control width is clipped on the right side (or requires scrolling,
if the control has scroll bars). DataTips can solve that problem
by displaying all of the text, including the clipped text, when
the mouse pointer hovers over a cell. If you enable data tips, they
only appear for fields where the data is clipped. To display DataTips,
set the <samp class="codeph">showDataTips</samp> property of a List control
to <samp class="codeph">true</samp>.</p>
<div class="note"><span class="notetitle">Note:</span> To use DataTips with a DataGrid control, you
must set the <samp class="codeph">showDataTips</samp> property on the individual
DataGridColumns of the DataGrid.</div>
<p>The default behavior of the <samp class="codeph">showDataTips</samp> property
is to display the label text. However, you can use the <samp class="codeph">dataTipField</samp> and <samp class="codeph">dataTipFunction</samp> properties
to determine what is displayed in the DataTip. The <samp class="codeph">dataTipField</samp> property
behaves like the <samp class="codeph">labelField</samp> property; it specifies
the name of the field in the data provider to use as the DataTip
for cells in the column. The <samp class="codeph">dataTipFunction</samp> property
behaves like the <samp class="codeph">labelFunction</samp> property; it specifies
the DataTip string to display for list items.</p>
<p>
The
following example sets the <samp class="codeph">showDataTips</samp> property
for a List control:</p>
<pre class="codeblock"> &lt;mx:List id="myList" dataProvider="{myDP}" width="220" height="200" showDataTips="true"/&gt;</pre>
<p>This example creates the following List control: </p>
<div class="figborder">
<img src="images/dpc_datatip.png" alt="List control with a tool tip"/>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffe_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">Displaying ScrollTips </h4>
<div>
<p>
You
use ScrollTips to give users context about where they are in a list
as they scroll through the list. The tips appear only when you scroll;
they don’t appear if you only hover the mouse over the scroll bar.
ScrollTips are useful when live scrolling is disabled (the <samp class="codeph">liveScrolling</samp> property
is false) so scrolling does not occur until you release the scroll
thumb. The default value of the <samp class="codeph">showScrollTips</samp> property
is <samp class="codeph">false</samp>.</p>
<p>The default behavior of the <samp class="codeph">showScrollTips</samp> property
is to display the index number of the top visible item. You can
use the <samp class="codeph">scrollTipFunction</samp> property to determine
what is displayed in the ScrollTip. The <samp class="codeph">scrollTipFunction</samp> property
behaves like the <samp class="codeph">labelFunction</samp> property; it specifies
the ScrollTip string to display for list items. You should avoid
going to the server to fill in a ScrollTip.</p>
<p>
The
following example sets the <samp class="codeph">showScrollTips</samp> and <samp class="codeph">scrollTipFunction</samp> properties
of a HorizontalList control, which shares many of the same properties
and methods as the standard List control; for more information about
the HorizontalList control, see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d97_verapache">MX
HorizontalList control</a>. The <samp class="codeph">scrollTipFunction</samp> property
specifies a function that gets the value of the <samp class="codeph">description</samp> property
of the current list item.</p>
<pre class="codeblock"> &lt;mx:HorizontalList id="list" dataProvider="{album.photo}" width="100%"
  itemRenderer="Thumbnail" columnWidth="108" height="100"
  <strong>selectionColor="#FFCC00" liveScrolling="false" showScrollTips="true"</strong>
  <strong>scrollTipFunction="scrollTipFunc"</strong>
  change="currentPhoto=album.photo[list.selectedIndex]"/&gt;</pre>
<p>This code produces the following HorizontalList control: </p>
<div class="figborder">
<img src="images/dpc_scrolltip.png" alt="HorizontalList control"/>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffd_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffd_verapache"><!-- --></a>
<h4 class="topictitle4">Vertically aligning text in List
control rows</h4>
<div>
<p>You can use the <samp class="codeph">verticalAlign</samp> style to
vertically align text at the top, middle, or bottom of a List row.
The default value is <samp class="codeph">top</samp>. You can also specify
a value of <samp class="codeph">middle</samp> or <samp class="codeph">bottom</samp>.</p>
<p>
The following
example sets the <samp class="codeph">verticalAlign</samp> property for a List
control to <samp class="codeph">bottom</samp>:</p>
<pre class="codeblock"> &lt;mx:List id="myList" dataProvider="{myDP}"
width="220" height="200"
verticalAlign="bottom"/&gt;</pre>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffc_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffc_verapache"><!-- --></a>
<h4 class="topictitle4">Setting variable row height and
wrapping List text</h4>
<div>
<p>You can use the <samp class="codeph">variableRowHeight</samp> property
to make the height of List control rows variable based on their
content. The default value is <samp class="codeph">false</samp>. If you set
the <samp class="codeph">variableRowHeight</samp> property to <samp class="codeph">true</samp>,
the <samp class="codeph">rowHeight</samp> property is ignored and the <samp class="codeph">rowCount</samp> property
is read-only.</p>
<p>
The following
example sets the <samp class="codeph">variableRowHeight</samp> property for
a List control to <samp class="codeph">true</samp>:</p>
<pre class="codeblock"> &lt;mx:List id="myList" dataProvider="{myDP}"
width="220" height="200"
variableRowHeight="true"/&gt;</pre>
<p>You can use the <samp class="codeph">wordWrap</samp> property in combination
with the <samp class="codeph">variableRowHeight</samp> property to wrap text
to multiple lines when it exceeds the width of a List row. </p>
<p>
The following
example sets the <samp class="codeph">wordWrap</samp> and <samp class="codeph">variableRowHeight</samp> properties
to <samp class="codeph">true</samp>:</p>
<pre class="codeblock"> &lt;mx:List id="myList" dataProvider="{myDP}"
width="220" height="200"
variableRowHeight="true" wordWrap="true"/&gt;</pre>
<p>This code produces the following List control:</p>
<div class="figborder">
<img src="images/dpc_list_example_vrh.png" alt="List control with variable row height"/>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffb_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffb_verapache"><!-- --></a>
<h4 class="topictitle4">Alternating row colors in a List
control</h4>
<div>
<p>
You
can use the <samp class="codeph">alternatingItemColors</samp> style property
to specify an Array that defines the color of each row in the List
control. The Array must contain two or more colors. After using
all the entries in the Array, the List control repeats the color
scheme.</p>
<p>The following example defines an Array with two entries, #66FFFF
for light blue and #33CCCC for a blue-gray. Therefore, the rows
of the List control alternate between these two colors. If you specify
a three-color array, the rows alternate among the three colors,
and so on.</p>
<pre class="codeblock"> &lt;mx:List alternatingItemColors="[#66FFFF, #33CCCC]".../&gt; </pre>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffa_verapache"><a name="WS19f279b149e7481c32a1a3e512c12af2ad0-7ffa_verapache"><!-- --></a>
<h4 class="topictitle4">Using a custom item renderer</h4>
<div>
<p>An item renderer is the object that displays a List control’s
data items. The simplest way to use a custom item renderer is to
specify an MXML component as the value of the <samp class="codeph">itemRenderer</samp> property.
When you use an MXML component as a item renderer, it can contain
multiple levels of containers and controls. You can also use an
ActionScript class as a custom item renderer. For detailed information
on custom item renderers, see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>
</p>
<p>
The following
example sets the <samp class="codeph">itemRenderer</samp> property to an MXML component
named FancyCellRenderer. It also sets the <samp class="codeph">variableRowHeight</samp> property
to <samp class="codeph">true</samp> because the MXML component exceeds the
default row height:</p>
<pre class="codeblock"> &lt;mx:List id="myList1" dataProvider="{myDP}"
width="220" height="200"
itemRenderer="FancyItemRenderer"
variableRowHeight="true"/&gt;</pre>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c2591359a12c12834bb9-8000_verapache"><a name="WS19f279b149e7481c2591359a12c12834bb9-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Specifying an icon to the List
control</h4>
<div>
<p>
You
can specify an icon to display with each List item, as the following
example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ListIcon.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
[Embed(source="assets/radioIcon.jpg")]
public var iconSymbol1:Class;
[Embed(source="assets/topIcon.jpg")]
public var iconSymbol2:Class;
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:List iconField="myIcon"&gt;
&lt;mx:dataProvider&gt;
&lt;fx:Array&gt;
&lt;fx:Object label="AL" data="Montgomery" myIcon="iconSymbol1"/&gt;
&lt;fx:Object label="AK" data="Juneau" myIcon="iconSymbol2"/&gt;
&lt;fx:Object label="AR" data="Little Rock" myIcon="iconSymbol1"/&gt;
&lt;/fx:Array&gt;
&lt;/mx:dataProvider&gt;
&lt;/mx:List&gt;
&lt;/s:Application&gt;</pre>
<p>
In this
example, you use the <samp class="codeph">iconField</samp> property to specify
the field of each item containing the icon. You use the <samp class="codeph">Embed</samp> metadata
to import the icons, and then reference them in the List control
definition. </p>
<p>You can also use the <samp class="codeph">iconFunction</samp> property to
specify a function that determines the icon, similar to the way
that you can use the <samp class="codeph">labelFunction</samp> property to
specify a function that determines the label text. The icon function must
have the following signature:</p>
<pre class="codeblock"> <em>iconFunction</em>(<em>item</em>:Object):Class</pre>
<p>The <samp class="codeph">
<em>item</em>
</samp> parameter passed in by the List
control contains the list item object. The function must return
the icon class to display in the List control.</p>
<p>The following example shows a List control that uses the <samp class="codeph">iconFunction </samp>property
to determine the icon to display for each item in the list:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ListIconFunction.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
// Embed icons.
[Embed(source="assets/radioIcon.jpg")]
public var pavementSymbol:Class;
[Embed(source="assets/topIcon.jpg")]
public var normalSymbol:Class;
// Define data provider.
private var myDP: Array;
private function initList():void {
myDP = [
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavarotti', Album:'Twilight', Price:11.99},
{Artist:'Other', Album:'Other', Price:5.99}];
list1.dataProvider = myDP;
}
// Determine icon based on artist. Pavement gets a special icon.
private function myiconfunction(item:Object):Class {
var type:String = item.Artist;
if (type == "Pavement") {
return pavementSymbol;
}
return normalSymbol;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:VBox &gt;
&lt;mx:List id="list1"
initialize="initList();"
labelField="Artist"
iconFunction="myiconfunction" /&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd2_verapache"><!-- --></a>
<h3 class="topictitle3">List control user interaction</h3>
<div>
<p>
The
user clicks individual list items to select them, and holds down
the Control and Shift keys while clicking to select multiple items.
(You must set the <samp class="codeph">allowMultipleSelection</samp> property
to <samp class="codeph">true</samp> to allow multiple selection.)</p>
<p>All mouse or keyboard selections broadcast a <samp class="codeph">change</samp> event.
For mouse interactions, the List control broadcasts this event when
the mouse button is released. </p>
<p>If you set the <samp class="codeph">allowDragSelection</samp> property to <samp class="codeph">true</samp>,
the control scrolls up or down when the user presses the mouse button
over the one or more rows, holds the mouse button down, drags the
mouse outside the control, and then moves the mouse up and down.</p>
<p>A List control shows the number of records that fit in the display.
Paging down through the data displayed by a 10-line List control
shows records 0-10, 9-18, 18-27, and so on, with one line overlapping
from one page to the next.</p>
<p>
The
List control has the following keyboard navigation features:</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="d183656e945">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e951">
<p>Action</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection up one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection down one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection up one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection down one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection to the top of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Moves selection to the bottom of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Alphanumeric keys</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Jumps to the next item with a label that
begins with the character typed.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Control</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Toggle key. Allows for multiple (noncontiguous)
selection and deselection. Works with key presses, click selection,
and drag selection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e945 ">
<p>Shift</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e951 ">
<p>Contiguous selection key. Allows for contiguous
selections. Works with key presses, click selection, and drag selection.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d97_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d97_verapache"><!-- --></a>
<h2 class="topictitle2">MX HorizontalList control</h2>
<div>
<p>
The
HorizontalList control displays a horizontal list of items. The
HorizontalList control is particularly useful in combination with
a custom item renderer for displaying a list of images and other
data. For more information about custom item renderers, see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
<p>For complete reference information, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/HorizontalList.html" target="_blank">HorizontalList</a> in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc6_verapache"><!-- --></a>
<h3 class="topictitle3">About HorizontaList controls</h3>
<div>
<p>The contents of a HorizontalList control can look very
similar to the contents of an <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/containers/HBox.html" target="_blank">HBox</a> container
in which a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/Repeater.html" target="_blank">Repeater</a> object
repeats components. However, performance of a HorizontalList control
can be better than the combination of an HBox container and a Repeater
object because the HorizontalList control only instantiates the
objects that fit in its display area. Scrolling in a HorizontalList
can be slower than it is when using a Repeater object. For more
information about the Repeater object, see <a href="flx_repeater_rp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b42_verapache">Dynamically
repeating controls and containers </a>.</p>
<p>The HorizontalList control always displays items from left to
right. The control usually contains a horizontal scroll bar, which
lets users access all items in the list. An optional vertical scroll
bar lets users view items when the full height of the list items
is unlikely to fit. The user can select one or more items from the
list, depending on the value of the <samp class="codeph">allowMultipleSelection</samp> property. </p>
<p>The following image shows a HorizontalList control:</p>
<div class="figborder">
<img src="images/cr_horizontallist2.png" alt="HorizontalList control"/>
</div>
<p>For complete reference information, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/HorizontalList.html" target="_blank">HorizontalList</a> in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd0_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a HorizontalList control</h3>
<div>
<p>You use the <samp class="codeph">&lt;mx:HorizontalList&gt;</samp> tag
to define a HorizontalList control. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block.</p>
<p>The HorizontalList control shares many properties and methods
with the List control; see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d90_verapache">MX
List control</a> for information on how to use several of these
shared properties. The HorizontalList control uses a list-based
data provider. For more information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>You specify the data for a HorizontalList control by using the <samp class="codeph">dataProvider</samp> property
of the <samp class="codeph">&lt;mx:HorizontalList&gt;</samp> tag, as the following
example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/HListDataProvider.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
width="450"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.*;
import mx.controls.Image;
private var catalog:ArrayList;
private static var cat:Array = [
"../assets/Flex_6820.gif", "../assets/Flex_3595.gif",
"../assets/Flex_3650.gif", "../assets/Flex_6010.gif"
];
/* Initialize the HorizontalList control by setting its dataProvider
property to an ArrayList containing the items parameter. */
private function initCatalog(items:Array):void {
catalog = new ArrayList(items);
myList.dataProvider = catalog;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- A four-column HorizontalList. The itemRenderer is a Flex Image control.
When the control is created, pass the cat array to the initialization routine. --&gt;
&lt;mx:HorizontalList id="myList"
columnWidth="100"
rowHeight="100"
columnCount="4"
itemRenderer="mx.controls.Image"
creationComplete="initCatalog(cat);"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you use the <samp class="codeph">creationComplete</samp> event
to populate the data provider with an ArrayList of image files,
and the <samp class="codeph">itemRenderer</samp> property to specify the Image
control as the item renderer. (Note that you use the full package
name of the control in the assignment because the code does not import
the mx.controls package.) The HorizontalList control then displays
the four images specified by the data provider. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ffa_verapache"><!-- --></a>
<h3 class="topictitle3">HorizontalList control user interaction </h3>
<div>
<p>
The
user clicks individual list items to select them, and holds down
the Control and Shift keys while clicking to select multiple items.</p>
<p>All mouse or keyboard selections broadcast a <samp class="codeph">change</samp> event.
For mouse interactions, the HorizontalList control broadcasts this
event when the mouse button is released. When the user drags the
mouse over the items and then outside the control, the control scrolls
up or down.</p>
<p>A HorizontalList control shows the number of records that fit
in the display. Paging through a four list shows records 0-4, 5-8,
and so on, with no overlap from one page to the next. </p>
</div>
<div class="nested3" id="WS19f279b149e7481c-65668f0612c12b89f91-8000_verapache"><a name="WS19f279b149e7481c-65668f0612c12b89f91-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Keyboard navigation</h4>
<div>
<p>
The
HorizontalList control has the following keyboard navigation features:</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="d183656e1311">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e1317">
<p>Action</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection to the left one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Left Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection to the left one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection right one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection to the right one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection to the beginning of the
list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Moves selection to the end of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Control</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Toggle key. Allows for multiple (noncontiguous)
selection and deselection when the <samp class="codeph">allowMultipleSelection</samp> property
is set to <samp class="codeph">true</samp>. Works with key presses, click selection,
and drag selection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1311 ">
<p>Shift</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1317 ">
<p>Contiguous selection key. Allows for contiguous
selections when <samp class="codeph">allowMultipleSelection</samp> is set to <samp class="codeph">true</samp>.
Works with key presses, click selection, and drag selection.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d82_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d82_verapache"><!-- --></a>
<h2 class="topictitle2">MX TileList control</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TileList.html" target="_blank">TileList</a> control
displays a tiled list of items. The items are tiled in vertical columns
or horizontal rows. The TileList control is particularly useful
in combination with a custom item renderer for displaying a list
of images and other data. The default item renderer for the TileList
control is <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/listClasses/TileListItemRenderer.html" target="_blank">TileListItemRenderer</a>,
which, by default, displays text of the data provider’s label field
and any icon. For more information about custom item renderers,
see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
<p>Flex also includes the Spark Tile layout. When possible, it’s
best that you use the Spark Tile layout with the Spark List control.
For more information, see <a href="flx_spark_dpcontrols_sdp.html#WSc2368ca491e3ff923c946c5112135c8ee9e-7fff_verapache">Spark
List control</a>.</p>
<p>For complete reference information, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc7_verapache"><!-- --></a>
<h3 class="topictitle3">About the TileList control</h3>
<div>
<p>The contents of a TileList control can look very similar
to the contents of a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/containers/Tile.html" target="_blank">Tile</a> container
in which a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/core/Repeater.html" target="_blank">Repeater</a> object
repeats components. However, performance of a TileList control can
be better than the combination of a Tile container and a Repeater
object because the TileList control only instantiates the objects that
fit in its display area. Scrolling in a TileList can be slower than
it is when using a Repeater object. For more information about the
Repeater object, see <a href="flx_repeater_rp.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b42_verapache">Dynamically
repeating controls and containers </a>.</p>
<p>The TileList control displays a number of items laid out in equally
sized tiles. It often contains a scroll bar on one of its axes to
access all items in the list depending on the direction orientation
of the list. The user can select one or more items from the list
depending on the value of the <samp class="codeph">allowMultipleSelection</samp> property.</p>
<p>The TileList control lays out its children in one or more vertical
columns or horizontal rows, starting new rows or columns as necessary.
The <samp class="codeph">direction</samp> property determines the primary direction
of the layout. The valid values for the <samp class="codeph">direction</samp> property
are and <samp class="codeph">horizontal</samp> (default) and <samp class="codeph">vertical</samp> for
a layout. In a <samp class="codeph">horizontal</samp> layout the tiles are
filled in row by row with each row filling the available space in
the control. If there are more tiles than fit in the display area,
the horizontal control has a vertical scroll. In a <samp class="codeph">vertical</samp> layout, the
tiles are filled in column by column in the available vertical space,
and the control may have a horizontal scroll bar.</p>
<p>The following image shows a TileList control:</p>
<div class="figborder">
<img src="images/dpc_tilelist2.png" alt="TileList control"/>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc8_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a TileList control</h3>
<div>
<p>You use the <samp class="codeph">&lt;mx:TileList&gt;</samp> tag to
define a TileList control. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block.</p>
<p>The TileList control shares many properties and methods with
the List control; see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d90_verapache">MX
List control</a> for information on how to use several of these
shared properties. The TileList control uses a list-based data provider.
For more information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>You specify the data for a TileList control by using the <samp class="codeph">dataProvider</samp> property of
the <samp class="codeph">&lt;mx:TileList&gt;</samp> tag, as the following example
shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TileListDataProvider.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
initialize="initData();" &gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.Button;
import mx.collections.*;
private var listArray:Array=[
{label: "item0", data: 0},{label: "item1", data: 1},
{label: "item2", data: 2},{label: "item3", data: 3},
{label: "item4", data: 4},{label: "item5", data: 5},
{label: "item6", data: 6},{label: "item7", data: 7},
{label: "item8", data: 8}];
[Bindable]
public var TileListdp:ArrayList;
private function initData():void {
TileListdp = new ArrayList(listArray);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:TileList dataProvider="{TileListdp}"
itemRenderer="mx.controls.Button"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you populate the data provider with an ArrayList
that contains an Array of strings defining labels and data values.
You then use the <samp class="codeph">itemRenderer</samp> property to specify
a Button control as the item renderer. The Button controls display
the data provider label values. The TileList control displays nine
Button controls with the specified labels.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcc_verapache"><!-- --></a>
<h3 class="topictitle3">TileList control user interaction</h3>
<div>
<p>
The
user clicks individual list items to select them, and holds down
the Control and Shift keys while clicking to select multiple items.</p>
<p>All mouse or keyboard selections broadcast a <samp class="codeph">change</samp> event.
For mouse interactions, the TileList control broadcasts this event
when the mouse button is released. When the user drags the mouse
over the items and then outside the control, the control scrolls
up or down.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcc_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcc_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fc9_verapache"><!-- --></a><h4 class="sectiontitle">Keyboard
navigation</h4>
<p>
The
TileList control has the following keyboard navigation features:</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="d183656e1680">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e1686">
<p>Action</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection up one item. If the control
direction is <samp class="codeph">vertical</samp>, and the current item is
at the top of a column, moves to the last item in the previous column;
motion stops at the first item in the first column.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection down one item. If the control
direction is <samp class="codeph">vertical</samp>, and the current item is
at the bottom of a column, moves to the first item in the next column;
motion stops at the last item in the last column.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection to the right one item. If
the control direction is <samp class="codeph">horizontal</samp>, and the current
item is at the end of a row, moves to the first item in the next
row; motion stops at the last item in the last column.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Left Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection to the left one item. If
the control direction is <samp class="codeph">horizontal</samp>, and the current
item is at the beginning of a row, moves to the last item in the
previous row; motion stops at the first item in the first row.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection up one page. For a single-page
control, moves the selection to the beginning of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection down one page. For a single-page
control, moves the selection to the end of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection to the beginning of the
list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Moves selection to the end of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Control</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Toggle key. Allows for multiple (noncontiguous)
selection and deselection when <samp class="codeph">allowMultipleSelection</samp> is
set to <samp class="codeph">true</samp>. Works with key presses, click selection,
and drag selection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1680 ">
<p>Shift</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e1686 ">
<p>Contiguous selection key. Allows for contiguous
selections when <samp class="codeph">allowMultipleSelection</samp> is set to <samp class="codeph">true</samp>.
Works with key presses, click selection, and drag selection.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9c_verapache"><!-- --></a>
<h2 class="topictitle2">MX ComboBox control</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox</a> control
is a drop-down list from which the user can select a single value.
Its functionality is very similar to that of the SELECT form element
in HTML. </p>
<p>Flex also includes the Spark ComboBox control. When possible,
it’s best that you use the Spark ComboBox control. For more information,
see <a href="flx_spark_dpcontrols_sdp.html#WS70f0d54f063b9b081aac8d1d1247252e4a0-8000_verapache">Spark
ComboBox control</a>.</p>
<p>For complete reference information, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fff_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">About the ComboBox control</h3>
<div>
<p>The following image shows a ComboBox control:</p>
<div class="figborder">
<img src="images/dpc_combobox_example.png" alt="ComboBox control"/>
</div>
<p>
In
its editable state, the user can type text directly into the top
of the list, or select one of the preset values from the list. In
its noneditable state, as the user types a letter, the drop-down
list opens and scrolls to the value that most closely matches the
one being entered; matching is only performed on the first letter that
the user types. </p>
<p>If the drop-down list hits the lower boundary of the application,
it opens upward. If a list item is too long to fit in the horizontal
display area, it is truncated to fit. If there are too many items
to display in the drop-down list, a vertical scroll bar appears.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcb_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a ComboBox control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:ComboBox&gt;</samp> tag to define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox</a> control
in MXML. Specify an <samp class="codeph">id</samp> value if you intend to refer
to a component elsewhere in your MXML, either in another tag or
in an ActionScript block.</p>
<p>The ComboBox control uses a list-based data provider. For more
information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>You specify the data for the ComboBox control by using the <samp class="codeph">dataProvider</samp> property
of the <samp class="codeph">&lt;mx:ComboBox&gt;</samp> tag. The data provider
should be a list or collection; the standard list implementation
is the ArrayList class. The standard collection implementations
are the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayList.html" target="_blank">ArrayCollection</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/XMLListCollection.html" target="_blank">XMLListCollection</a> classes,
for working with Array-based and XML-based data, respectively. You
can also use a raw data object, such as an Array object, as a data
provider; however, it is always better to specify a list or collection
explicitly for data that could change. For more information on data
providers and collections see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>In a simple case for creating a ComboBox control, you specify
the property by using an <samp class="codeph">dataProvider</samp> child tag,
and use an <samp class="codeph">&lt;mx:ArrayList&gt;</samp> tag to define the
entries as an ArrayList whose source is an Array of Strings, as
the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ComboBoxSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:ComboBox&gt;
&lt;mx:ArrayList&gt;
&lt;fx:String&gt;AK&lt;/fx:String&gt;
&lt;fx:String&gt;AL&lt;/fx:String&gt;
&lt;fx:String&gt;AR&lt;/fx:String&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:ComboBox&gt;
&lt;/s:Application&gt;</pre>
<p>This example shows how you can take advantages of MXML defaults.
You do not have to use an <samp class="codeph">dataProvider</samp> tag, because <samp class="codeph">dataProvider</samp> is
the default property of the ComboBox control. Similarly, you do
not have to use an <samp class="codeph">&lt;mx:source&gt;</samp> tag inside
the <samp class="codeph">&lt;mx:ArrayList&gt;</samp> tag because <samp class="codeph">source</samp> is
the default property of the ArrayList class. Finally, you do not
have to specify an <samp class="codeph">&lt;fx:Array&gt;</samp> tag for the
source array.</p>
<p>The data provider can also contain objects with multiple fields,
as in the following example:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ComboBoxMultiple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:ComboBox&gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object label="AL" data="Montgomery"/&gt;
&lt;fx:Object label="AK" data="Juneau"/&gt;
&lt;fx:Object label="AR" data="Little Rock"/&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:ComboBox&gt;
&lt;/s:Application&gt;</pre>
<p>If the data source is an array of strings, as in the first example,
the ComboBox displays strings as the items in the drop-down list.
If the data source consists of objects, the ComboBox, by default,
uses the contents of the label field. You can, however, override
this behavior, as described in <a href="flx_dpcontrols_dpc.html#WS19f279b149e7481c2954ae7a12c1290681b-7fff_verapache">Specifying
ComboBox labels</a>.</p>
<p>The index of items in the ComboBox control is zero-based, which
means that values are 0, 1, 2, ... , <em>n</em> - 1, where <em>n</em> is
the total number of items. The value of the item is its label text. </p>
</div>
<div class="nested3" id="WS19f279b149e7481c2954ae7a12c1290681b-8000_verapache"><a name="WS19f279b149e7481c2954ae7a12c1290681b-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Using events with ComboBox controls</h4>
<div>
<p>You typically use events to handle user interaction with
a ComboBox control. </p>
<p>
The
ComboBox control broadcasts a <samp class="codeph">change</samp> event (flash.events.Event
class with a <samp class="codeph">type</samp> property value of <samp class="codeph">flash.events.Event.CHANGE</samp>)
when the value of the control’s <samp class="codeph">selectedIndex</samp> or <samp class="codeph">selectedItem</samp> property
changes due to the following user actions:</p>
<ul>
<li>
<p>If the user closes the drop-down list by using a mouse
click, Enter key, or Control+Up key, and the selected item is different
from the previously selected item. </p>
</li>
<li>
<p>If the drop-down list is currently closed, and the user presses
the Up, Down, Page Up, or Page Down key to select a new item. </p>
</li>
<li>
<p>If the ComboBox control is editable, and the user types into
the control, Flex broadcasts a <samp class="codeph">change</samp> event each
time the text field of the control changes. </p>
</li>
</ul>
<p>
The
ComboBox control broadcasts an mx.events.DropdownEvent with a type <samp class="codeph">mx.events.DropdownEvent.OPEN</samp> (open<samp class="codeph">)</samp> and <samp class="codeph">mx.events.DropdownEvent.CLOSE</samp> (close)
when the ComboBox control opens and closes. For detailed information
on these and other ComboBox events, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox </a>in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. </p>
<p>The following example displays information from ComboBox events:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ComboBoxEvent.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.Event;
import mx.events.DropdownEvent;
// Display the type of event for open and close events.
private function dropEvt(event:DropdownEvent):void {
forChange.text+=event.type + "\n";
}
// Display a selected item's label field and index for change events.
private function changeEvt(event:Event):void {
forChange.text+=event.currentTarget.selectedItem.label + " " +
event.currentTarget.selectedIndex + "\n";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:ComboBox open="dropEvt(event)" close="dropEvt(event)"
change="changeEvt(event)" &gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object label="AL" data="Montgomery"/&gt;
&lt;fx:Object label="AK" data="Juneau"/&gt;
&lt;fx:Object label="AR" data="Little Rock"/&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:ComboBox&gt;
&lt;mx:TextArea id="forChange" width="150" height="150"/&gt;
&lt;/s:Application&gt;</pre>
<p>If you populate the ComboBox control with an Array of Strings,
the <samp class="codeph">currentTarget.selectedItem</samp> field contains a
String. If you populate it with an Array of Objects, the <samp class="codeph">currentTarget.selectedItem</samp> field
contains the Object that corresponds to the selected item, so, in
this case, <samp class="codeph">currentTarget.selectedItem.label</samp> refers
to the selected item object’s label field. </p>
<p>In this example, you use two properties of the ComboBox control, <samp class="codeph">selectedItem</samp> and <samp class="codeph">selectedIndex</samp>,
in the event handlers. Every <samp class="codeph">change</samp> event updates
the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a> control
with the label of the selected item and the item’s index in the
control, and every <samp class="codeph">open</samp> or <samp class="codeph">close</samp> event
appends the event type.</p>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c2954ae7a12c1290681b-7fff_verapache"><a name="WS19f279b149e7481c2954ae7a12c1290681b-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Specifying ComboBox labels</h4>
<div>
<p>If the ComboBox data source is an array of strings, the
control displays the string for each item. If the data source is
contains Objects, by default, the ComboBox control expects each
object to contain a property named <samp class="codeph">label</samp> that defines
the text that appears in the ComboBox control for the item. If each
Object does not contain a <samp class="codeph">label</samp> property, you can
use the <samp class="codeph">labelField</samp> property of the ComboBox control
to specify the property name, as the following example shows:</p>
<pre class="codeblock">  &lt;mx:ComboBox open="dropEvt(event)" close="dropEvt(event)"
  change="changeEvt(event)" labelField="state"&gt;
  &lt;mx:ArrayList&gt;
  &lt;fx:Object state="AL" capital="Montgomery"/&gt;
  &lt;fx:Object state="AK" capital="Juneau"/&gt;
  &lt;fx:Object state="AR" capital="Little Rock"/&gt;
  &lt;/mx:ArrayList&gt;
  &lt;/mx:ComboBox&gt;</pre>
<p>To make the event handler in the section <a href="flx_dpcontrols_dpc.html#WS19f279b149e7481c2954ae7a12c1290681b-8000_verapache">Using
events with ComboBox controls</a>display the state ID and capital,
you would modify the <samp class="codeph">change</samp> event handler to use
a property named <samp class="codeph">state</samp>, as the following example
shows: </p>
<pre class="codeblock">  private function changeEvt(event) {
  <strong>forChange.text=event.currentTarget.selectedItem.state + " " + </strong>
  event.currentTarget.selectedItem.capital + " " +
  event.currentTarget.selectedIndex;
  }</pre>
<p>You can also specify the ComboBox labels by using a label function,
as described in <a href="flx_dpcontrols_dpc.html#WS19f279b149e7481c32a1a3e512c12af2ad0-8000_verapache">Using
a label function</a>.</p>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c2954ae7a12c1290681b-7ffe_verapache"><a name="WS19f279b149e7481c2954ae7a12c1290681b-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">Populating a ComboBox control by
using variables and models</h4>
<div>
<p>Flex lets you populate the data provider of a ComboBox
control from an ActionScript variable definition or from a Flex
data model. Each element of the data provider must contain a string
label, and can contain one or more fields with additional data.
The following example populates two ComboBox controls; one from
an ArrayList variable that it populates directly from an Array,
the other from an ArrayList that it populates from an array of items
in an <samp class="codeph">&lt;fx:Model&gt;</samp> tag.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/ComboBoxVariables.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
initialize="initData();"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.*
private var COLOR_ARRAY:Array=
[{label:"Red", data:"#FF0000"},
{label:"Green", data:"#00FF00"},
{label:"Blue", data:"#0000FF"}];
// Declare an ArrayList variable for the colors.
// Make it Bindable so it can be used in bind
// expressions ({colorAL}).
[Bindable]
public var colorAL:ArrayList;
// Initialize colorAL ArrayList variable from the Array.
// Use an initialize event handler to initialize data variables
// that do not rely on components, so that the initial values are
// available when the controls that use them are constructed.
//See the mx:ArrayList tag, below, for a second way to
//initialize an ArrayList.
private function initData():void {
colorAL=new ArrayList(COLOR_ARRAY);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;!-- This example shows two different ways to
structure a Model. --&gt;
&lt;fx:Model id="myDP"&gt;
&lt;obj&gt;
&lt;item label="AL" data="Montgomery"/&gt;
&lt;item&gt;
&lt;label&gt;AK&lt;/label&gt;
&lt;data&gt;Juneau&lt;/data&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;label&gt;AR&lt;/label&gt;
&lt;data&gt;Little Rock&lt;/data&gt;
&lt;/item&gt;
&lt;/obj&gt;
&lt;/fx:Model&gt;
&lt;!-- Create a stateAL ArrayList that uses as its source an Array of
the item elements from the myDP model.
This technique and the declaration and initialization code used for
the colorAL variable are alternative methods of creating and
initializing the ArrayList. --&gt;
&lt;mx:ArrayList id="stateAL" source="{myDP.item}"/&gt;
&lt;/fx:Declarations&gt;
&lt;mx:ComboBox dataProvider="{colorAL}"/&gt;
&lt;mx:ComboBox dataProvider="{stateAL}"/&gt;
&lt;/s:Application&gt;</pre>
<p>This example uses a simple model. However, you can populate the
model from an external data source or define a custom data model
class in ActionScript. For more information on using data models,
see <a href="flx_datamodels_dm.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ff3_verapache">Storing
data</a>. </p>
<p>You can use remote data providers to supply data to your ComboBox
control. For example, when a web service operation returns an Array
of strings, you can use the following format to display each string
as a row of a ComboBox control:</p>
<pre class="codeblock"> &lt;mx:ArrayCollection id=”resultAC”
  source=”mx.utils.ArrayUtil.toArray(service.operation.lastResult);”
 &lt;mx:ComboBox dataProvider="{resultAC}" /&gt;</pre>
<p>In general, you should use an ArrayCollection for web service
operations. An ArrayList is not usually compatible with the results.
For more information on using remote data providers, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b63_verapache">Remote
data in data provider components</a>. </p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db5_verapache"><!-- --></a>
<h3 class="topictitle3">ComboBox control user interaction </h3>
<div>
<p>
A <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox</a> control
can be noneditable or editable, as specified by the Boolean <samp class="codeph">editable</samp> property.
In a noneditable ComboBox control, a user can make a single selection
from a drop-down list. In an editable ComboBox control, the portion
button of the control is a text field that the user can enter text
directly into or can populate by selecting an item from the drop‑down
list. When the user makes a selection in the ComboBox control list,
the label of the selection is copied to the text field at the top
of the ComboBox control.</p>
<p>
When
a ComboBox control (and not the drop-down box) has focus and is editable,
all keystrokes go to the text field and are handled according to
the rules of the TextInput control (see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache">MX
TextInput control</a>), with the exception of the Control+Down
key combination, which opens the drop-down list. When the drop-down
list is open, you can use the Up and Down keys to navigate in the
list and the Enter key to select an item from the list.</p>
<p>When a ComboBox control has focus and is noneditable, alphanumeric keystrokes
move the selection up and down the data provider to the next item with
the same first character and display the label in the text field.
If the drop-down list is open, the visible selection moves to the
selected item. </p>
<p>You can also use the following keys to control a noneditable
ComboBox control when the drop-down list is not open:</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="d183656e2351">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e2357">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Control+Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Opens the drop-down list and gives it focus.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Moves the selection down one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Moves the selection to the bottom of the
collection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Moves the selection to the top of the collection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Displays the item that would be at the end
bottom of the drop-down list. If the current selection is a multiple
of the <samp class="codeph">rowCount</samp> value, displays the item that <samp class="codeph">rowCount</samp> -1
down the list, or the last item. If the current selection is the
last item in the data provider, does nothing.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Displays the item that would be at the top
of the drop-down. If the current selection is a multiple of the <samp class="codeph">rowCount</samp> value,
displays the item that <samp class="codeph">rowCount</samp> -1 up the list,
or the first item. If the current selection is the first item in
the data provider, does nothing.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2351 ">
<p>Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2357 ">
<p>Moves the selection up one item.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>When the drop-down list of a noneditable ComboBox control has
focus, alphanumeric keystrokes move the selection up and down the
drop-down list to the next item with the same first character. You
can also use the following keys to control a drop-down list when
it is open:</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="d183656e2504">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e2510">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Control+Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Closes the drop-down list and returns focus
to the ComboBox control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves the selection down one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves the selection to the bottom of the
collection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Closes the drop-down list and returns focus
to the ComboBox control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Escape</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Closes the drop-down list and returns focus
to the ComboBox control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves the selection to the top of the collection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves to the bottom of the visible list.
If the current selection is at the bottom of the list, moves the current
selection to the top of the displayed list and displays the next <samp class="codeph">rowCount</samp>-1
items, if any. If there current selection is the last item in the
data provider, does nothing.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves to the top of the visible list. If
the current selection is at the top of the list, moves the current selection
to the bottom of the displayed list and displays the previous <samp class="codeph">rowCount</samp>-1
items, if any. If the current selection is the first item in the
data provider, does nothing.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Shift+Tab</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Closes the drop-down list and moves the
focus to the previous object in the DisplayList.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Tab</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Closes the drop-down list and moves the
focus to the next object in the DisplayList.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2504 ">
<p>Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e2510 ">
<p>Moves the selection up one item.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d9a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d9a_verapache"><!-- --></a>
<h2 class="topictitle2">MX DataGrid control</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DataGrid.html" target="_blank">DataGrid</a> control
is a list that can display more than one column of data. It is a
formatted table of data that lets you set editable table cells,
and is the foundation of many data-driven applications. </p>
<p>For information on the following topics, which are often important
for creating advanced data grid controls, see:</p>
<ul>
<li>
<p>How to format the information in each DataGrid cell and
control how users enter data in the cells; see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
</li>
<li>
<p>How to drag objects to and from the data grid; see <a href="flx_dragdrop_dd.html#WS2db454920e96a9e51e63e3d11c0bf69084-7c0a_verapache">Drag
and drop </a>.</p>
</li>
</ul>
<p>Flex also includes the Spark DataGrid control. When possible,
it’s best that you use the Spark DataGrid control. For more information,
see <a href="flx_spark_datagrid_sdg.html#WSd867f5c5d869105e43810e1112c55502365-8000_verapache">Spark
DataGrid and Grid controls</a>.</p>
<p>
For complete
reference information, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff8_verapache"><!-- --></a>
<h3 class="topictitle3">About the MX DataGrid control</h3>
<div>
<p>The DataGrid control provides the following features:</p>
<ul>
<li>
<p>Resizable, sortable, and customizable column layouts,
including hidable columns</p>
</li>
<li>
<p>Optional customizable column and row headers, including optionally wrapping
header text</p>
</li>
<li>
<p>Columns that the user can resize and reorder at run time </p>
</li>
<li>
<p>Selection events </p>
</li>
<li>
<p>Ability to use a custom item renderer for any column</p>
</li>
<li>
<p>Support for paging through data</p>
</li>
<li>
<p>Locked rows and columns that do not scroll</p>
</li>
</ul>
<p>The following image shows a DataGrid control:</p>
<div class="figborder">
<img src="images/dpc_datagrid_example.png" alt="DataGrid control"/>
</div>
<p>Rows are responsible for rendering items. Each row is laid out
vertically below the previous one. Columns are responsible for maintaining
the state of each visual column; columns control width, color, and
size. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX DataGrid control</h3>
<div>
<p>
You
use the <samp class="codeph">&lt;mx:DataGrid&gt;</samp> tag to define a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/DataGrid.html" target="_blank">DataGrid</a> control
in MXML. Specify an <samp class="codeph">id</samp> value if you intend to refer
to a component elsewhere in your MXML, either in another tag or
in an ActionScript block. </p>
<p>The DataGrid control uses a list-based data provider. For more
information, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb8_verapache">Data
providers and collections</a>.</p>
<p>
You
specify the data for the DataGrid control by using the <samp class="codeph">dataProvider</samp> property.
You can specify data in several different ways. In the simplest
case for creating a DataGrid control, you use the <samp class="codeph">dataProvider</samp> property
subtag with <samp class="codeph">&lt;mx:ArrayList&gt;</samp>, and <samp class="codeph">&lt;fx:Object&gt;</samp> tags
to define the entries as an ArrayList of Objects. Each Object defines
a row of the DataGrid control, and properties of the Object define
the column entries for the row, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:DataGrid&gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object&gt;
&lt;fx:Artist&gt;Pavement&lt;/fx:Artist&gt;
&lt;fx:Price&gt;11.99&lt;/fx:Price&gt;
&lt;fx:Album&gt;Slanted and Enchanted&lt;/fx:Album&gt;
&lt;/fx:Object&gt;
&lt;fx:Object&gt;
&lt;fx:Artist&gt;Pavement&lt;/fx:Artist&gt;
&lt;fx:Album&gt;Brighten the Corners&lt;/fx:Album&gt;
&lt;fx:Price&gt;11.99&lt;/fx:Price&gt;
&lt;/fx:Object&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:DataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>This example shows how you can take advantages of MXML defaults.
You do not have to use an <samp class="codeph">dataProvider</samp> tag, because <samp class="codeph">dataProvider</samp> is
the default property of the DataGrid control. Similarly, you do
not have to use an <samp class="codeph">&lt;mx:source&gt;</samp> tag inside
the <samp class="codeph">&lt;mx:ArrayList&gt;</samp> tag because <samp class="codeph">source</samp> is
the default property of the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayList.html" target="_blank">ArrayList</a> class.
Finally, you do not have to specify an <samp class="codeph">&lt;fx:Array&gt;</samp> tag
for the source array.</p>
<p>You can also define the objects by using properties directly
in the Object tags, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridSimpleAttributes.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:DataGrid&gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object Artist="Pavement"
Album="Slanted and Enchanted" Price="11.99" /&gt;
&lt;fx:Object Artist="Pavement"
Album="Brighten the Corners" Price="11.99" /&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:DataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>The column names displayed in the DataGrid control are the property
names of the Array Objects. By default, the columns are in alphabetical
order by the property names. Different Objects can define their
properties in differing orders. If an Array Object omits a property,
the DataGrid control displays an empty cell in that row. </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fef_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fef_verapache"><!-- --></a><h4 class="sectiontitle">Specifying
columns</h4>
<p>Each column in a DataGrid control is represented
by a DataGridColumn object. You use the <samp class="codeph">columns</samp> property
of the DataGrid control and the <samp class="codeph">&lt;mx:DataGridColumn&gt;</samp> tag
to select the DataGrid columns, specify the order in which to display
them, and set additional properties. You can also use the DataGridColumn
class <samp class="codeph">visible</samp> property to hide and redisplay columns,
as described in the next section.</p>
<p>
For complete reference information
for the <samp class="codeph">&lt;mx:DataGridColumn&gt;</samp> tag, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/dataGridClasses/DataGridColumn.html" target="_blank">DataGridColumn </a>in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. </p>
<p>
You specify an Array element to the <samp class="codeph">&lt;mx:columns&gt;</samp> child
tag of the <samp class="codeph">&lt;mx:DataGrid&gt;</samp> tag, as the following
example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridSpecifyColumns.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:DataGrid&gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object Artist="Pavement" Price="11.99"
Album="Slanted and Enchanted" /&gt;
&lt;fx:Object Artist="Pavement"
Album="Brighten the Corners" Price="11.99" /&gt;
&lt;/mx:ArrayList&gt;
&lt;mx:columns&gt;
&lt;mx:DataGridColumn dataField="Album" /&gt;
&lt;mx:DataGridColumn dataField="Price" /&gt;
&lt;/mx:columns&gt;
&lt;/mx:DataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you only display
the Album and Price columns in the DataGrid control. You can reorder
the columns as well, as the following example shows:</p>
<pre class="codeblock"> &lt;mx:columns&gt;
  &lt;mx:DataGridColumn dataField="Price" /&gt;
  &lt;mx:DataGridColumn dataField="Album" /&gt;
 &lt;/mx:columns&gt;</pre>
<p>In this example, you specify
that the Price column is the first column in the DataGrid control,
and that the Album column is the second. </p>
<p>
You can also use the <samp class="codeph">&lt;mx:DataGridColumn&gt;</samp> tag
to set other options. The following example uses the <samp class="codeph">headerText</samp> property
to set the name of the column to a value different than the default
name of Album, and uses the <samp class="codeph">width</samp> property to set
the album name column wide enough to display the full album names:</p>
<pre class="codeblock"> &lt;mx:columns&gt;
  &lt;mx:DataGridColumn dataField="Album" width="200" /&gt;
  &lt;mx:DataGridColumn dataField="Price" headerText="List Price" /&gt;
 &lt;/mx:columns&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b3c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff2_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b3c_verapache"><!-- --></a><h4 class="sectiontitle">Hiding
and displaying columns</h4>
<p>If you might display a column at
some times, but not at others, you can specify the DataGridColumn
class <samp class="codeph">visible</samp> property to hide or show the column.
The following example lets you hide or show the album price by clicking
a button:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridVisibleColumn.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;mx:DataGrid id="myDG" width="350"&gt;
&lt;mx:ArrayList&gt;
&lt;mx:source&gt;
&lt;fx:Object Artist="Pavement" Price="11.99"
Album="Slanted and Enchanted" /&gt;
&lt;fx:Object Artist="Pavement"
Album="Brighten the Corners" Price="11.99" /&gt;
&lt;/mx:source&gt;
&lt;/mx:ArrayList&gt;
&lt;mx:columns&gt;
&lt;mx:DataGridColumn dataField="Artist" /&gt;
&lt;mx:DataGridColumn dataField="Album" /&gt;
&lt;mx:DataGridColumn id="price" dataField="Price" visible="false"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:DataGrid&gt;
&lt;!-- The column id property specifies the column to show.--&gt;
&lt;mx:Button label="Toggle Price Column"
click="price.visible = !price.visible;" /&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
<div class="nested3" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fee_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fee_verapache"><!-- --></a>
<h4 class="topictitle4">Passing data to an MX DataGrid
control </h4>
<div>
<p>
Flex
lets you populate a DataGrid control from an ActionScript variable
definition or from a Flex data model. The following example populates
a DataGrid control by using a variable:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridPassData.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
initialize="initData();"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.*;
private var DGArray:Array = [
{Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
{Artist:'Pavement', Album:'Brighten the Corners', Price:11.99}];
[Bindable]
public var initDG:ArrayList;
//Initialize initDG ArrayList variable from the Array.
//If you use this technique to process an HTTPService,
//WebService, or RemoteObject result, use an ArrayCollection
//rather than an ArrayList.
public function initData():void {
initDG=new ArrayList(DGArray);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:DataGrid id="myGrid" width="350" height="200"
dataProvider="{initDG}" &gt;
&lt;mx:columns&gt;
&lt;mx:DataGridColumn dataField="Album" /&gt;
&lt;mx:DataGridColumn dataField="Price" /&gt;
&lt;/mx:columns&gt;
&lt;/mx:DataGrid&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you bind the variable <samp class="codeph">initDG</samp> to
the <samp class="codeph">&lt;mx:dataProvider&gt;</samp> property. You can still
specify a column definition event when using data binding. For a
description of using a model as a data provider, see <a href="flx_dpcontrols_dpc.html#WS19f279b149e7481c2954ae7a12c1290681b-7ffe_verapache">Populating
a ComboBox control by using variables and models</a>
</p>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fed_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fed_verapache"><!-- --></a>
<h3 class="topictitle3">Handling events in an MX DataGrid
control</h3>
<div>
<p>
The
DataGrid control and the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/events/DataGridEvent.html" target="_blank">DataGridEvent</a> class
define several event types that let you respond to user interaction.
For example, Flex broadcasts mx.events.ListEvent class event with
a <samp class="codeph">typ</samp>e property value of <samp class="codeph">mx.events.ListEvent.ITEM_CLICK</samp> ("itemClick")
when a user clicks an item in a DataGrid control. You can handle
this event as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridEvents.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.ListEvent;
private function itemClickEvent(event:ListEvent):void {
clickColumn.text=String(event.columnIndex);
clickRow.text=String(event.rowIndex);
eventType.text=event.type;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:DataGrid id="myGrid" width="350" height="150"
itemClick="itemClickEvent(event);"&gt;
&lt;mx:ArrayList&gt;
&lt;fx:Object Artist="Pavement" Price="11.99"
Album="Slanted and Enchanted" /&gt;
&lt;fx:Object Artist="Pavement" Album="Brighten the Corners"
Price="11.99" /&gt;
&lt;/mx:ArrayList&gt;
&lt;/mx:DataGrid&gt;
&lt;s:Form&gt;
&lt;s:FormItem label="Column Index:"&gt;
&lt;s:Label id="clickColumn"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Row Index:"&gt;
&lt;s:Label id="clickRow"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Type:"&gt;
&lt;s:Label id="eventType"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Application&gt; </pre>
<p>In this example, you use the event handler to display the column
index, row index, and event type in three TextArea controls.</p>
<p>The index of columns in the DataGrid control is zero-based, meaning
values are 0, 1, 2, ... , <em>n</em> ‑ 1, where <em>n</em> is the total
number of columns. Row items are also indexed starting at 0. Therefore,
if you select the first item in the second row, this example displays
0 in the TextArea for the column index, and 1 in the TextArea for the
row index. </p>
<p>To access the selected item in the event handler, you can use
the <samp class="codeph">currentTarget</samp> property of the event object,
and the <samp class="codeph">selectedItem</samp> property of the DataGrid control,
as the following code shows:</p>
<pre class="codeblock"> var selectedArtist:String=event.currentTarget.selectedItem.Artist;</pre>
<p>The <samp class="codeph">currentTarget</samp> property of the object passed
to the event handler contains a reference to the DataGrid control.
You can reference any control property by using <samp class="codeph">currentTarget</samp> followed
by a period and the property name. The <samp class="codeph">currentTarget.selectedItem</samp> field
contains the selected item.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache"><!-- --></a>
<h3 class="topictitle3">Sorting data in an MX DataGrid
control</h3>
<div>
<p>The DataGrid control supports displaying sorted data in
two ways:</p>
<ul>
<li>
<p>By default, the control displays data in the sorted order
of its underlying data provider collection. Therefore you can use
the collection <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/Sort.html" target="_blank">Sort</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/SortField.html" target="_blank">SortField</a> classes
to control the order of the rows.</p>
</li>
<li>
<p>By default, users can sort the display by clicking the column
headers. Clicking the column header initially sorts the display
in descending order of the entries in the selected column, and clicking
the header again reverses the sort order. You can disable sorting
an entire DataGrid Control or individual columns.</p>
<p>For detailed
information on using the Sort and SortField classes, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b66_verapache">Sorting and
filtering data for viewing</a>.</p>
</li>
</ul>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd5_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd5_verapache"><!-- --></a><h4 class="sectiontitle">Determining
the initial DataGrid sort order</h4>
<p>To specify the initial
DataGrid sort order, you sort the data provider. While a number
of approaches can work, the following technique takes best advantage of
the built in features of Flex collections:</p>
<ul>
<li>
<p>Use an
object that implements the ICollectionView interface, such as an
ArrayCollection, in the <samp class="codeph">dataProvider</samp> property of
your DataGrid. Specify a Sort object in the data provider object’s
the <samp class="codeph">sort</samp> field. Note that you cannot use an ArrayList
with a sort field.</p>
</li>
<li>
<p>Use the Sort object to control the order of the rows in the <samp class="codeph">dataProvider</samp> object.</p>
</li>
</ul>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd4_verapache"><!-- --></a><h4 class="sectiontitle">Controlling
user sorting of DataGrid displays</h4>
<p>The following DataGrid
and DataGridColumn properties control how users can sort data:</p>
<ul>
<li>
<p>The DataGrid <samp class="codeph">sortableColumns</samp> property is
a global switch that enables user sorting of the DataGrid display
by clicking column headings. The default this property is <samp class="codeph">true</samp>.</p>
</li>
<li>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/dataGridClasses/DataGridColumn.html" target="_blank">DataGridColumn</a>
<samp class="codeph">sortable</samp> property
specifies whether users can sort an individual column. The default
this property is <samp class="codeph">true</samp>.</p>
</li>
<li>
<p>The DataGridColumn <samp class="codeph">sortCompareFunction</samp> property
lets you specify a custom comparison function. This property sets
the <samp class="codeph">compare</samp> property of the default SortField class
object that the DataGrid uses to sort the grid when users click
the headers. It lets you specify the function that compares two objects
and determines which would be higher in the sort order, without requiring
you to explicitly create a Sort object on your data provider. For detailed
information on the comparison function signature and behavior, see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/dataGridClasses/DataGridColumn.html#sortCompareFunction()" target="_blank">sortCompareFunction</a> in
the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
<p>By default, the DataGrid class
uses its own sort code to control how the data gets sorted when
the user clicks a column. To override this behavior, you create
a <samp class="codeph">headerRelease</samp> event handler to handle the DataGridEvent
event that is generated when the user clicks the column header.
This event handler must do the following:</p>
<ol>
<li>
<p>Use the
event object’s <samp class="codeph">columnIndex</samp> property to determine
the clicked column.</p>
</li>
<li>
<p>Create an MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/Sort.html" target="_blank">Sort</a> object
with a set of MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/SortField.html" target="_blank">SortField</a> objects
based on the clicked column and any other rules that you need to
control the sorting order. For more information on using Sort objects,
see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b66_verapache">Sorting
and filtering data for viewing</a>.</p>
</li>
<li>
<p>Apply the Sort object to the collection assigned as the data
provider.</p>
</li>
<li>
<p>Call the DataGridEvent class event object’s <samp class="codeph">preventDefault()</samp> method to
prevent the DataGrid from doing a default column sort. </p>
<div class="note"><span class="notetitle">Note:</span> If you specify a <samp class="codeph">labelFunction</samp> property,
you must also specify a <samp class="codeph">sortCompareFunction</samp> function.
The Computed Columns example in Flex Explorer shows this use.</div>
</li>
</ol>
</li>
</ul>
<p>The
following example shows how to use the headerRelease event handler
to do multi-column sorting when a user clicks a DataGrid column
header.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b62_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fd6_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b62_verapache"><!-- --></a><h4 class="sectiontitle">Example:
Sorting a DataGrid on multiple columns</h4>
<p>The following example
shows how you can use a collection with a Sort object to determine
an initial multi-column sort and to control how the columns sort
when you click the headers. The data grid is initially sorted by
in-stock status first, artist second, and album name, third. If
you click any heading, that column becomes the primary sort criterion,
the previous primary criterion becomes the second criterion, and
the previous secondary criterion becomes the third criterion.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DataGridSort.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
initialize="initDP();"
width="550" height="400"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.events.DataGridEvent;
import mx.collections.*;
// Declare storage variables and initialize the simple variables.
// The data provider collection.
private var myDPColl:ArrayCollection;
// The Sort object used to sort the collection.
[Bindable]
private var sortA:Sort;
// The sort fields used to determine the sort.
private var sortByInStock:SortField;
private var sortByArtist:SortField;
private var sortByAlbum:SortField;
private var sortByPrice:SortField;
// The data source that populates the collection.
private var myDP:Array = [
{Artist:'Pavement', Album:'Slanted and Enchanted',
Price:11.99, InStock: true},
{Artist:'Pavement', Album:'Crooked Rain, Crooked Rain',
Price:10.99, InStock: false},
{Artist:'Pavement', Album:'Wowee Zowee',
Price:12.99, InStock: true},
{Artist:'Asphalt', Album:'Brighten the Corners',
Price:11.99, InStock: false},
{Artist:'Asphalt', Album:'Terror Twilight',
Price:11.99, InStock: true},
{Artist:'Asphalt', Album:'Buildings Meet the Sky',
Price:14.99, InStock: true},
{Artist:'Other', Album:'Other',
Price:5.99, InStock: true}
];
//Initialize the DataGrid control with sorted data.
private function initDP():void {
//Create an ArrayCollection backed by the myDP array of data.
myDPColl = new ArrayCollection(myDP);
//Create a Sort object to sort the ArrrayCollection.
sortA = new Sort();
//Initialize SortField objects for all valid sort fields:
// A true second parameter specifies a case-insensitive sort.
// A true third parameter specifies descending sort order.
// A true fourth parameter specifies a numeric sort.
sortByInStock = new SortField("InStock", true, true);
sortByArtist = new SortField("Artist", true);
sortByAlbum = new SortField("Album", true);
sortByPrice = new SortField("Price", true, false, true);
// Sort the grid using the InStock, Artist, and Album fields.
sortA.fields=[sortByInStock, sortByArtist, sortByAlbum];
myDPColl.sort=sortA;
// Refresh the collection view to show the sort.
myDPColl.refresh();
// Initial display of sort fields
tSort0.text = "First Sort Field: InStock";
tSort1.text = "Second Sort Field: Artist";
tSort2.text = "Third Sort Field: Album";
// Set the ArrayCollection as the DataGrid data provider.
myGrid.dataProvider=myDPColl;
// Set the DataGrid row count to the array length,
// plus one for the header.
myGrid.rowCount=myDPColl.length +1;
}
// Re-sort the DataGrid control when the user clicks a header.
private function headRelEvt(event:DataGridEvent):void {
// The new third priority was the old second priority.
sortA.fields[2] = sortA.fields[1];
tSort2.text = "Third Sort Field: " + sortA.fields[2].name;
// The new second priority was the old first priority.
sortA.fields[1] = sortA.fields[0];
tSort1.text = "Second Sort Field: " + sortA.fields[1].name;
// The clicked column determines the new first priority.
if (event.columnIndex==0) {
sortA.fields[0] = sortByArtist;
} else if (event.columnIndex==1) {
sortA.fields[0] = sortByAlbum;
} else if (event.columnIndex==2) {
sortA.fields[0] = sortByPrice;
} else {
sortA.fields[0] = sortByInStock;}
tSort0.text = "First Sort Field: " + sortA.fields[0].name;
// Apply the updated sort fields and re-sort.
myDPColl.sort=sortA;
// Refresh the collection to show the sort in the grid.
myDPColl.refresh();
// Prevent the DataGrid from doing a default column sort.
event.preventDefault();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- The Data Grid control.
By default the grid and its columns can be sorted by clicking.
The headerRelease event handler overrides the default sort
behavior. --&gt;
&lt;mx:DataGrid id="myGrid" width="100%" headerRelease="headRelEvt(event);"&gt;
&lt;mx:columns&gt;
&lt;mx:DataGridColumn minWidth="120" dataField="Artist" /&gt;
&lt;mx:DataGridColumn minWidth="200" dataField="Album" /&gt;
&lt;mx:DataGridColumn width="75" dataField="Price" /&gt;
&lt;mx:DataGridColumn width="75" dataField="InStock"
headerText="In Stock"/&gt;
&lt;/mx:columns&gt;
&lt;/mx:DataGrid&gt;
&lt;mx:VBox&gt;
&lt;mx:Label id="tSort0" text="First Sort Field: "/&gt;
&lt;mx:Label id="tSort1" text="Second Sort Field: "/&gt;
&lt;mx:Label id="tSort2" text="Third Sort Field: "/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db4_verapache"><!-- --></a>
<h3 class="topictitle3">MX DataGrid control user interaction</h3>
<div>
<p>
The
DataGrid control responds to mouse and keyboard activity. The response
to a mouse click or key press depends on whether a cell is editable.
A cell is editable when the <samp class="codeph">editable</samp> properties
of the DataGrid control and the DataGridColumn containing the cell
are both <samp class="codeph">true</samp>. Clicking within an editable cell
directs focus to that cell. Clicking a noneditable cell has no effect
on the focus. </p>
<p>Users can modify the DataGrid control appearance in the following
ways:</p>
<ul>
<li>
<p>If the value of the <samp class="codeph">sortableColumns</samp> property
is <samp class="codeph">true</samp>, the default value, clicking within a column
header causes the DataGrid control to be sorted based on the column’s
cell values. </p>
</li>
<li>
<p>If the value of the <samp class="codeph">draggableColumns</samp> property
is <samp class="codeph">true</samp>, the default value, clicking and holding
the mouse button within a column header, dragging horizontally,
and releasing the mouse button moves the column to new location. </p>
</li>
<li>
<p>If the value of the <samp class="codeph">resizableColumns</samp> property
is <samp class="codeph">true</samp>, the default value, clicking in the area
between columns permits column resizing. </p>
</li>
</ul>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7db4_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7feb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7db4_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7feb_verapache"><!-- --></a><h4 class="sectiontitle">Keyboard
navigation</h4>
<p>
The
DataGrid control has the following keyboard navigation features:</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="d183656e3445">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e3451">
<p>Action</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Enter</p>
<p>Return Shift+Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>When a cell is in editing state, commits
change, and moves editing to the cell on the same column, next row
down or up, depending on whether Shift is pressed.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Tab</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>Moves focus to the next editable cell, traversing
the cells in row order. If at the end of the last row, advances
to the next element in the parent container that can receive focus.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Shift+Tab</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>Moves focus to the previous editable cell.
If at the beginning of a row, advances to the end of the previous
row. If at the beginning of the first row, advances to the previous
element in the parent container that can receive focus.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Up Arrow Home</p>
<p>Page Up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>If editing a cell, shifts the cursor to
the beginning of the cell’s text. If the cell is not editable, moves selection
up one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Down Arrow</p>
<p>End</p>
<p>Page Down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>If editing a cell, shifts the cursor to
the end of the cell’s text. If the cell is not editable, moves selection down
one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Control</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>Toggle key. If you set the DataGrid control <samp class="codeph">allowMultipleSelection</samp> property
to <samp class="codeph">true</samp>, allows for multiple (noncontiguous) selection
and deselection. Works with key presses, click selection, and drag selection.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3445 ">
<p>Shift</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e3451 ">
<p>Contiguous select key. If you set the DataGrid
control <samp class="codeph">allowMultipleSelection</samp> property to <samp class="codeph">true</samp>,
allows for contiguous selections. Works with key presses, click
selection, and drag selection.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d80_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d80_verapache"><!-- --></a>
<h2 class="topictitle2">MX Tree control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Tree.html" target="_blank">Tree</a> control
lets a user view hierarchical data arranged as an expandable tree. </p>
<p>For complete reference information, see the <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. For information on hierarchical data
providers, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b69_verapache">Hierarchical
data objects</a>.</p>
<p>For information on the following topics, which are often important
for using advanced Tree controls, see:</p>
<ul>
<li>
<p>How to format the information in each Tree node and control
how users enter data in the nodes; see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
</li>
<li>
<p>How to drag objects to and from the Tree control; see <a href="flx_dragdrop_dd.html#WS2db454920e96a9e51e63e3d11c0bf69084-7c0a_verapache">Drag
and drop </a>.</p>
</li>
</ul>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fe9_verapache"><!-- --></a>
<h3 class="topictitle3">About Tree controls</h3>
<div>
<p>
A Tree control
is a hierarchical structure of <em>branch</em> and <em>leaf</em>
<em>nodes</em>.
Each item in a tree is called a node and can be either a leaf or
a branch. A branch node can contain leaf or branch nodes, or can
be empty (have no children). A leaf node is an end point in the
tree.</p>
<p>By default, a leaf is represented by a text label beside a file
icon and a branch is represented by a text label beside a folder
icon with a disclosure triangle that a user can open to expose children. </p>
<p>The following image shows a Tree control:</p>
<div class="figborder">
<img src="images/dpc_tree.png" alt="Tree control"/>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fe7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fe7_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Tree control</h3>
<div>
<p>You define a Tree control in MXML by using the <samp class="codeph">&lt;mx:Tree&gt;</samp> tag.
The Tree class extends the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/List.html" target="_blank">List</a> class and
Tree controls take all of the properties and methods of the List
control. For more information about using the List control, see <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d90_verapache">MX
List control</a>. Specify an <samp class="codeph">id</samp> value if you
intend to refer to a control elsewhere in your MXML, either in another
tag or in an ActionScript block. </p>
<p>The Tree control normally gets its data from a hierarchical data
provider, such as an XML structure. If the Tree represents dynamically
changing data, you should use a list or collection, such as the
standard <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/ArrayList.html" target="_blank">ArrayCollection</a>,
or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/collections/XMLListCollection.html" target="_blank">XMLListCollection</a> object,
as the data provider. </p>
<p>The Tree control uses a data descriptor to parse and manipulate
the data provider content. By default, the Tree control uses a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/treeClasses/DefaultDataDescriptor.html" target="_blank">DefaultDataDescriptor</a> instance,
but you can create your own class and specify it in the Tree control’s <samp class="codeph">dataDescriptor</samp> property. </p>
<p>The DefaultDataDescriptor class supports the following types
of data:</p>
<dl>
<dt class="dlterm">Collections</dt>
<dd>
<p>A collection implementation, such as an XMLListCollection
or ArrayCollection object. The DefaultDataDescriptor class includes
code to handle collections efficiently. Always use a collection
as the data provider if the data in the menu changes dynamically;
otherwise the Tree control might display obsolete data.</p>
</dd>
<dt class="dlterm">XML</dt>
<dd>
<p>A string containing valid XML text, or any of the following
objects containing valid E4X format XML data: <samp class="codeph">&lt;fx:XML&gt;</samp> or <a href="mxml/xmlList.html" target="_blank">&lt;fx:XMLList&gt;</a> compile-time tag,
or an XML or <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/XMLList.html" target="_blank">XMLList</a> object.</p>
</dd>
<dt class="dlterm">Other objects</dt>
<dd>
<p>An array of items, or an object that contains an array of
items, where a node’s children are contained in an item named <samp class="codeph">children</samp>.</p>
<p>The
DefaultDataDescriptor class also supports using an <samp class="codeph">&lt;fx:Model&gt;</samp> tag
as a data provider for a menu, but all leaf nodes must have the
name <samp class="codeph">children</samp>; As a general rule, it is a better
programming practice to use the <samp class="codeph">&lt;fx:XML&gt;</samp> or <samp class="codeph">&lt;fx:XMLList&gt;</samp> tags
when you need a Tree data provider that uses binding.</p>
<p>For
more information on hierarchical objects and data descriptors, including
a detailed description of the formats supported by the DefaultDataDescriptor,
see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b5d_verapache">Data
descriptors and hierarchical data structure</a>. </p>
<p>The following
code contains a single Tree control that defines the tree shown
in the image in <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d80_verapache">MX
Tree control</a>. This uses an XMLListCollection wrapper around
an <samp class="codeph">&lt;fx:XMLList&gt;</samp> tag. By using an XMLListCollection,
you can modify the underlying XML data provider by changing the
contents of the <samp class="codeph">MailBox</samp> XMLListCollection, and
the Tree control will represent the changes to the data. This example also
does not use the <samp class="codeph">&lt;mx:dataProvider&gt;</samp> tag because <samp class="codeph">dataProvider</samp> is the
default property of the Tree control.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeSimple.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;mx:Tree id="tree1"
labelField="@label"
showRoot="true"
width="160"&gt;
&lt;mx:XMLListCollection id="MailBox"&gt;
&lt;fx:XMLList&gt;
&lt;folder label="Mail"&gt;
&lt;folder label="INBOX"/&gt;
&lt;folder label="Personal Folder"&gt;
&lt;Pfolder label="Business" /&gt;
&lt;Pfolder label="Demo" /&gt;
&lt;Pfolder label="Personal" isBranch="true" /&gt;
&lt;Pfolder label="Saved Mail" /&gt;
&lt;/folder&gt;
&lt;folder label="Sent" /&gt;
&lt;folder label="Trash" /&gt;
&lt;/folder&gt;
&lt;/fx:XMLList&gt;
&lt;/mx:XMLListCollection&gt;
&lt;/mx:Tree&gt;
&lt;/s:Application&gt;</pre>
<p>The tags that represent tree
nodes in the XML data can have any name. The Tree control reads
the XML and builds the display hierarchy based on the nested relationship
of the nodes. For information on valid XML structure, see <a href="flx_about_dataproviders_ab.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b69_verapache">Hierarchical
data objects</a>.</p>
<p>Some data providers have a single top
level node, called a <em>root</em> node. Other data providers are
lists of nodes and do not have a root node. In some cases, you might not
want to display the root node as the Tree root. To prevent the tree
from displaying the root node, specify the <samp class="codeph">showRoot</samp> property
to <samp class="codeph">false;</samp> doing this does not affect the data provider
contents, only the Tree display. You can only specify a <samp class="codeph">false</samp>
<samp class="codeph">showRoot</samp> property
for data providers that have roots, that is, XML and Object-based
data providers.</p>
<p>A branch node can contain multiple child nodes,
and, by default, appears as a folder icon with a disclosure triangle
that lets users open and close the folder. Leaf nodes appear by
default as file icons and cannot contain child nodes.</p>
<p>When
a Tree control displays a node of a non-XML data provider, by default,
it displays the value of the <samp class="codeph">label</samp> property of
the node as the text label. When you use an E4X XML-based data provider,
however, you must specify the label field, even if the label is
identified by an attribute named “label”. To specify the label field,
use the <samp class="codeph">labelField</samp> property; for example, if the
label field is the label attribute, specify <samp class="codeph">labelField="@label"</samp>.</p>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7b2b_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7b2b_verapache"><!-- --></a>
<h3 class="topictitle3">Handling Tree control events</h3>
<div>
<p>
You
typically use events to respond to user interaction with a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Tree.html" target="_blank">Tree</a> control.
Since the Tree control is derived from the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/List.html" target="_blank">List</a> control,
you can use all of the events defined for the List control. The
Tree control also dispatches several <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/Event.html" target="_blank">Event</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/events/TreeEvent.html" target="_blank">TreeEvent </a>class
events, including <samp class="codeph">Event.change</samp> and <samp class="codeph">TreeEvent.itemOpen</samp>.
The following example defines event handlers for the <samp class="codeph">change</samp> and <samp class="codeph">itemOpen</samp> events: </p>
<pre class="codeblock">Ôªø&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeEvents.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.*;
import mx.events.*;
import mx.controls.*;
private function changeEvt(event:Event):void {
var theData:String = ""
if (event.currentTarget.selectedItem.@data) {
theData = " Data: " + event.currentTarget.selectedItem.@data;
}
forChange.text = event.currentTarget.selectedItem.@label + theData;
}
private function itemOpenEvt(event:TreeEvent):void {
forOpen.text = event.item.@label;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree id="XMLTree1" width="150" height="170"
labelField="@label" itemOpen="itemOpenEvt(event);"
change="changeEvt(event);"&gt;
&lt;mx:XMLListCollection id="MailBox"&gt;
&lt;fx:XMLList&gt;
&lt;node label="Mail" data="100"&gt;
&lt;node label="Inbox" data="70"/&gt;
&lt;node label="Personal Folder" data="10"&gt;
&lt;node label="Business" data="2"/&gt;
&lt;node label="Demo" data="3"/&gt;
&lt;node label="Personal" data="0" isBranch="true" /&gt;
&lt;node label="Saved Mail" data="5" /&gt;
&lt;/node&gt;
&lt;node label="Sent" data="15"/&gt;
&lt;node label="Trash" data="5"/&gt;
&lt;/node&gt;
&lt;/fx:XMLList&gt;
&lt;/mx:XMLListCollection&gt;
&lt;/mx:Tree&gt;
&lt;s:Form&gt;
&lt;s:FormItem label="Change Event:"&gt;
&lt;s:Label id="forChange" width="150"/&gt;
&lt;/s:FormItem&gt;
&lt;s:FormItem label="Open Event:"&gt;
&lt;s:Label id="forOpen" width="150"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you define event listeners for the <samp class="codeph">change</samp> and <samp class="codeph">itemOpen</samp> events.
The Tree control broadcasts the <samp class="codeph">change</samp> event when
the user selects a tree item, and broadcasts the <samp class="codeph">itemOpen</samp> event
when a user opens a branch node. For each event, the event handler
displays the label and the data property, if any, in a TextArea
control.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fdf_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fdf_verapache"><!-- --></a>
<h3 class="topictitle3">Expanding a tree node</h3>
<div>
<p>By default, the Tree control displays the root node or
nodes of the tree when it first opens. If you want to expand a node
of the tree when the tree opens, you can use the <samp class="codeph">expandItem()</samp> method
of the Tree control. The following change to the example in <a href="flx_dpcontrols_dpc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7b2b_verapache">Handling
Tree control events</a> calls the <samp class="codeph">expandItem()</samp> method as
part of the Tree control’s <samp class="codeph">creationComplete</samp> event
listener to expand the root node of the tree:</p>
<pre class="codeblock"> &lt;fx:Script&gt;
  &lt;![CDATA[
 .
 .
 .
  <strong>private function initTree():void {</strong>
  <strong>XMLTree1.expandItem(MailBox.getItemAt(0), true);</strong>
  <strong>forOpen.text=XMLTree1.openItems[0].@label;</strong>
  <strong>}</strong>
  ]]&gt;
  &lt;/fx:Script&gt;
 
 &lt;mx:Tree id="tree1" ... <strong>creationComplete="initTree()</strong>;" &gt;
  ...
 &lt;/mx:Tree&gt;</pre>
<p>This example must use the Tree control’s <samp class="codeph">creationComplete</samp> event,
not the <samp class="codeph">initialize</samp> event, because the data provider
is not fully initialized and available until the <samp class="codeph">creationComplete</samp> event.</p>
<p>The Tree control <samp class="codeph">openItems</samp> property is an Array
containing all expanded tree nodes. The following line in the example
code displays the label of the first (and only) open item in the
tree:</p>
<pre class="codeblock"> forOpen.text=XMLTree1.openItems[0].@label;</pre>
<p>In this example, however, you could also get the <samp class="codeph">openItems</samp> box
to indicate the initial open item by setting the <samp class="codeph">expandItem()</samp> method
to dispatch an <samp class="codeph">itemOpen</samp> event. You can do this
by specifying the fourth, optional parameter of the <samp class="codeph">expandItem()</samp> method
to <samp class="codeph">true.</samp> The <samp class="codeph">true</samp> fourth parameter
causes the tree to dispatch an <samp class="codeph">open</samp> event when
the item opens. The following example shows the use of the fourth
parameter:</p>
<pre class="codeblock"> XMLTree1.expandItem(MailBox.getItemAt(0), true, false, true);</pre>
<p>You can programmatically walk down a Tree control’s nodes and
open a node without knowing what depth you are at in the Tree’s
data provider. One way to do this is by using the <samp class="codeph">children()</samp> method
of a node’s XML object to test whether the node has any children;
you can use the <samp class="codeph">expandItem()</samp> method to open the
node.</p>
<p>The following example opens nodes in the Tree control based on
the values of query string parameters. For example, if you pass <em>app_url</em>?0=1&amp;1=2&amp;2=0
to the application, then Flex opens the second item at the top level
of the tree, the third item at the next level, and the first item
at the third level of the tree (nodes are zero-based).</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/DrillIntoTree.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
creationComplete="initApp();"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.XMLListCollection;
import mx.core.FlexGlobals;
[Bindable]
private var treeData:XML =
&lt;root&gt;
&lt;node label="Monkeys"&gt;
&lt;node label="South America"&gt;
&lt;node label="Coastal"/&gt;
&lt;node label="Inland"/&gt;
&lt;/node&gt;
&lt;node label="Africa" isBranch="true"/&gt;
&lt;node label="Asia" isBranch="true"/&gt;
&lt;/node&gt;
&lt;node label="Sharks"&gt;
&lt;node label="South America" isBranch="true"/&gt;
&lt;node label="Africa" isBranch="true"/&gt;
&lt;node label="Asia" &gt;
&lt;node label="Coastal"/&gt;
&lt;node label="Inland"/&gt;
&lt;/node&gt;
&lt;/node&gt;
&lt;/root&gt;;
private var openSequence:Array = [];
private function initApp():void {
/* Parse URL and place values into openSequence Array.
This lets you pass any integers on the query string,
in any order. So:
http://localhost/flex/flex2/DrillIntoTree.swf?0=1&amp;1=2&amp;2=0
results in an array of selections like this:
0:1
1:2
2:0
Non-ints are ignored.
The Array is then used to drill down into the tree.
*/
var paramLength:int = 0;
for (var s:String in FlexGlobals.topLevelApplication.parameters) {
if (!isNaN(Number(s))) {
openSequence[s] = FlexGlobals.topLevelApplication.parameters[s];
paramLength += 1;
}
}
openTree();
}
private function openTree():void {
var nodeList:XMLListCollection =
myTree.dataProvider as XMLListCollection;
var node:XMLList = nodeList.source;
for(var i:int=0; i &lt; openSequence.length; i++) {
var j:int = openSequence[i];
var n:XML = node[j];
if( n.children() != null ) {
myTree.expandItem(n,true,false);
node = n.children();
} else {
break;
}
}
if( n != null ) myTree.selectedItem = n;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree id="myTree"
y="50"
width="221"
height="257"
horizontalCenter="0"
dataProvider="{treeData.node}"
labelField="@label"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying Tree control icons</h3>
<div>
<p>The Tree control provides four techniques for specifying
node icons:</p>
<ul>
<li>
<p>The <samp class="codeph">folderOpenIcon</samp>, <samp class="codeph">folderClosedIcon</samp>,
and <samp class="codeph">defaultLeafIcon</samp> properties</p>
</li>
<li>
<p>Data provider node icon fields</p>
</li>
<li>
<p>The <samp class="codeph">setItemItcon()</samp> method</p>
</li>
<li>
<p>The <samp class="codeph">iconFunction</samp> property</p>
</li>
</ul>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fde_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fde_verapache"><!-- --></a><h4 class="sectiontitle">Using
icon properties</h4>
<p>You can use the <samp class="codeph">folderOpenIcon</samp>, <samp class="codeph">folderClosedIcon</samp>,
and <samp class="codeph">defaultLeafIcon</samp> properties to control the Tree
control icons. For example, the following code specifies a default
leaf icon, and icons for the open and closed states of branch nodes:</p>
<pre class="codeblock"> &lt;mx:Tree folderOpenIcon="@Embed(source='open.jpg')"
folderClosedIcon="@Embed(source='closed.jpg')"
defaultLeafIcon="@Embed(source='def.jpg')"&gt; </pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcf_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fcf_verapache"><!-- --></a><h4 class="sectiontitle">Using
icon fields</h4>
<p>
You
can specify an icon displayed with each Tree leaf when you populate
it by using XML, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeIconField.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
[Bindable]
[Embed(source="assets/radioIcon.jpg")]
public var iconSymbol1:Class;
[Bindable]
[Embed(source="assets/topIcon.jpg")]
public var iconSymbol2:Class;
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree iconField="@icon"
labelField="@label"
showRoot="false"
width="160"&gt;
&lt;fx:XMLList&gt;
&lt;node label="New"&gt;
&lt;node label="HTML Document" icon="iconSymbol2"/&gt;
&lt;node label="Text Document" icon="iconSymbol2"/&gt;
&lt;/node&gt;
&lt;node label="Close" icon="iconSymbol1"/&gt;
&lt;/fx:XMLList&gt;
&lt;/mx:Tree&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, you use the <samp class="codeph">iconField</samp> property
to specify the field of each item containing the icon. You use the <samp class="codeph">Embed</samp> metadata
to import the icons, then reference them in the XML definition.
You cannot use icon fields to specify icons for individual branch
nodes; instead you must use the Tree control’s <samp class="codeph">folderOpenIcon</samp>, <samp class="codeph">folderClosedIcon</samp> properties,
each of which specifies an icon to use for all open or closed branches,
or use the <samp class="codeph">setItemIcon()</samp> method to set individual
node icons.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff1_verapache"><!-- --></a><h4 class="sectiontitle">Using
the setItemIcon() method</h4>
<p>You can use the <samp class="codeph">setItemIcon()</samp> method
to specify the icon, or both the open and closed icons for a tree
item. This method lets you dynamically specify and change icons
for individual branches and nodes. For details on this function
see <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Tree.html#setItemIcon()" target="_blank">setItemIcon()</a> in <em>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>. The following example sets the open and
closed node icon for the first branch node and the icon for the
second branch (which does not have any leaves):</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeItemIcon.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
[Bindable]
[Embed(source="assets/radioIcon.jpg")]
public var iconSymbol1:Class;
[Bindable]
[Embed(source="assets/topIcon.jpg")]
public var iconSymbol2:Class;
private function setIcons():void {
myTree.setItemIcon(myTree.dataProvider.getItemAt(0),
iconSymbol1, iconSymbol2);
myTree.setItemIcon(myTree.dataProvider.getItemAt(1),
iconSymbol2, null);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree id="myTree" labelField="@label"
showRoot="false"
width="160" initialize="setIcons();"&gt;
&lt;fx:XMLList&gt;
&lt;node label="New"&gt;
&lt;node label="HTML Document"/&gt;
&lt;node label="Text Document"/&gt;
&lt;/node&gt;
&lt;node label="Close"/&gt;
&lt;/fx:XMLList&gt;
&lt;/mx:Tree&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fdc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7fdc_verapache"><!-- --></a><h4 class="sectiontitle">Using
an icon function</h4>
<p>You can use the Tree control <samp class="codeph">iconFunction</samp> property
to specify a function that dynamically sets all icons for the tree.
For information on using the <samp class="codeph">iconFunction</samp> property
in Flex controls, see <a href="flx_dpcontrols_dpc.html#WS19f279b149e7481c2591359a12c12834bb9-8000_verapache">Specifying
an icon to the List control</a>.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b29_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7b29_verapache"><!-- --></a><h4 class="sectiontitle">Opening
a Tree control to a specific node</h4>
<p>By default, a Tree control
is collapsed when it initializes, but you can initialize it so that
it is expanded with a specific node selected, as the following example
shows. In this application, the <samp class="codeph">initTree()</samp> method
is called after the Tree control is created. This method expands
the root node of the Tree control and sets its <samp class="codeph">selectedIndex</samp> property
to the index number of a specific node.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeOpenNode.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.events.*;
import mx.events.*;
import mx.controls.*;
private function initTree():void {
XMLTree1.expandItem(MailBox.getItemAt(0), true);
XMLTree1.selectedIndex = 2;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree id="XMLTree1"
width="150" height="170"
labelField="@label"
creationComplete="initTree();"&gt;
&lt;mx:XMLListCollection id="MailBox"&gt;
&lt;fx:XMLList&gt;
&lt;node label="Mail" data="100"&gt;
&lt;node label="Inbox" data="70"/&gt;
&lt;node label="Personal Folder" data="10"&gt;
&lt;node label="Business" data="2"/&gt;
&lt;node label="Demo" data="3"/&gt;
&lt;node label="Saved Mail" data="5" /&gt;
&lt;/node&gt;
&lt;node label="Sent" data="15"/&gt;
&lt;node label="Trash" data="5"/&gt;
&lt;/node&gt;
&lt;/fx:XMLList&gt;
&lt;/mx:XMLListCollection&gt;
&lt;/mx:Tree&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf66ce9-7fea_verapache__WS2db454920e96a9e51e63e3d11c0bf66ce9-7ff3_verapache"><!-- --></a><h4 class="sectiontitle">Adding
and removing leaf nodes at run time </h4>
<p>You can add and remove
leaf nodes from a Tree control at run time. The following example
contains code for making these changes. The application initializes
with predefined branches and leaf nodes that represent company departments
and employees. You can dynamically add leaf (employee) nodes to
the Operations department branch at run time. You can also remove
any leaf node, including any you create at run time.</p>
<p>The XML
in this example contains two different element names, department
and employee. The Tree control's label function, <samp class="codeph">treeLabel()</samp>,
determines what text is displayed for these types of elements. It
uses E4X syntax to return either the title of a department or the
name of an employee. Those values are then used in the <samp class="codeph">addEmployee()</samp>and <samp class="codeph">removeEmployee()</samp>methods.</p>
<p>To
add employees to the Operations department, the <samp class="codeph">addEmployee()</samp> method
uses E4X syntax to get the Operations department node based on the value
of its title attribute, and stores it in the dept variable, which
is of type XMLList. It then appends a child node to the Operations
node by calling <samp class="codeph">dept.appendChild()</samp>.</p>
<p>The <samp class="codeph">removeEmployee()</samp> method
stores the currently selected item in the node variable, which is
of type XML. The method calls the <samp class="codeph">node.localName()</samp> method
to determine if the selected item is an employee node. If the item
is an employee node, it is deleted.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- dpcontrols/TreeAddRemoveNode.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.collections.XMLListCollection;
[Bindable]
private var company:XML =
&lt;list&gt;
&lt;department title="Finance" code="200"&gt;
&lt;employee name="John H"/&gt;
&lt;employee name="Sam K"/&gt;
&lt;/department&gt;
&lt;department title="Operations" code="400"&gt;
&lt;employee name="Bill C"/&gt;
&lt;employee name="Jill W"/&gt;
&lt;/department&gt;
&lt;department title="Engineering" code="300"&gt;
&lt;employee name="Erin M"/&gt;
&lt;employee name="Ann B"/&gt;
&lt;/department&gt;
&lt;/list&gt;;
[Bindable]
private var companyData:XMLListCollection =
new XMLListCollection(company.department);
private function treeLabel(item:Object):String {
var node:XML = XML(item);
if( node.localName() == "department" )
return node.@title;
else
return node.@name;
}
private function addEmployee():void {
var newNode:XML = &lt;employee/&gt;;
newNode.@name = empName.text;
var dept:XMLList =company.department.(@title == "Operations");
if( dept.length() &gt; 0 ) {
dept[0].appendChild(newNode);
empName.text = "";
}
}
private function removeEmployee():void {
var node:XML = XML(tree.selectedItem);
if( node == null ) return;
if( node.localName() != "employee" ) return;
var children:XMLList = XMLList(node.parent()).children();
for(var i:Number=0; i &lt; children.length(); i++) {
if( children[i].@name == node.@name ) {
delete children[i];
}
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Tree id="tree"
top="72" left="50"
dataProvider="{companyData}"
labelFunction="treeLabel"
height="225" width="300"/&gt;
&lt;mx:VBox&gt;
&lt;mx:HBox&gt;
&lt;mx:Button label="Add Operations Employee" click="addEmployee();"/&gt;
&lt;mx:TextInput id="empName"/&gt;
&lt;/mx:HBox&gt;
&lt;mx:Button label="Remove Selected Employee" click="removeEmployee();"/&gt;
&lt;/mx:VBox&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7da7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7da7_verapache"><!-- --></a>
<h3 class="topictitle3">Tree user interaction</h3>
<div>
<p>You can let users edit tree control labels. The controls
also support several keyboard navigation and editing keys.</p>
</div>
<div class="nested3" id="WS19f279b149e7481c-407eb5a312c12b6a7c8-8000_verapache"><a name="WS19f279b149e7481c-407eb5a312c12b6a7c8-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Editing a node label at run time</h4>
<div>
<p>
Set
the <samp class="codeph">editable</samp> property of the Tree control to <samp class="codeph">true</samp> to
make node labels editable at run time. To edit a node label, the
user selects the label, and then enters a new label or edits the
existing label text. </p>
<p>
To
support label editing, the Tree control’s <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/List.html" target="_blank">List</a> superclass
uses the following events. These events belong to the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/events/ListEvent.html" target="_blank">ListEvent</a> class: </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="d183656e4361">
<p>Event</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e4367">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4361 ">
<p>
<samp class="codeph">itemEditBegin</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4367 ">
<p>Dispatched when the editedItemPosition property
has been set and the cell can be edited.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4361 ">
<p>
<samp class="codeph">itemEditEnd</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4367 ">
<p>Dispatched when cell editing session ends
for any reason.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4361 ">
<p>
<samp class="codeph">itemFocusIn</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4367 ">
<p>Dispatched when tree node gets the focus:
when a user selects the label or tabs to it.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4361 ">
<p>
<samp class="codeph">itemFocusOut</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4367 ">
<p>Dispatched when a label loses focus.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4361 ">
<p>
<samp class="codeph">itemClick</samp>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4367 ">
<p>Dispatched when a user clicks on an item
in the control.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>These events are commonly used in custom item editors. For more
information see <a href="flx_cellrenderer_cr.html#WS2db454920e96a9e51e63e3d11c0bf69084-7fb7_verapache">MX
item renderers and item editors</a>.</p>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-407eb5a312c12b6a7c8-7fff_verapache"><a name="WS19f279b149e7481c-407eb5a312c12b6a7c8-7fff_verapache"><!-- --></a>
<h4 class="topictitle4">Using the keyboard to edit labels</h4>
<div>
<p>
If
you set the Tree <samp class="codeph">editable</samp> property to <samp class="codeph">true</samp>,
you can use the following keys to edit labels: </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="d183656e4515">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e4521">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Down Arrow</p>
<p>Page Down</p>
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Moves the caret to the end of the label.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Up Arrow</p>
<p>Page Up</p>
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Moves the caret to the beginning of the
label.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Moves the caret forward one character.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Left Arrow </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Moves the caret backward one character.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Ends editing and moves selection to the
next visible node, which can then be edited. At the last node, selects
the label.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Shift Enter</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Ends editing and moves selection to the
previous visible node, which can then be edited. At the first node,
selects the label.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Escape</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>Cancels the edit, restores the text, and
changes the row state from editing to selected.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>TAB</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>When in editing mode, accepts the current
changes, selects the row below, and goes into editing mode with
the label text selected. If at the last element in the tree or not
in editing mode, sends focus to the next control.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4515 ">
<p>Shift-TAB</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4521 ">
<p>When in editing mode, accepts the current
changes, selects the row above, and goes into editing mode. If at
the first element in the tree or not in editing mode, sends focus
to the previous control.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481c-407eb5a312c12b6a7c8-7ffe_verapache"><a name="WS19f279b149e7481c-407eb5a312c12b6a7c8-7ffe_verapache"><!-- --></a>
<h4 class="topictitle4">Tree Navigation keys</h4>
<div>
<p>
When
a Tree control is not editable and has focus from clicking or tabbing,
you use the following keys to control it:</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="d183656e4715">
<p>Key</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d183656e4721">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Down Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection down one. When the Tree
control gets focus, use the Down arrow to move focus to the first
node. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Up Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection up one item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Right Arrow</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Opens a selected branch node. If a branch
is already open, moves to the first child node.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Left Arrow </p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Closes a selected branch node. If a leaf
node or a closed branch node is currently selected, selects the
parent node.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Spacebar or * (Asterisk on numeric keypad)</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Opens or closes a selected branch node (toggles
the state).</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>+ (Plus sign on numeric keypad)</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Opens a selected branch node.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>- (Minus sign on numeric keypad)</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Closes a selected branch node.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Control + Arrow keys</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the focus, but does not select a node.
Use the Spacebar to select a node. </p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>End</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection to the bottom of the
list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Home</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection to the top of the list.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Page down</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection down one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Page up</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>Moves the selection up one page.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Control</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>If the <samp class="codeph">allowMultipleSelection</samp> property
is <samp class="codeph">true</samp>, allows multiple noncontiguous selections.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4715 ">
<p>Shift</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d183656e4721 ">
<p>If the <samp class="codeph">allowMultipleSelection</samp> property
is <samp class="codeph">true</samp>, allows multiple contiguous selections.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p/>
</div>
</div>
</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>