Chapter 22: Using Item Renderers and Item Editors--About item renderers

You can customize the appearance and behavior of cells in list-based data provider controls that you use in Adobe 
Flex applications, including the DataGrid, HorizontalList, List, Menu, MenuBar, TileList, and Tree controls. To 
control the appearance of cells in list controls, you create custom item renderers and item editors.
About item renderers
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 DataGridItem-
Renderer 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:
<span style="font-family: "symbol";"><?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></span>

   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; 
   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:

<span style="font-family: "symbol";"><?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></span>

 

   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.

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– on page 780. In this example, you use a custom item renderer to display the state name, capital, and a URL 
to the states official website in each list item：

 

 

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

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– on page 802.

 

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– on page 810.
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 infor-
mation 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 infor-
mation 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– on page 840.
    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:

Control

Contents of the data property

DataGrid 

Contains the data provider element for the entire row of the DataGrid control. That means if you use a 

different item renderer for each cell of the DataGrid control, each cell in a row receives the same information in the data property.

Tree 

List 

Contains the data provider element for the node of the List or Tree control.

HorizontalList 

TileList

Contains the data provider element for the cell.

Menu 

Contains the data provider element for the menu item.

MenuBar 

Contains the data provider element for the menu bar item. 

 

---

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 inter-
faces, depending on how you intend to use it.

 

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

 

Interface

Use

IDataRenderer

Defines the data property used to pass information to an item renderer or item editor. All item renderers and item editors must implement this interface.

Many Flex components implement this interface, such as the chart renderer classes and many Flex controls. 

IDropInListItemRenderer

Defines the listData property required by drop-in item renderers and item editors. All drop-in item
renderers and item editors must implement this interface.
The listData property is of type BaseListData, where the BaseListData class has three subclasses:  
DataGridListData, ListData, TreeListData. The actual data type of the value of the depends on the control using the drop-in item renderer or item editor. For a DataGrid control, the value is of type DataGridListData; for a List control, the value is of type ListData; and for a Tree control, the 
value is of type TreeListData.

IListItemRenderer

Defines the complete set of interfaces that an item renderer or item editor must implement to be used with any Flex control other than a Chart control.

 A renderer for a Chart control has to implement only the IDataRenderer interface.

The set of interfaces includes the following:

IDataRenderer, IFlexDisplayObject, ILayoutClient, IStyleable, and IUIComponent. 

The UIComponent class implements all of these interfaces, except the IDataRenderer interface. Therefore, if you create a custom item renderer or item editor

 as a subclass of the UIComponent class, you have to implement only the IDataRenderer interface. If you implement a drop-in item renderer or item editor as a subclass of the UIComponent class, you have to implement only the IDataRenderer and IDropInListItemRenderer interfaces. 

---

Application layout with item renderers and item editors

    All list controls, with the exception of the TileList and HorizontalList controls, ignore item renderers when calcu-
lating 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 controls 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.