by Adobe

adobe_logo_bio

Created

22 March 2010

Requirements
User level
All
MX item editors let you modify the value of a cell of an MX list-based control. The MX DataGrid, List, and Tree controls support item editors.
 
Link: Adobe Flex also supports item renderers for customizing how components display data. For more information, see Using MX item renderers in the Quick Start tutorials.
 
The MX DataGrid, List, and Tree controls include an editable property that you set to true to let users edit the contents of the control. By default, the value of the editable property is false, which means that you cannot edit the cells.
 
There are various ways of creating and using MX item renderers:
 

 
Using the default MX item editor

By default, Flex MX components expects an item editor to return a single value to the list control. You use the editorDataField property of the list control to specify the property of the item editor that contains the new data. Flex converts the value to the appropriate data type for the cell.
 
The default MX item editor is an mx.controls.TextInput control. Therefore, the default value of the editorDataField property is text, which corresponds to the text property of the MX TextInput control.
 
The following example contains an MX DataGrid control that has its editable property set to true. This example doesn't define a custom item editor, so the DataGrid uses the default item editor. Users can modify the values in each of its fields by clicking a cell and editing the displayed value in the TextInput control.
 
Tip: For an MX DataGrid control, setting the editable property to true enables editing for all columns of the grid. You can disable editing for any column by setting the editable property of the DataGridColumn instance to false.
 
 
Example
Data model (artwork.xml)
 
<artwork> <piece> <name>The Wall</name> <image>artwork1.jpg</image> <price>250</price> <quantity>5</quantity> </piece> <piece> <name>Blue Flake</name> <image>artwork5.jpg</image> <price>400</price> <quantity>2</quantity> </piece> <piece> <name>Butterfly</name> <image>artwork6.jpg</image> <price>375</price> <quantity>17</quantity> </piece> </artwork>
MXML file
 
<?xml version="1.0" encoding="utf-8"?> <!-- ItemEditorDefault.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" height="140"> <fx:Declarations> <fx:Model id="artwork" source="model/artwork.xml"/> </fx:Declarations> <mx:DataGrid rowCount="4" dataProvider="{artwork.piece}" editable="true"/> </s:Application>

 
Using an MX drop-in item editor

The simplest way to use custom MX item editors is to use a drop-in item editor. A drop-in item editor is a Flex MX component that you specify as the value of the itemEditor property of a list-based control such as the MX List, Tree, ComboBox or DataGrid controls. For example, you can use an MX NumericStepper control to edit a field of an MX DataGrid control.
 
To use a component as a drop-in item editor, a component must implement the IDropInListItemRenderer interface. The following MX 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, Text, TextArea, and TextInput.
 
You can define your own components to use as drop-in item editors. The only requirement is that they, too, implement the IDropInListItemRenderer interface.
 
In the following example, you use the MX NumericStepper control as a drop-in item editor to give the user an easy way of altering the quantity field of the DataGrid control. You must click on a cell in the Quantity column to enable the item editor. This example also uses an MX Image control as an item renderer to display thumbnail images of the artwork.
 
Tip: The example uses the editorXOffset, editorYOffset, editorWidthOffset and editorHeightOffset properties of the DataGridColumn object to size and position the NumericStepper control in the middle of the cell.
 
 
Example
Data model (artwork.xml)
 
<artwork> <piece> <name>The Wall</name> <image>assets/artwork1.jpg</image> <price>250</price> <quantity>5</quantity> </piece> <piece> <name>Blue Flake</name> <image>assets/artwork5.jpg</image> <price>400</price> <quantity>2</quantity> </piece> <piece> <name>Butterfly</name> <image>assets/artwork6.jpg</image> <price>375</price> <quantity>17</quantity> </piece> </artwork>
MXML files
 
