If you specify horizontalScrollPolicy="on", the default width of a List control does not change; it is still large enough to display the widest visible label. If you set horizontalScrollPolicy="on", and specify a List control pixel width, you can use the measureWidthOfItems() 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.

 <mx:List id="li2" 
	width="200" horizontalScrollPolicy="on" 
	maxHorizontalScrollPosition="{li2.measureWidthOfItems() - li2.width +5}">

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.

Lists, and all subclasses of the ListBase class, determine their sizes when a style changes or the data provider changes.

If you set a width property that is less than the width of the longest label and specify the horizontalScrollPolicy="off", labels that exceed the control width are clipped.

You use the <mx:List> tag to define a List control. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The List control uses a list-based data provider. For more information, see Data providers and collections.

You specify the data for the List control by using the dataProvider property of the control. However, because dataProvider is the List control's default property, you do not have to specify a dataProvider child tag of the <mx:List> tag. In the simplest case for creating a static List control, you need only put <fx:String> tags in the control body, because Flex also automatically interprets the multiple tags as an Array of Strings, as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/ListDataProvider.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <mx:List> 
        <mx:dataProvider> 
            <fx:String>AK</fx:String> 
            <fx:String>AL</fx:String> 
            <fx:String>AR</fx:String> 
        </mx:dataProvider> 
    </mx:List> 
</s:Application>

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 Data providers and collections.

The index of items in the List control is zero-based, which means that values are 0, 1, 2, ... , n - 1, where n is the total number of items. The value of the item is its label text.

You typically use events to handle user interaction with a List control. The following example code adds a handler for a change event to the List control. Flex broadcasts a mx.ListEvent.CHANGE event when the value of the control changes due to user interaction.

<?xml version="1.0"?> 
<!-- dpcontrols/ListChangeEvent.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
            import flash.events.Event; 
 
            public function changeEvt(event:Event):void { 
                forChange.text=event.currentTarget.selectedItem.label + " " + 
                event.currentTarget.selectedIndex; 
            } 
        ]]> 
    </fx:Script> 
 
    <mx:List width="35" change="changeEvt(event)"> 
        <fx:Object label="AL" data="Montgomery"/> 
        <fx:Object label="AK" data="Juneau"/> 
        <fx:Object label="AR" data="Little Rock"/> 
    </mx:List> 
    <mx:TextArea id="forChange" width="150"/> 
</s:Application>

In this example, you use two properties of the List control, selectedItem and selectedIndex, in the event handler. Every change event updates the TextArea control with the label of the selected item and the item's index in the control.

The target 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 currentTarget property. The currentTarget.selectedItem field contains a copy of the selected item. If you populate the List control with an Array of Strings, the currentTarget.selectedItem field contains a String. If you populate it with an Array of Objects, the currentTarget.selectedItem field contains the Object that corresponds to the selected item, so, in this case, currentTarget.selectedItem.label refers to the selected item's label field.

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 allowMultipleSelection property to true to allow multiple selection.)

All mouse or keyboard selections broadcast a change event. For mouse interactions, the List control broadcasts this event when the mouse button is released.

If you set the allowDragSelection property to true, 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.

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.

The List control has the following keyboard navigation features:

The contents of a HorizontalList control can look very similar to the contents of an HBox container in which a Repeater 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 Dynamically repeating controls and containers.

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 allowMultipleSelection property.

The following image shows a HorizontalList control:

For complete reference information, see HorizontalList in the ActionScript 3.0 Reference for Apache Flex.

You use the <mx:HorizontalList> tag to define a HorizontalList control. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The HorizontalList control shares many properties and methods with the List control; see MX List control for information on how to use several of these shared properties. The HorizontalList control uses a list-based data provider. For more information, see Data providers and collections.

