Adobe Flex supports several Spark 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 Spark list controls support item renderers to allow you to control the display of the items in the list.

The Spark components that support item renderers are derived from the spark.components.DataGroup or spark.components.SkinnableDataContainer class. These controls include the Spark controls List, ComboBox, ButtonBar, TabBar, and DropDownList controls.

A Spark that support item renderers gets its data from a data provider, which is a collection of objects. For example, a List control reads data from a data provider to define the structure of the list and any associated data that is assigned to each list item.

The data provider creates a level of abstraction between Flex components and the data that you use to populate them. You can populate multiple components from the same data provider, switch data providers for a component at run time, and modify the data provider so that changes are reflected by all components that use the 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.

This article discusses the following ways of creating and using item renderers:

Using the default Spark item renderer
Using a Spark item renderer
Using a Spark item renderer with view states
Passing data to a Spark item renderer
Using an inline item renderer

The Flex MX components also support item renderers. For information on using item renderers with MX components, see Using MX item renderers.

Using the default Spark item renderer

Most Spark components define a default item renderer. The following example contains a Spark List control that uses the default item renderer to display the list information. Flex automatically uses the default when you do not specify a custom item renderer.

Example

        <?xml version="1.0" encoding="utf-8"?>
<!-- ItemRendererSparkDefault.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:Panel title="Using a default Spark item renderer">
		<s:layout>
			<s:VerticalLayout paddingLeft="10" paddingRight="10"
				paddingTop="10" paddingBottom="10"/>
		</s:layout>

		<s:List>
			<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:List>
	</s:Panel>
</s:Application>

    

Result

This content requires Flash To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player. To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

Using a Spark item renderer

Spark item renderers are subclasses of the spark.components.supportClasses.ItemRenderer class. The ItemRenderer class is a subclass of the Group class, so it is itself a container. In the body of the ItemRenderer class, define the layout, states, and child controls of the item renderer used to represent the data item.

You specify a custom Spark item renderer by using the itemRenderer property of a Spark list-based control. In the following example, you use the Spark Label control in the item renderer to display each item in the List control.

Example

components/SimpleSparkItemRenderer.mxml

        <?xml version="1.0" encoding="utf-8"?>
<!-- SimpleSparkItemRenderer.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:Label id="labelDisplay"
		verticalCenter="0"
		left="3" right="3" top="6" bottom="4"/>
</s:ItemRenderer>
    

MXML file

        <?xml version="1.0" encoding="utf-8"?>
<!-- ItemRendererSpark.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:Panel title="Using a Spark item renderer">
		<s:layout>
			<s:VerticalLayout paddingLeft="10" paddingRight="10"
				paddingTop="10" paddingBottom="10"/>
		</s:layout>

		<s:List
			itemRenderer="components.SimpleSparkItemRenderer">
			<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:List>
	</s:Panel>
</s:Application>

    

Result

Using a Spark item renderer with view states

Item renderers support optional view states. When the user interacts with a control in a way that changes the view state of the item renderer, Flex first determines if the renderer defines that view state. If the item renderer supports the view state, Flex sets the item renderer to use that view state. If the item renderer does not supports the view state, Flex does nothing.

The following example defines an item renderer with two view states: normal and hovered. When the user moves the mouse over a list item, the hovered states specifies to display the list item by using a 14 point, italic font.

Example

components/SparkStateItemRenderer.mxml

        <?xml version="1.0" encoding="utf-8"?>
<!-- SparkStateItemRenderer.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>

    

MXML file

        <?xml version="1.0" encoding="utf-8"?>
<!-- ItemRendererSparkStates.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:Panel title="Using a Spark item renderer with view states">
		<s:layout>
			<s:VerticalLayout paddingLeft="10" paddingRight="10"
				paddingTop="10" paddingBottom="10"/>
		</s:layout>

		<s:List
			itemRenderer="components.SparkStateItemRenderer">
			<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:List>
	</s:Panel>