<?xml version="1.0" encoding="utf-8"?> <!-- ItemEditorDropIn.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="470" height="340"> <s:layout> <s:VerticalLayout/> </s:layout> <fx:Declarations> <fx:Model id="artwork" source="model/artwork.xml"/> </fx:Declarations> <mx:DataGrid id="artGrid" rowCount="10" variableRowHeight="true" dataProvider="{artwork.piece}" editable="true"> <mx:columns> <!-- Drop-in item renderer: Image control --> <mx:DataGridColumn dataField="image" headerText="Image" itemRenderer="mx.controls.Image"/> <mx:DataGridColumn headerText="Name" dataField="name"/> <mx:DataGridColumn headerText="Price" dataField="price"/> <!-- Drop-in item editor: NumericStepper control --> <mx:DataGridColumn headerText="Quantity" dataField="quantity" itemEditor="mx.controls.NumericStepper" editorDataField="value" editorXOffset="22" editorYOffset="25" editorWidthOffset="-40" editorHeightOffset="-50"/> </mx:columns> </mx:DataGrid> <mx:LinkButton textAlign="center" label="Photos (c) 2006 geishaboy500 (CC Attribution License)" click="{navigateToURL(new URLRequest(&apos;http://www.flickr.com/photos/geishaboy500/&apos;));}"/> <fx:Script> <![CDATA[ import flash.net.navigateToURL; ]]> </fx:Script> </s:Application>

 
Creating an MX inline item editor

MX drop-in item editors are very easy to use but their major drawback is that you cannot configure them. To create more flexible item editors, you can develop your item editor as an inline component by using the <fx:Component> tag.
 
In the following example, you create an inline item editor that contains an MX NumericStepper control. The example uses an inline item editor, so you can configure the NumericStepper by setting its maximum and stepSize properties.
 
 
Example
Data model (artwork.xml)
 
<artwork> <piece> <name>The Wall</name> <image>artwork1.jpg</image> <price>250</price> <quantity>5</quantity> </piece> <piece> <name>Blue Flake</name> <image>artwork5.jpg</image> <price>400</price> <quantity>2</quantity> </piece> <piece> <name>Butterfly</name> <image>artwork6.jpg</image> <price>375</price> <quantity>17</quantity> </piece> </artwork>
MXML file
 
<?xml version="1.0" encoding="utf-8"?> <!-- ItemEditorInline.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="525" height="525"> <s:layout> <s:VerticalLayout/> </s:layout> <fx:Declarations> <fx:Model id="artwork" source="model/artwork.xml"/> </fx:Declarations> <mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{artwork.piece}" editable="true"> <mx:columns> <!-- Inline item renderer: Image control --> <mx:DataGridColumn dataField="image" headerText="Image" width="150" editable="false"> <mx:itemRenderer> <fx:Component> <mx:VBox width="100%" height="140"> <mx:Image source="{data.image}"/> <s:Label text="{data.image}" /> </mx:VBox> </fx:Component> </mx:itemRenderer> </mx:DataGridColumn> <mx:DataGridColumn headerText="Name" dataField="name"/> <mx:DataGridColumn headerText="Price" dataField="price"/> <!-- Inline item editor: NumericStepper --> <mx:DataGridColumn headerText="Quantity" dataField="quantity" editorDataField="value"> <mx:itemEditor> <fx:Component> <mx:NumericStepper maximum="100" stepSize="1"/> </fx:Component> </mx:itemEditor> </mx:DataGridColumn> </mx:columns> </mx:DataGrid> <mx:LinkButton textAlign="center" label="Photos (c) 2006 geishaboy500 (CC Attribution License)" click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"/> <fx:Script> <![CDATA[ import flash.net.navigateToURL; ]]> </fx:Script> </s:Application>

 
Creating a reusable MX inline item editor

Rather than defining an inline item editor in the definition of a component, you can define a reusable inline item editor for use in multiple locations in your application. You create reusable inline item editors by using the <fx:Component> tag, setting your inline component's id property, and binding the itemEditor property of your control to your inline component's id property.
 
Even if you do use an item editor more than once, using reusable inline item editors results in code that is easier to maintain because you can group all your item editors in a single place in your MXML document.
 
In this example, you create a reusable item editor that uses an MX NumericStepper control.
 
 
Example
Data model (artwork.xml)
 
<artwork> <piece> <name>The Wall</name> <image>artwork1.jpg</image> <price>250</price> <quantity>5</quantity> </piece> <piece> <name>Blue Flake</name> <image>artwork5.jpg</image> <price>400</price> <quantity>2</quantity> </piece> <piece> <name>Butterfly</name> <image>artwork6.jpg</image> <price>375</price> <quantity>17</quantity> </piece> </artwork>
MXML file
 
