Define a custom Spark item renderer

Several Spark components represent lists of items. These list-based components, such as DataGroup, List, and DataGrid, let the application user scroll through the item list. Some components, such as List, also let you select one or more items from the list.

You define a custom item renderer to control the display of a data item in a list-based component. The appearance can include the font, background color, border, and any other visual aspects of the data item.

An item renderer also defines the appearance of a data item when the user interacts with it. For example, the item renderer can display the data item one way when the user hovers over the data item, and in a different way when the user selects the data item.

Many Spark components support both skins and item renderers. While the item renderer defines the appearance of the data item, the skin defines the complete visual appearance of the component. The skin can include borders, scroll bars, and any other aspects of the appearance of the component. For more information on skins, see Spark Skinning.

 Adobe engineer Balaji Sridhar explains creating item renderers in Using Flash Builder 4 to create Spark item renderers .

Adobe recommends

Have a tutorial you would like to share?

Building a Mobile ItemRenderer in Flex

Jeffry Houser
This post gives you the steps to create a mobile optimized renderer.

Item renderer architecture

Create an item renderer in MXML or ActionScript. The advantage to creating item renderers in MXML is that it requires the least amount of code because much of the item renderer functionality is built into the base class, ItemRenderer, that you use to define MXML item renderers.

ActionScript item renderers provide the best performance because they give you complete control over the implementation. In an ActionScript item renderer, you only implement the code necessary to support your application requirements. Create an ActionScript item renderer as a subclass of the spark.components.LabelItemRenderer class for mobile applications, and the mx.core.UIComponent class for desktop applications.

The Spark item renderer architecture is defined by interfaces. Regardless of how you create your item renderer, MXML or ActionScript, the item renderer typically implements two interfaces:

Item renderer interface

Implemented by

Use

IDataRenderer

Item renderer

Defines the data property used to pass information to an item renderer.

At a minimum, an item renderer must implement IDataRenderer to display data.

IItemRenderer

Item renderer

Defines the APIs that a component must implement to create an item renderer that can communicate with a host component to support user interaction with the data item. User interactions include selection, dragging, and the caret indicator. For some components, such as the Spark List control, user interaction includes item selection.

The list-based components that uses the item renderer is called the host component, or item renderer owner. To function as a host component, the component must implement the IItemRendererOwner interface.

Host component interface

Implemented by

Use

IItemRendererOwner

Host component of an item renderer

Defines the methods used by the host component to pass data to the item renderer.

Custom item renderer example

To better understand how item renderers work, examine the implementation of a custom item renderer. Shown below is the code for a custom MXML item renderer for the SkinnableDataContainer container that changes the font of the data item when the user hovers over the data item: 
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\myComponents\MySimpleCustomItemRenderer.mxml -->
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:states> 
        <s:State name="normal"/> 
        <s:State name="hovered"/> 
    </s:states> 
    
    <s:Label id="labelDisplay" 
        verticalCenter="0" 
        left="3" right="3" top="6" bottom="4" 
        fontSize.hovered='14' fontStyle.hovered="italic"/> 
</s:ItemRenderer>

The base class of this item renderer is the ItemRenderer class. The ItemRenderer class implements the IDataRenderer and IItemRenderer interfaces. It is also a subclass of the Group class, so it is itself a container. In the body of the item renderer, define the layout, view states, and child controls of the item renderer used to represent the data item.

The default layout of the ItemRenderer class is BasicLayout. In this example, since there is no specification for the layout property, the item renderer uses BasicLayout.

The item renderer can define view states. All view states are optional. In this example, you handle the normal and hovered view states. The normal state defines the appearance of the data item when there is no user interaction. The hovered view state defines the appearance when the user hovers the pointer over the data item.

This example uses the hovered view state to change the font when the user mouses over the data item. In this example, the custom item renderer displays the text in 14 point, italic font on mouse over. For more information on using view states in an item renderer, see Defining item renderer view states for a Spark container.

The Label control is centered vertically in the display area of the item renderer, and is constrained to be three pixels in from the left border, three pixels in from the right border, six pixels in from the top border, and four pixels in from the bottom border. You can use these same settings in your custom item renderers to mimic the look of the default Flex item renderer, or change them as necessary for your application.

The id of the Label control in the item renderer is labelDisplay. This is a specially named component in an item renderer. Flex writes the String representation of the data item to the component named labelDisplay. Flex also uses the labelDisplay component to determine the value of the baselinePosition property in the host component.

The following application uses this custom item renderer: 
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkDataGroupContainerSimpleIR.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:SkinnableDataContainer 
        itemRenderer="myComponents.MySimpleCustomItemRenderer"> 
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
        <mx:ArrayList>
            <fx:String>Bill Smith</fx:String>
            <fx:String>Dave Jones</fx:String>
            <fx:String>Mary Davis</fx:String>
            <fx:String>Debbie Cooper</fx:String>
        </mx:ArrayList> 
    </s:SkinnableDataContainer> 
</s:Application>
The executing SWF file for the previous example is shown below: