Flex supports several controls that you can use to represent lists of items. These controls let the application user scroll through the item list and select one or more items from the list. All Flex list components are derived from the ListBase class, and include the following controls:

• DataGrid
• HorizontalList
• List
• Menu
• MenuBar
• TileList
• Tree

A list control gets its data from a data provider. A data provider is a collection that contains a data object such as an Array or XMLList object. For example, a Tree control reads data from a data provider to define the structure of the tree and any associated data that is assigned to each tree node. Collections are objects that contain a set of methods that let you access, sort, filter, and modify the data items in a data object. The standard collection types are the ArrayCollection and XMLListCollection classes, for working with Array-based and XMLList-based data, respectively.

Collections provide a level of abstraction between Flex components and the data that you use to populate them. You can populate multiple components from the same collection, switch the collection that a component uses as a data provider at run time, or modify a collection so that changes are reflected by all components that use it as a data provider.

You can think of the data provider as the model, and the Flex components as the view of the model. By separating the model from the view, you can change one without changing the other. Each list control has a default mechanism for controlling the display of data, or view, and lets you override that default. To override the default view, you create a custom item renderer.

In addition to controlling the display of data using an item renderer, the DataGrid, List, and Tree controls let users edit the data. For example, you could let users update the Quantity column of a DataGrid control if you are using it for a shopping cart. As with the display of data, the list controls have a default mechanism for letting users edit data that you can override by creating a custom item editor.

Default item rendering and cell editing

Each list-based control has a default item renderer defined for it. The simplest item renderer is the DataGridItemRenderer class, which defines the item renderer for the DataGrid control. This item renderer assumes that each element in a data provider is a text string.

Other item renderers include the ListItemRenderer, MenuItemRenderer, MenuBarItem, TileListItemRenderer, and TreeItemRenderer. By default, these item renderers combine an image with text.

For example, the following image shows a List control that displays three items using its default item renderer:

In this example, the List control uses the default item renderer to display each of the three strings that represent postal codes for Alaska, Alabama, and Arkansas. You use the following code to create this List control:

<?xml version="1.0"?>
<!-- itemRenderers\list\ListDefaultRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:List width="50" height ="75"> 
        <mx:dataProvider>
            <mx:String>AK</mx:String>
            <mx:String>AL</mx:String>
            <mx:String>AR</mx:String>
        </mx:dataProvider>
    </mx:List>
</mx:Application>
The executing SWF file for the previous example is shown below:

Because the data in this example is inline static data, it is not necessary to explicitly wrap it in an ArrayCollection instance. However, when you work with data that could change, it is always best to specify a collection explicitly; for more information, see Using Data Providers and Collections.

In the next example, the data provider for the DataGrid control contains fields for an artist, album name, and price. Each of these fields appears in the DataGrid control using the default item renderer, which displays data as text.

The following code creates the example shown in the previous image:

<?xml version="1.0"?>
<!-- itemRenderers\dataGrid\DGDefaultRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
    
    <mx:Script>
        <![CDATA[
          import mx.collections.ArrayCollection;
        
          [Bindable]
          private var initDG:ArrayCollection = new ArrayCollection([
            {Artist:'Pavement', Album:'Slanted and Enchanted', Price:11.99},
            {Artist:'Pavement', Album:'Brighten the Corners', Price:11.99}
          ]);            
        ]]>
    </mx:Script>

    <mx:Panel paddingTop="10" paddingBottom="10" 
        paddingLeft="10" paddingRight="10">

        <mx:DataGrid id="myGrid" dataProvider="{initDG}" 
            width="100%" editable="true"> 
            <mx:columns>
                <mx:DataGridColumn dataField="Artist" resizable="true"/>
                <mx:DataGridColumn dataField="Album" resizable="true"/>
                <mx:DataGridColumn dataField="Price" resizable="true"/>
            </mx:columns>       
        </mx:DataGrid>  
    </mx:Panel>    
</mx:Application>
The executing SWF file for the previous example is shown below:

