Using Flash Builder 4 to create Spark item renderers
Created
22 November 2010
Requirements
Prerequisite knowledge
Familiarity with Flex item renderers, Spark, and Flash Builder will be helpful.
User level
Intermediate
Required products
- Flash Builder 4 (Download trial)
- Flex 4.1 SDK
Item renderers play a significant role in building engaging Flex applications. Item renderers enable developers to customize how data is rendered by List-based components. In Flex 4 the item renderer infrastructure has evolved as part of the introduction of the Spark component and skinning architecture. Because of this, item renderers in Spark are much more intuitive and robust. Additionally, Flash Builder 4 now provides a workflow to generate custom item renderers for a supported set of Spark and MX components.
In this article, I'll detail the changes made to item renderers in Spark and how you can make use of them effectively. As part of this, I will also walk through the new-wizard based Flash Builder 4 workflow for generating item renderers.
Overview of changes to item renderers in Flex 4/Spark
Several design goals underpinned the rethinking of Spark item renderers:
- Improve performance of the default item renderer.
- Improve performance and usability when the developer creates an item renderer and does not want to worry about the selection/rollover background.
- Improve performance and usability when the developer creates an item renderer and wants to change the selection shape or color with hard-coded or stylable values.
- Make it easier to develop custom item renderers.
To achieve these objectives (among others) the following changes were made in Flex 4/Spark item renderers:
- All of the visuals—including rollover and selection of the renderer—are now specified in the renderer itself and are not drawn by the component.
- When you set the
autoDrawBackgroundproperty on an item renderer totrue(its default value) the background will be handled automatically for you. (It basically performsgraphics.drawRect()behind the scenes.) To completely control the background color of an item renderer, set theautoDrawBackgroundproperty tofalse—then your item renderer will be responsible for displaying the background colors for all user interactions, such as selection and hovering. - The MXItemRenderer class (the base class for the MX component item renderer) is built on the Spark item renderer and therefore has
autoDrawBackgroundset totrue. The MXItemRenderer class is a convenience class, which allows you to use Spark-like item renderers with MX components. For example, the MX Tree and MX DataGrid components are not yet part of the Spark component architecture and thus have a different contract for item renderers. You can use the MXItemRenderer class to create Spark-like item renderers for use with the MX Tree or MX DataGrid controls. MXItemRenderer extends ItemRenderer, intercepts lifecycle events, and overrides the setting of ItemRenderer properties to handle the padding MX List-based components put around the renderer so that the states used by the renderer match the backgrounds being displayed under the renderer.
Flash Builder 4 item renderer support
Flash Builder 4 now provides support for creating and editing item renderers directly for a supported set of MX components (Tree, DataGrid and AdvancedDataGrid) and all Spark components that use item renderers. The primary intent is to help beginners jumpstart the creation of a basic, boiler-plate custom item renderer.
You can trigger this workflow from Design view, Source view, the File menu, or the Property Inspector.
From Design view
In Design view, when you right-click (Windows) or Control-click (Mac OS X) on a component that supports the itemRenderer property, Flash Builder displays a context menu item from which you can select Create Item Renderer (see Figure 1).
When you select Create Item Renderer, the New MXML Item Renderer dialog box will appear (see Figure 2).
Simply select a package, type a name for the item renderer, and click Finish. Flash Builder will generate the external item renderer code in the package you specify (see Figure 3).
To customize the template that is used to generate the custom item renderer file, choose Window > Preferences, select Flash Builder > File Templates, expand the MXML file type, and select Item Renderer for Spark Components.
Once you have an item renderer configured, you can open its source code by selecting the component in Design view, and selecting Open Item Renderer Declaration from the context menu (see Figure 4).
If you have an MX DataGrid or AdvancedDataGrid component, you can create or select an item renderer for it by selecting it and clicking Configure Columns in the Property Inspector. The Configure Columns dialog box (see Figure 5) has an Item Renderer option where you can select an existing item renderer; you can also click the button to the right to create a new item renderer.
From Source view
In Source view the Content Assist feature of Flash Builder 4 enables you to select an existing item renderer or create a new one when you add an itemRenderer property to a component that supports it (see Figure 6).
If you select an existing item renderer its name will be inserted in the code. If you select Create Item Renderer, you can use the New MXML Item Renderer dialog box to define a new one.
From the File menu
You can also create a new item renderer by choosing File > New > Other and selecting MXML Item Renderer (see Figure 7).
Alternatively, you can choose File > New > MXML Item Renderer (see Figure 8).
From the Property Inspector
From the Property Inspector (in Standard view), click the icon to the right of the Item Renderer setting to create a new item renderer (see Figure 9). If an item renderer has already been defined for the component, you will also see an option to open the item renderer declaration.
In Alphabetical view, the Value field for the property itemRenderer will display the associated item renderer for the selected component (see Figure 10).
Customizing your item renderer
The basic custom item renderer you generated (see Figure 3) will draw a highlight (or selection) background rectangle by default. To customize the appearance of the item renderer on selection or scroll you need to use states and set the autoDrawBackground property to false ; for example:
<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer focusEnabled="false"
xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark"
autoDrawBackground="false">
<s:states>
<s:State name="normal" />
<s:State name="hovered" />
<s:State name="selected" />
<s:State name="normalAndShowsCaret" stateGroup="caretStates" />
<s:State name="hoveredAndShowsCaret" stateGroup="caretStates"/>
<s:State name="selectedAndShowsCaret" stateGroup="caretStates"/>
</s:states>
<s:Rect left="0" right="0" top="0" bottom="0">
<s:stroke.caretStates>
<s:SolidColorStroke
color="0xFF0000"
weight="1"/>
</s:stroke.caretStates>
<s:fill>
<s:SolidColor
color.normal="0xFFFFFF"
color.normalAndShowsCaret="0xFFFFFF"
color.hovered="0x00FF00"
color.hoveredAndShowsCaret="0x00FF00"
color.selected="0x0000FF"
color.selectedAndShowsCaret="0x0000FF"
/>
</s:fill>
</s:Rect>
<s:Label id="labelDisplay"
verticalCenter="0" left="3" right="3" top="6" bottom="4"
color.hovered="green" color.selected="red"/>
</s:ItemRenderer>
Once you’ve done this, you can handle the visuals of the item renderer yourself. This involves creating MXML graphics to visually present the change as the item renderer enters and exits its default states or custom states you define.
Where to go from here
The changes made to the Flex 4 item renderer are designed to be simple and easy to follow. See the Flash Builder documentation on the Item Renderer workflow for help in getting up to speed with the tooling support for creating and editing item renderers. For more information on Flex 4 features, see the Flex 4 Features and Migration guide .
You may also want to take a look at Deepa Subramaniam's article What's new in Flex 4 and Andrew Shorten's article What's new in Flash Builder 4.