You specify the data for a HorizontalList control by using the dataProvider property of the <mx:HorizontalList> tag, as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/HListDataProvider.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    width="450"> 
    
    <fx:Script> 
        <![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; 
            } 
        ]]>   
    </fx:Script> 
 
    <!-- A four-column HorizontalList. The itemRenderer is a Flex Image control. 
       When the control is created, pass the cat array to the initialization routine. --> 
    <mx:HorizontalList id="myList" 
        columnWidth="100" 
        rowHeight="100" 
        columnCount="4" 
        itemRenderer="mx.controls.Image" 
        creationComplete="initCatalog(cat);"/> 
</s:Application>

In this example, you use the creationComplete event to populate the data provider with an ArrayList of image files, and the itemRenderer 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.

The user clicks individual list items to select them, and holds down the Control and Shift keys while clicking to select multiple items.

All mouse or keyboard selections broadcast a change 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.

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.

The contents of a TileList control can look very similar to the contents of a Tile container in which a Repeater 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 Dynamically repeating controls and containers.

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 allowMultipleSelection property.

The TileList control lays out its children in one or more vertical columns or horizontal rows, starting new rows or columns as necessary. The direction property determines the primary direction of the layout. The valid values for the direction property are and horizontal (default) and vertical for a layout. In a horizontal 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 vertical layout, the tiles are filled in column by column in the available vertical space, and the control may have a horizontal scroll bar.

The following image shows a TileList control:

You use the <mx:TileList> tag to define a TileList control. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The TileList control shares many properties and methods with the List control; see MX List control for information on how to use several of these shared properties. The TileList control uses a list-based data provider. For more information, see Data providers and collections.

You specify the data for a TileList control by using the dataProvider property of the <mx:TileList> tag, as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/TileListDataProvider.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    initialize="initData();" > 
    
    <fx:Script> 
        <![CDATA[ 
            import mx.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); 
            } 
        ]]> 
    </fx:Script> 
 
   <mx:TileList dataProvider="{TileListdp}" 
      itemRenderer="mx.controls.Button"/> 
</s:Application>

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 itemRenderer 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.

The user clicks individual list items to select them, and holds down the Control and Shift keys while clicking to select multiple items.

All mouse or keyboard selections broadcast a change 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.

The following image shows a ComboBox control:

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.

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.

You use the <mx:ComboBox> tag to define a ComboBox control in MXML. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The ComboBox control uses a list-based data provider. For more information, see Data providers and collections.

You specify the data for the ComboBox control by using the dataProvider property of the <mx:ComboBox> tag. The data provider should be a list or collection; the standard list implementation is the ArrayList class. The standard collection implementations are the ArrayCollection and XMLListCollection 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 Data providers and collections.

In a simple case for creating a ComboBox control, you specify the property by using an dataProvider child tag, and use an <mx:ArrayList> tag to define the entries as an ArrayList whose source is an Array of Strings, as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/ComboBoxSimple.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:ComboBox> 
      <mx:ArrayList> 
         <fx:String>AK</fx:String> 
         <fx:String>AL</fx:String> 
         <fx:String>AR</fx:String> 
      </mx:ArrayList> 
   </mx:ComboBox> 
</s:Application>

This example shows how you can take advantages of MXML defaults. You do not have to use an dataProvider tag, because dataProvider is the default property of the ComboBox control. Similarly, you do not have to use an <mx:source> tag inside the <mx:ArrayList> tag because source is the default property of the ArrayList class. Finally, you do not have to specify an <fx:Array> tag for the source array.

The data provider can also contain objects with multiple fields, as in the following example:

<?xml version="1.0"?> 
<!-- dpcontrols/ComboBoxMultiple.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:ComboBox> 
      <mx:ArrayList> 
         <fx:Object label="AL" data="Montgomery"/> 
         <fx:Object label="AK" data="Juneau"/> 
         <fx:Object label="AR" data="Little Rock"/> 
      </mx:ArrayList> 
   </mx:ComboBox> 
</s:Application>

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 Specifying ComboBox labels.

The index of items in the ComboBox control is zero-based, which means that values are 0, 1, 2, ... , n - 1, where n is the total number of items. The value of the item is its label text.

