Using Spark item renderers
Requirements
User level
All
Required products
- Flex (Download trial)
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
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
This work is licensed under a Creative Commons Attribution-Noncommercial 3.0 Unported License.
