Chapter 22: Using Item Renderers and Item Editors--Creating drop-in item renderers and item editors

Several Flex controls are designed to work as item renderers and item editors. This lets you specify these controls
as values of the itemRenderer or itemEditor property. When you specify one of these controls as a property
value, it is called a drop-in item renderer or drop-in item editor.
To use a component as a drop-in item renderer or drop-in item editor, a component must implement the IDropIn-
ListItemRenderer interface. The following controls implement the IDropInListItemRenderer interface, making
them usable directly as a drop-in item renderer or drop-in item editor:



• Button
• CheckBox
• DateField
• Image
• Label
• NumericStepper
• Tex t
• Tex tAre a
• Tex t Input
You can define your own components for use as drop-in item renderers or drop-in item editors. The only
requirement is that they, too, implement the IDropInListItemRenderer interface.

Using drop-in item renderers and item editors
When you use a control as a drop-in item renderer, Flex sets the control’s default property to the current value of
the cell. When you use a control as an item editor, the initial value of the cell becomes the current value of the
control. Any edits made to the cell are copied back to the data provider of the list control.

Control	Default property	Notes
Button	selected	Cannot specify a label for the Button control.
CheckBox	selected	If used as a drop-in item renderer in a Tree control, the Tree displays only check boxes with no text.
DateField	selectedDate	Requires that the data provider of the list control has a field of type Date.
Image	source	Set an explicit row height by using the rowHeight property, or set the variableRowHeight property to true to size the row correctly.
Label	text
NumericStepper	value
Text	text
TextArea	text
TextInput	text

In the following example, you use the NumericStepper, DateField, and CheckBox controls as the drop-in item
renderers and item editors for a DataGrid control:

<?xml version="1.0"?>
<!-- itemRenderers/inline/CBInlineCellEditor.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <mx:Script>
        <!--[CDATA[
            import mx.collections.ArrayCollection;
        
            [Bindable]                
            private var myDP:ArrayCollection = new ArrayCollection([
                {label1:"Order #2314", contact:"John Doe", 
                    quant:3, solddate:new Date(2005, 0, 1), Sent:true},
                {label1:"Order #2315", contact:"Jane Doe", 
                    quant:3, solddate:new Date(2005, 0, 5), Sent:false}
            ]);
        ]]-->
    </mx:Script>
    <mx:DataGrid id="myDG" 
            dataProvider="{myDP}" 
            variableRowHeight="true" 
            width="500" height="250" 
            editable="true">
        <mx:columns>
            <mx:DataGridColumn dataField="label1" 
                headerText="Order #" 
                editable="false"/>
            <mx:DataGridColumn dataField="quant" 
                headerText="Quantity" 
                itemEditor="mx.controls.NumericStepper"  
                editorDataField="value"/>
            <mx:DataGridColumn dataField="solddate" 
                headerText="Date"  
                itemRenderer="mx.controls.DateField" 
                rendererIsEditor="true" 
                editorDataField="selectedDate"/>
            <mx:DataGridColumn dataField="Sent" 
                itemRenderer="mx.controls.CheckBox" 
                rendererIsEditor="true" 
                editorDataField="selected"/>
        </mx:columns >
    </mx:DataGrid>  
</mx:Application>

To determine the field of the data provider used to populate the drop-in item renderer, Flex uses the value of the
dataField property for the <mx:DataGridColumn> tag. In this example, you do the following:
• You s e t t he dataField property of the second column to quant, and define the NumericStepper control as
the item editor. Therefore, the column displays the cell value as text, and opens the NumericStepper control when
you select the cell to edit it. The NumericStepper control displays the current value of the cell, and any changes
you make to it are copied back to the data provider of the DataGrid control.
• You set the dataField property of the third column to solddate, and define the DateField control as the item
renderer and item editor by setting the rendererIsEditor property to true. The data provider defines the data
as an object of type Date, which is required to use the DateField control as the item renderer or item editor.
Therefore, the column displays the date value using the DateField control, and also uses the DateField control to
edit the cell value.
• You s e t t he dataField property of the fourth column to Sent, and define the CheckBox control as the item
renderer and item editor. Typically, you use itemEditor property to specify a different class as the item editor,
and specify to use the same control as both the item renderer and item editor by setting the rendererIsEditor
property to true. The CheckBox control displays a check mark in the cell if the Sent field for the row is set to true,
and an empty check box if the field is set to false.



For more information on using an item renderer as an item editor, see “Creating an editable cell” on page 822.
Note: When you use a CheckBox control as a drop-in item renderer, the control appears flush against the left cell
border. To center a CheckBox control, or any drop-in item renderer, create a custom item renderer that wraps the
control in a container, such as the HBox container. However, the addition of the container can affect application
performance when you are rendering large amounts of data. For more information, see “Creating item renderers and
item editor components” on page 807.
When you use the Image control as a drop-in item renderer, you usually have to set the row height to accom-
modate the image, as the following example shows:

<?xml version="1.0"?>
<!-- itemRenderers/DGDropInImageRenderer.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, Cover:'../assets/slanted.jpg'},
                {Artist:'Pavement', Album:'Brighten the Corners', 
                    Price:11.99, Cover:'../assets/brighten.jpg'}
            ]);
        ]]-->
    </mx:Script>
    <mx:DataGrid id="myGrid" dataProvider="{initDG}" rowHeight="50">    
        <mx:columns>
            <mx:DataGridColumn dataField="Artist"/>
            <mx:DataGridColumn dataField="Album"/>
            <mx:DataGridColumn dataField="Cover" 
                itemRenderer="mx.controls.Image"/>
            <mx:DataGridColumn dataField="Price"/>
        </mx:columns>       
    </mx:DataGrid>      
</mx:Application>

In this example, you use the Image control to display the album cover in a cell of the DataGrid control.
Requirements of a drop-in item renderer in a List control
When you use the itemRenderer property of the List control to specify a drop-in item renderer, the data in the
data provider must be of the type expected by the item renderer control. For example, if you use an Image control
as a drop-in item renderer, the data provider for the List control must have String data in the field.