A ComboBox control can be noneditable or editable, as specified by the Boolean editable 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.

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 MX TextInput control), 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.

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.

You can also use the following keys to control a noneditable ComboBox control when the drop-down list is not open:

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:

The DataGrid control provides the following features:

• Resizable, sortable, and customizable column layouts, including hidable columns

• Optional customizable column and row headers, including optionally wrapping header text

• Columns that the user can resize and reorder at run time

• Selection events

• Ability to use a custom item renderer for any column

• Support for paging through data

• Locked rows and columns that do not scroll

The following image shows a DataGrid control:

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.

You use the <mx:DataGrid> tag to define a DataGrid control in MXML. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The DataGrid control uses a list-based data provider. For more information, see Data providers and collections.

You specify the data for the DataGrid control by using the dataProvider property. You can specify data in several different ways. In the simplest case for creating a DataGrid control, you use the dataProvider property subtag with <mx:ArrayList>, and <fx:Object> 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:

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridSimple.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:DataGrid> 
      <mx:ArrayList> 
         <fx:Object> 
            <fx:Artist>Pavement</fx:Artist> 
            <fx:Price>11.99</fx:Price> 
            <fx:Album>Slanted and Enchanted</fx:Album> 
         </fx:Object> 
         <fx:Object> 
            <fx:Artist>Pavement</fx:Artist> 
            <fx:Album>Brighten the Corners</fx:Album> 
            <fx:Price>11.99</fx:Price> 
         </fx:Object> 
      </mx:ArrayList> 
   </mx:DataGrid> 
</s:Application>

This example shows how you can take advantages of MXML defaults. You do not have to use an dataProvider tag, because dataProvider is the default property of the DataGrid control. Similarly, you do not have to use an <mx:source> tag inside the <mx:ArrayList> tag because source is the default property of the ArrayList class. Finally, you do not have to specify an <fx:Array> tag for the source array.

You can also define the objects by using properties directly in the Object tags, as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridSimpleAttributes.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:DataGrid> 
      <mx:ArrayList> 
         <fx:Object Artist="Pavement" 
            Album="Slanted and Enchanted" Price="11.99" /> 
         <fx:Object Artist="Pavement" 
            Album="Brighten the Corners" Price="11.99" /> 
      </mx:ArrayList> 
   </mx:DataGrid> 
</s:Application>

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.

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridSpecifyColumns.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:DataGrid> 
      <mx:ArrayList> 
         <fx:Object Artist="Pavement" Price="11.99" 
            Album="Slanted and Enchanted" /> 
         <fx:Object Artist="Pavement" 
            Album="Brighten the Corners" Price="11.99" /> 
      </mx:ArrayList> 
      <mx:columns> 
         <mx:DataGridColumn dataField="Album" /> 
         <mx:DataGridColumn dataField="Price" /> 
      </mx:columns> 
   </mx:DataGrid> 
</s:Application>

 <mx:columns> 
 	<mx:DataGridColumn dataField="Price" /> 
 	<mx:DataGridColumn dataField="Album" /> 
 </mx:columns>

 <mx:columns> 
 	<mx:DataGridColumn dataField="Album" width="200" /> 
 	<mx:DataGridColumn dataField="Price" headerText="List Price" /> 
 </mx:columns>

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridVisibleColumn.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
   <mx:DataGrid id="myDG" width="350"> 
      <mx:ArrayList> 
          <mx:source> 
              <fx:Object Artist="Pavement" Price="11.99" 
                  Album="Slanted and Enchanted" /> 
              <fx:Object Artist="Pavement" 
                  Album="Brighten the Corners" Price="11.99" /> 
          </mx:source> 
      </mx:ArrayList> 
      <mx:columns> 
         <mx:DataGridColumn dataField="Artist" /> 
         <mx:DataGridColumn dataField="Album" /> 
         <mx:DataGridColumn id="price" dataField="Price" visible="false"/> 
      </mx:columns> 
   </mx:DataGrid> 
 
   <!-- The column id property specifies the column to show.--> 
   <mx:Button label="Toggle Price Column" 
      click="price.visible = !price.visible;" /> 
</s:Application> 

The DataGrid control and the DataGridEvent class define several event types that let you respond to user interaction. For example, Flex broadcasts mx.events.ListEvent class event with a type property value of mx.events.ListEvent.ITEM_CLICK ("itemClick") when a user clicks an item in a DataGrid control. You can handle this event as the following example shows:

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridEvents.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <fx:Script> 
        <![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; 
            } 
        ]]> 
    </fx:Script> 
    
    <mx:DataGrid id="myGrid" width="350" height="150" 
        itemClick="itemClickEvent(event);"> 
        <mx:ArrayList> 
            <fx:Object Artist="Pavement" Price="11.99" 
                Album="Slanted and Enchanted" /> 
            <fx:Object Artist="Pavement" Album="Brighten the Corners" 
                Price="11.99" /> 
        </mx:ArrayList> 
    </mx:DataGrid> 
    <s:Form> 
        <s:FormItem label="Column Index:"> 
            <s:Label id="clickColumn"/>                
        </s:FormItem> 
        <s:FormItem label="Row Index:"> 
            <s:Label id="clickRow"/>               
        </s:FormItem> 
        <s:FormItem label="Type:"> 
            <s:Label id="eventType"/>              
        </s:FormItem> 
    </s:Form> 
</s:Application> 

In this example, you use the event handler to display the column index, row index, and event type in three TextArea controls.

The index of columns in the DataGrid control is zero-based, meaning values are 0, 1, 2, ... , n ‑ 1, where n 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.

To access the selected item in the event handler, you can use the currentTarget property of the event object, and the selectedItem property of the DataGrid control, as the following code shows:

 var selectedArtist:String=event.currentTarget.selectedItem.Artist;

The currentTarget property of the object passed to the event handler contains a reference to the DataGrid control. You can reference any control property by using currentTarget followed by a period and the property name. The currentTarget.selectedItem field contains the selected item.

The DataGrid control supports displaying sorted data in two ways:

• By default, the control displays data in the sorted order of its underlying data provider collection. Therefore you can use the collection Sort and SortField classes to control the order of the rows.

• 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.

  For detailed information on using the Sort and SortField classes, see Sorting and filtering data for viewing.

<?xml version="1.0"?> 
<!-- dpcontrols/DataGridSort.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    initialize="initDP();" 
    width="550" height="400"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
      
    <fx:Script> 
        <![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(); 
            } 
        ]]> 
    </fx:Script> 
 
    <!-- 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. --> 
    <mx:DataGrid id="myGrid" width="100%" headerRelease="headRelEvt(event);"> 
        <mx:columns> 
            <mx:DataGridColumn minWidth="120" dataField="Artist" /> 
            <mx:DataGridColumn minWidth="200" dataField="Album" /> 
            <mx:DataGridColumn width="75" dataField="Price" /> 
            <mx:DataGridColumn width="75" dataField="InStock" 
               headerText="In Stock"/> 
        </mx:columns> 
    </mx:DataGrid> 
    <mx:VBox> 
        <mx:Label id="tSort0" text="First Sort Field: "/> 
        <mx:Label id="tSort1" text="Second Sort Field: "/> 
        <mx:Label id="tSort2" text="Third Sort Field: "/> 
    </mx:VBox> 
</s:Application>

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 editable properties of the DataGrid control and the DataGridColumn containing the cell are both true. Clicking within an editable cell directs focus to that cell. Clicking a noneditable cell has no effect on the focus.

Users can modify the DataGrid control appearance in the following ways:

• If the value of the sortableColumns property is true, the default value, clicking within a column header causes the DataGrid control to be sorted based on the column's cell values.

• If the value of the draggableColumns property is true, 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.

• If the value of the resizableColumns property is true, the default value, clicking in the area between columns permits column resizing.

A Tree control is a hierarchical structure of branch and leaf nodes. 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.

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.

The following image shows a Tree control:

You define a Tree control in MXML by using the <mx:Tree> tag. The Tree class extends the List class and Tree controls take all of the properties and methods of the List control. For more information about using the List control, see MX List control. Specify an id value if you intend to refer to a control elsewhere in your MXML, either in another tag or in an ActionScript block.

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 ArrayCollection, or XMLListCollection object, as the data provider.

The Tree control uses a data descriptor to parse and manipulate the data provider content. By default, the Tree control uses a DefaultDataDescriptor instance, but you can create your own class and specify it in the Tree control's dataDescriptor property.

The DefaultDataDescriptor class supports the following types of data:

Collections

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.

XML

A string containing valid XML text, or any of the following objects containing valid E4X format XML data: <fx:XML> or <fx:XMLList> compile-time tag, or an XML or XMLList object.

Other objects

An array of items, or an object that contains an array of items, where a node's children are contained in an item named children.

The DefaultDataDescriptor class also supports using an <fx:Model> tag as a data provider for a menu, but all leaf nodes must have the name children; As a general rule, it is a better programming practice to use the <fx:XML> or <fx:XMLList> tags when you need a Tree data provider that uses binding.

For more information on hierarchical objects and data descriptors, including a detailed description of the formats supported by the DefaultDataDescriptor, see Data descriptors and hierarchical data structure.

The following code contains a single Tree control that defines the tree shown in the image in MX Tree control. This uses an XMLListCollection wrapper around an <fx:XMLList> tag. By using an XMLListCollection, you can modify the underlying XML data provider by changing the contents of the MailBox XMLListCollection, and the Tree control will represent the changes to the data. This example also does not use the <mx:dataProvider> tag because dataProvider is the default property of the Tree control.

<?xml version="1.0"?> 
<!-- dpcontrols/TreeSimple.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
   <mx:Tree id="tree1" 
       labelField="@label" 
       showRoot="true" 
       width="160"> 
      <mx:XMLListCollection id="MailBox"> 
         <fx:XMLList> 
            <folder label="Mail"> 
               <folder label="INBOX"/> 
               <folder label="Personal Folder"> 
                  <Pfolder label="Business" /> 
                  <Pfolder label="Demo" /> 
                     <Pfolder label="Personal" isBranch="true" /> 
                     <Pfolder label="Saved Mail" /> 
                  </folder> 
                  <folder label="Sent" /> 
                  <folder label="Trash" /> 
            </folder> 
         </fx:XMLList> 
      </mx:XMLListCollection> 
   </mx:Tree> 
</s:Application>

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 Hierarchical data objects.

Some data providers have a single top level node, called a root 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 showRoot property to false; doing this does not affect the data provider contents, only the Tree display. You can only specify a false showRoot property for data providers that have roots, that is, XML and Object-based data providers.

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.

When a Tree control displays a node of a non-XML data provider, by default, it displays the value of the label 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 labelField property; for example, if the label field is the label attribute, specify labelField="@label".

You typically use events to respond to user interaction with a Tree control. Since the Tree control is derived from the List control, you can use all of the events defined for the List control. The Tree control also dispatches several Event and TreeEvent class events, including Event.change and TreeEvent.itemOpen. The following example defines event handlers for the change and itemOpen events:

Ôªø<?xml version="1.0"?> 
<!-- dpcontrols/TreeEvents.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
   <fx:Script> 
      <![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; 
      } 
   ]]> 
   </fx:Script> 
 
   <mx:Tree id="XMLTree1" width="150" height="170" 
          labelField="@label" itemOpen="itemOpenEvt(event);" 
          change="changeEvt(event);"> 
      <mx:XMLListCollection id="MailBox"> 
         <fx:XMLList> 
            <node label="Mail" data="100"> 
               <node label="Inbox" data="70"/> 
               <node label="Personal Folder" data="10"> 
                  <node label="Business" data="2"/> 
                  <node label="Demo" data="3"/> 
                  <node label="Personal" data="0" isBranch="true" /> 
                  <node label="Saved Mail" data="5" /> 
               </node> 
               <node label="Sent" data="15"/> 
               <node label="Trash" data="5"/> 
            </node> 
         </fx:XMLList> 
      </mx:XMLListCollection> 
   </mx:Tree> 
 
    <s:Form> 
        <s:FormItem label="Change Event:"> 
            <s:Label id="forChange" width="150"/>          
        </s:FormItem> 
        <s:FormItem label="Open Event:"> 
            <s:Label id="forOpen" width="150"/>            
        </s:FormItem> 
    </s:Form> 
</s:Application>

In this example, you define event listeners for the change and itemOpen events. The Tree control broadcasts the change event when the user selects a tree item, and broadcasts the itemOpen 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.

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 expandItem() method of the Tree control. The following change to the example in Handling Tree control events calls the expandItem() method as part of the Tree control's creationComplete event listener to expand the root node of the tree:

 <fx:Script> 
 	<![CDATA[ 
 . 
 . 
 . 
 		private function initTree():void { 
 			XMLTree1.expandItem(MailBox.getItemAt(0), true); 
 			forOpen.text=XMLTree1.openItems[0].@label; 
 		} 
 		]]> 
 	</fx:Script> 
  
 <mx:Tree id="tree1" ... creationComplete="initTree();" > 
 	... 
 </mx:Tree>

This example must use the Tree control's creationComplete event, not the initialize event, because the data provider is not fully initialized and available until the creationComplete event.

The Tree control openItems 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:

 forOpen.text=XMLTree1.openItems[0].@label;

In this example, however, you could also get the openItems box to indicate the initial open item by setting the expandItem() method to dispatch an itemOpen event. You can do this by specifying the fourth, optional parameter of the expandItem() method to true. The true fourth parameter causes the tree to dispatch an open event when the item opens. The following example shows the use of the fourth parameter:

 XMLTree1.expandItem(MailBox.getItemAt(0), true, false, true);

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 children() method of a node's XML object to test whether the node has any children; you can use the expandItem() method to open the node.

The following example opens nodes in the Tree control based on the values of query string parameters. For example, if you pass app_url?0=1&1=2&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).

<?xml version="1.0"?> 
<!-- dpcontrols/DrillIntoTree.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    creationComplete="initApp();"> 
    
    <fx:Script> 
      <![CDATA[ 
        import mx.collections.XMLListCollection; 
        import mx.core.FlexGlobals; 
        
        [Bindable] 
        private var treeData:XML = 
            <root> 
                <node label="Monkeys"> 
                    <node label="South America"> 
                        <node label="Coastal"/> 
                        <node label="Inland"/> 
                    </node> 
                    <node label="Africa" isBranch="true"/> 
                    <node label="Asia" isBranch="true"/> 
                </node> 
                <node label="Sharks"> 
                    <node label="South America" isBranch="true"/> 
                    <node label="Africa" isBranch="true"/> 
                    <node label="Asia" > 
                        <node label="Coastal"/> 
                        <node label="Inland"/> 
                    </node> 
                </node> 
            </root>; 
            
        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&1=2&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 < 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; 
        } 
      ]]> 
    </fx:Script> 
    
    <mx:Tree id="myTree" 
        y="50" 
        width="221" 
        height="257" 
        horizontalCenter="0" 
        dataProvider="{treeData.node}" 
        labelField="@label"/>    
</s:Application>

The Tree control provides four techniques for specifying node icons:

• The folderOpenIcon, folderClosedIcon, and defaultLeafIcon properties

• Data provider node icon fields

• The setItemItcon() method

• The iconFunction property

 <mx:Tree folderOpenIcon="@Embed(source='open.jpg')" 
	folderClosedIcon="@Embed(source='closed.jpg')" 
	defaultLeafIcon="@Embed(source='def.jpg')"> 