An editable component lets the user modify the data in the list control, and propagates the changes in the data back to the underlying data provider of the control. The DataGrid, List, and Tree controls have a property named editable that, if set to true, lets you edit the contents of a cell. By default, the list controls use a TextInput control as the item editor. That means when you select a cell in the list control, Flex opens a TextInput control that contains the current contents of the cell and lets you edit it, as the following image shows:

In this image, you use the default item editor to edit the price of the first album in the DataGrid control.

For more information on item editors, see Working with Item Editors.

Using custom item renderers and item editors

To control the display of a list component, you write a custom item renderer or custom item editor. Your custom item renderers and item editors still use the underlying functionality of the list control, but let you control the display and editing of the data. Custom item renderers and item editors provide you with several advantages:

• You can create a more compelling user interface by replacing the display of text with a more user-intuitive appearance.
• You can combine multiple elements in a single list item, such as a label and an image.
• You can programmatically control the display of the data.

The following List control is a modification of the List control in the section Default item rendering and cell editing. In this example, you use a custom item renderer to display the state name, capital, and a URL to the state's official website in each list item:

For the code for this example, see Example: Using an item renderer with a List control.

In the next image, you use a default item renderer for the first and third columns of the DataGrid control. You use a custom item renderer for the second column to display the album cover along with the album title in the DataGrid control.

For the code for this example, see Creating a complex inline item renderer or item editor.

Just as you can define a custom item renderer to control the display of a cell, you can use a custom item editor to edit the contents of the cell. For example, if the custom item renderer displays an image, you could define a custom item editor that uses a ComboBox control that lets users select an image from a list of available images. Or you could use a CheckBox control to let the user set a true or false value for a cell, as the right side of the following example shows:

For the code for this example, see Creating a simple item editor component.

Using an item renderer does not imply that the control also has an item editor. Often, you do not allow your controls to be edited; that is, they are for display only.

You can also use an item editor without a corresponding item renderer. For example, you could display information such as a male/female or true/false as text using the default item renderer. But, you could then use a custom item editor with a ComboBox control that provides the user only a limited set of options to enter into the cell when changing the value.

Item renderer and item editor architecture

In order for an item renderer or item editor to work with the contents of a list control, the list control must be able to pass information to the item renderer or item editor. An item editor must also be able to pass updated information back to the list control.

The following image shows the relationship of a list control to an item renderer or item editor:

To pass information to an item renderer or item editor, Flex sets the data property of the item renderer or item editor to the cell data. In the previous image, you can see the data property that is used to pass the data to the item renderer or item editor.

By default, an item editor can pass back a single value to the list control that becomes the new value of the edited cell. To return more than one value, you must write additional code to return the data back to the list control. For more information, see Example: Passing multiple values back from an item editor.

Any Flex component that you want to use in an item renderer or item editor, and that requires access to the cell data of the list control, must implement the IDataRenderer interface to support the data property. You can use additional components in an item renderer that do not support the data property, if those components do not need to access data passed from the list control.

The contents of the data property depend on the type of control, as the following table shows:

For more information about item editors, see Working with Item Editors.

About item renderer and item editor interfaces

The Flex item renderer and item editor architecture is defined by several interfaces. Flex components that you can use as item renderers and item editors implement one or more of these interfaces. If you create your own custom component to use as an item renderer or item editor, your component must implement one or more of these interfaces, depending on how you intend to use it.

The following table describes the interfaces that you use with item renderers and item editors:

Application layout with item renderers and item editors

All list controls, with the exception of the TileList and HorizontalList controls, ignore item renderers when calculating the default height and width of their contents. By default, item renderers are sized to the full width of a control, or the width of the column for a DataGrid control. Therefore, if you define a custom item renderer that requires a size other than its default, you should explicitly size the control.

Vertical controls such as the List and Tree controls use the rowHeight property to determine the default cell height. You can also set the variableRowHeight property to true if each row has a different height. Otherwise, Flex sets the height of each cell to 20 pixels.

For the HorizontalList control, Flex can use the value of the columnWidth property, if specified. For the TileList control, Flex uses the values of the columnWidth and rowHeight properties. If you omit these properties, Flex examines the control's data provider to determine the default size of each cell, including an item renderer, if specified. Otherwise, Flex sets the height and width of each cell to 50 pixels.