<?xml version="1.0" encoding="utf-8"?> <!-- ItemEditorReusable.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="525" height="525"> <s:layout> <s:VerticalLayout/> </s:layout> <fx:Declarations> <fx:Model id="artwork" source="model/artwork.xml"/> <!-- Reusable inline item editor --> <fx:Component id="NumericStepEditor"> <mx:NumericStepper maximum="100" stepSize="1"/> </fx:Component> <!-- Reusable inline item renderer --> <fx:Component id="ImageRenderer"> <mx:VBox width="100%" height="140"> <mx:Image source="{data.image}"/> <s:Label text="{data.image}"/> </mx:VBox> </fx:Component> </fx:Declarations> <mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{artwork.piece}" editable="true"> <mx:columns> <mx:DataGridColumn dataField="image" headerText="Image" width="150" itemRenderer="{ImageRenderer}" editable="false"/> <mx:DataGridColumn headerText="Name" dataField="name"/> <mx:DataGridColumn headerText="Price" dataField="price"/> <mx:DataGridColumn headerText="Quantity" dataField="quantity" itemEditor="{NumericStepEditor}" editorDataField="value"> </mx:DataGridColumn> </mx:columns> </mx:DataGrid> <mx:LinkButton textAlign="center" label="Photos (c) 2006 geishaboy500 (CC Attribution License)" click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"/> <fx:Script> <![CDATA[ import flash.net.navigateToURL; ]]> </fx:Script> </s:Application>

 
Using an MX component as an item editor

It is easier to create maintainable and scalable applications if you break them into multiple smaller, well-encapsulated pieces. In Flex, you can follow such a modular workflow by using custom components.
 
One way of defining custom components in Flex is by using MXML. A custom component has its own MXML document in which the root tag may be any Flex component other than the Application container.
 
In the following example, you extract the reusable inline item renderer containing the MX Image and MX Label controls and the reusable inline item editor containing the MX NumericStepper control into their own MXML documents, making them custom components.
 
To use a custom component as an MX item renderer, you specify its name as the value for another control's itemRenderer property. Similarly, to use a custom component as an item editor, you specify its name as the value for another control's itemEditor property.
 
Note: With reusable inline item editor you use data binding to bind a control to the item renderer. When you use a component as an item editor, you do not use data binding but specify the name of the custom component to use as an item editor.
 
 
Example
NumericStepEditor.mxml component
 
<?xml version="1.0" encoding="utf-8"?> <!-- NumericStepEditor.mxml --> <mx:VBox 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[ // Expose the editor's value public function get newQuantity ():uint { return myStepper.value; } ]]> </fx:Script> <mx:NumericStepper id="myStepper" maximum="100" stepSize="1" value="{data.quantity}" /> </mx:VBox>
ImageRenderer.mxml component
 
<?xml version="1.0" encoding="utf-8"?> <!-- ImageRenderer.mxml --> <mx:VBox 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="100%" height="140"> <mx:Image source="{data.image}"/> <s:Label text="{data.image}"/> </mx:VBox>
Main application file
 
<?xml version="1.0" encoding="utf-8"?> <!-- ItemRendererComponent.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="525" height="525"> <s:layout> <s:VerticalLayout/> </s:layout> <fx:Declarations> <fx:Model id="artwork" source="model/artwork.xml"/> </fx:Declarations> <mx:DataGrid rowCount="3" variableRowHeight="true" dataProvider="{artwork.piece}" editable="true"> <mx:columns> <!-- Use the ImageRenderer custom component as an item renderer --> <mx:DataGridColumn dataField="image" headerText="Image" width="150" itemRenderer="ImageRenderer" editable="false"/> <mx:DataGridColumn headerText="Name" dataField="name"/> <mx:DataGridColumn headerText="Price" dataField="price"/> <!-- Use the NumericStepEditor custom component as an item editor. --> <mx:DataGridColumn headerText="Quantity" dataField="quantity" itemEditor="NumericStepEditor" editorDataField="newQuantity"> </mx:DataGridColumn> </mx:columns> </mx:DataGrid> <mx:LinkButton textAlign="center" label="Photos (c) 2006 geishaboy500 (CC Attribution License)" click="{navigateToURL(new URLRequest('http://www.flickr.com/photos/geishaboy500/'));}"/> <fx:Script> <![CDATA[ import flash.net.navigateToURL; ]]> </fx:Script> </s:Application>

 
For more information