<?xml version="1.0"?> 
<!-- dpcontrols/TreeIconField.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Script> 
        <![CDATA[ 
            [Bindable] 
            [Embed(source="assets/radioIcon.jpg")] 
            public var iconSymbol1:Class; 
            [Bindable] 
            [Embed(source="assets/topIcon.jpg")] 
            public var iconSymbol2:Class; 
        ]]> 
    </fx:Script> 
 
   <mx:Tree iconField="@icon" 
       labelField="@label" 
       showRoot="false" 
        width="160"> 
        <fx:XMLList> 
            <node label="New"> 
                <node label="HTML Document" icon="iconSymbol2"/> 
                <node label="Text Document" icon="iconSymbol2"/> 
            </node> 
            <node label="Close" icon="iconSymbol1"/> 
        </fx:XMLList> 
    </mx:Tree> 
</s:Application>

<?xml version="1.0"?> 
<!-- dpcontrols/TreeItemIcon.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
   <fx:Script> 
      <![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); 
         } 
      ]]> 
   </fx:Script> 
 
   <mx:Tree id="myTree" labelField="@label" 
      showRoot="false" 
      width="160" initialize="setIcons();"> 
      <fx:XMLList> 
         <node label="New"> 
            <node label="HTML Document"/> 
            <node label="Text Document"/> 
         </node> 
         <node label="Close"/> 
      </fx:XMLList> 
   </mx:Tree> 
</s:Application>

<?xml version="1.0"?> 
<!-- dpcontrols/TreeOpenNode.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    
    <fx:Script> 
        <![CDATA[ 
            import flash.events.*; 
            import mx.events.*; 
            import mx.controls.*; 
            private function initTree():void { 
 
                XMLTree1.expandItem(MailBox.getItemAt(0), true); 
                XMLTree1.selectedIndex = 2; 
            } 
        ]]> 
    </fx:Script> 
 
    <mx:Tree id="XMLTree1" 
        width="150" height="170" 
        labelField="@label" 
        creationComplete="initTree();"> 
        <mx:XMLListCollection id="MailBox"> 
            <fx:XMLList> 
                <node label="Mail" data="100"> 
                    <node label="Inbox" data="70"/> 
                    <node label="Personal Folder" data="10"> 
                        <node label="Business" data="2"/> 
                        <node label="Demo" data="3"/> 
                        <node label="Saved Mail" data="5" /> 
                    </node> 
                    <node label="Sent" data="15"/> 
                    <node label="Trash" data="5"/> 
                 </node> 
            </fx:XMLList> 
        </mx:XMLListCollection> 
    </mx:Tree> 
</s:Application>

<?xml version="1.0"?> 
<!-- dpcontrols/TreeAddRemoveNode.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.collections.XMLListCollection; 
            
            [Bindable] 
            private var company:XML = 
              <list> 
                <department title="Finance" code="200"> 
                    <employee name="John H"/> 
                    <employee name="Sam K"/> 
                </department> 
                <department title="Operations" code="400"> 
                    <employee name="Bill C"/> 
                    <employee name="Jill W"/> 
                </department>                    
                <department title="Engineering" code="300"> 
                    <employee name="Erin M"/> 
                    <employee name="Ann B"/> 
                </department>                                
              </list>; 
              
            [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 = <employee/>; 
                newNode.@name = empName.text; 
                var dept:XMLList =company.department.(@title == "Operations"); 
                if( dept.length() > 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 < children.length(); i++) { 
                    if( children[i].@name == node.@name ) { 
                        delete children[i]; 
                    } 
                } 
            } 
        ]]> 
    </fx:Script> 
    
    <mx:Tree id="tree" 
        top="72" left="50" 
        dataProvider="{companyData}" 
        labelFunction="treeLabel" 
        height="225" width="300"/> 
    
    <mx:VBox> 
        <mx:HBox>           
            <mx:Button label="Add Operations Employee" click="addEmployee();"/> 
            <mx:TextInput id="empName"/>            
        </mx:HBox> 
        <mx:Button label="Remove Selected Employee" click="removeEmployee();"/>                     
    </mx:VBox> 
</s:Application>

You can let users edit tree control labels. The controls also support several keyboard navigation and editing keys.