</s:Application>

    

Result

Passing data to a Spark item renderer

The host component of the item renderer is called the item renderer's owner. The base class for item renderers, ItemRenderer, defines properties that the host component uses to pass information to the renderer.

In the following example, you use the ItemRenderer.data property to pass data to the item renderer. The data property contains the original data item from the host component, in its original representation.

Example

components/SparkDataItemRenderer.mxml

        <?xml version="1.0" encoding="utf-8"?>
<!-- SparkDataItemRenderer.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">

	<!-- Use the data property to access the data passed to the item renderer. -->
	<s:HGroup verticalCenter="0" left="2" right="2" top="2" bottom="2">
		<s:Label text="{data.lastName}, {data.firstName}"/>
		<s:Label text="{data.companyID}"/>
	</s:HGroup>
</s:ItemRenderer>

    

MXML file

        <?xml version="1.0" encoding="utf-8"?>
<!-- ItemRendererSparkData.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:Panel title="Passing data to a Spark item renderer">
		<s:layout>
			<s:VerticalLayout paddingLeft="10" paddingRight="10"
				paddingTop="10" paddingBottom="10"/>
		</s:layout>

		<s:List
			itemRenderer="components.SparkDataItemRenderer">
			<mx:ArrayList>
				<fx:Object firstName="Bill" lastName="Smith" companyID="11233"/>
				<fx:Object firstName="Dave" lastName="Jones" companyID="13455"/>
				<fx:Object firstName="Mary" lastName="Davis" companyID="11543"/>
				<fx:Object firstName="Debbie" lastName="Cooper" companyID="14266"/>
			</mx:ArrayList>
		</s:List>
	</s:Panel>
</s:Application>
    

Result

Using an inline item renderer

The examples of item renderers shown above are all defined in an MXML file. That makes the item renderer highly reusable because you can reference it from multiple containers. You can also define inline item renderers in the MXML definition of a component. By using an inline item renderer, your code can all be defined in a single file.

You define the item renderer inline by using the itemRenderer property of the Spark control. The first child tag of the itemRenderer property is always the <fx:Component> tag. Inside the <fx:Component> tag is the code for the item renderer.

Example

        <?xml version="1.0" encoding="utf-8"?>
<!-- ItemRendererSparkInline.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:Panel title="Using an inline Spark item renderer">
		<s:layout>
			<s:VerticalLayout paddingLeft="10" paddingRight="10"
				paddingTop="10" paddingBottom="10"/>
		</s:layout>

		<s:List>
			<mx:ArrayList>
				<fx:Object firstName="Bill" lastName="Smith" companyID="11233"/>
				<fx:Object firstName="Dave" lastName="Jones" companyID="13455"/>
				<fx:Object firstName="Mary" lastName="Davis" companyID="11543"/>
				<fx:Object firstName="Debbie" lastName="Cooper" companyID="14266"/>
			</mx:ArrayList>
			<s:itemRenderer>
				<fx:Component>
					<s:ItemRenderer>
						<s:HGroup verticalCenter="0" left="2"
								right="2" top="2" bottom="2">
							<s:Label text="{data.lastName}, {data.firstName}"/>
							<s:Label text="{data.companyID}"/>
						</s:HGroup>
					</s:ItemRenderer>
				</fx:Component>
			</s:itemRenderer>
		</s:List>
	</s:Panel>
</s:Application>

    

Result

For more information

Custom Spark item renderers

This work is licensed under a Creative Commons Attribution-Noncommercial 3.0 Unported License.

Using Spark item renderers

by Adobe

Created

Page tools

Requirements

User level

Required products

Using the default Spark item renderer

Example

Result

Using a Spark item renderer

Example

Result

Using a Spark item renderer with view states

Example

Result

Passing data to a Spark item renderer

Example

Result

Using an inline item renderer

Example

Result

For more information

Products

Download

Support & Learning

Buy

Company