Generating custom item renderers

Spark list-based controls, such as List and ComboBox, support custom item renderers. You can also use Spark item renderers with some MX controls, such as the MX DataGrid and MX Tree controls.

Use custom item renderers to control the display of a data item in a DataGroup, SkinnableDataContainer, or in a subclass of those containers. The appearance defined by an item renderer 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 moves the mouse over the data item. It displays the differently when the user selects the data item by clicking on it.

Using Flash Builder, you can generate and edit item renderers. When Flash Builder generates item renderers, it uses one of the following templates:

  • Spark components

    Use this template for Spark list-based controls, such as List and ComboBox.

  • MX Advanced DataGrid

  • MX DataGrid

  • MX Tree

You can open the New MXML Item Renderer wizard from both Design mode and Source mode of the MXML editor. In the New MXML Item Renderer wizard, you specify a name and template for the item renderer. Flash Builder generates an MXML file that implements the item renderer.

Components in the application reference the generated item renderer using the itemRenderer property.

For details on creating and using item renderers, see Custom Spark Item Renderers.

    Generate and edit an item renderer for an MX Tree component (Design mode)

    This example generates an item renderer for an MX Tree component, showing you how to use a combination of Flash Builder views to edit the item renderer. It assumes that you are working in a Flex project using the default Spark theme.

    1. Create an application file. In Design mode of the editor, add an MX Tree component to the application.

      Populate your Tree with data that can be displayed when you run the application.

    2. From the context menu for the Tree, select Create Item Renderer.

      The New MXML Item Renderer dialog opens.

      You can also do the following to open the New MXML Item Renderer dialog.

      • In the Common section of the Properties view, select the icon near the Item Renderer Field field.

      • From the Flash builder menu, select New > MXML Item Renderer.

    3. Specify the following in the New MXML Item Renderer Dialog:

      • Source Folder and Package for the generated item renderer declaration.

      • Name

        The name for the item renderer class you are creating.

      • Template

        Select the template to use when generating the item renderer.

    4. Click Finish.

      Flash Builder generates an ItemRenderer class file and opens it in Design mode of the MXML editor.

      The ItemRenderer component is selected.

      The normal state of the Tree is selected in States view.

    5. For each state of the Tree, modify the appearance in the generated ItemRenderer class.

      1. Open Outline view:

        Notice that the top-level node, MXTreeItemRenderer, is selected.

        In the Style section of Properties view, modify the appearance of tree items.

      2. In Outline view, select other components of the MXTreeItemRenderer to modify the appearance of those components.

        Notice that the Style section tools are not always available.

        If the Style section tools are not available, then use Source mode of the editor to define the appearance. When you switch to Source mode, the source for the selected component in Outline view is highlighted.

    6. Run the application to see how the ItemRenderer changes the appearance of the Tree.

    Creating and editing item renderers (Source mode)

    You can open the New MXML Item Renderer dialog directly in Source mode of the editor. For example, do the following to create an item renderer for a Spark List component.

    1. In Source mode of the editor, place your cursor inside a <s:List> tag and type the following:

      <s:List itemRender="

      After you type the first quote for the item renderer class name, a context menu appears.

    2. Double-click Create Item Renderer to open the New MXML Item Renderer dialog.

      This dialog is the same dialog that opens in Design Mode.

      See the instructions in Generate and edit an item renderer for an MX Tree component (Design mode) for creating the item renderer.

    3. Click Finish.

      Flash Builder generates a new item renderer based on your selections in the New MXML Item Renderer dialog. The editor switches to the source for the newly generated class.

    4. Edit the item renderer class.

      Save your class file and application file.

    ItemRenderer declaration

    In Flash Builder, an ItemRenderer declaration is the file that implements the custom ItemRenderer for a component.

    You can view the custom ItemRenderer declaration for selected components:

    1. In Design mode of the MXML editor, select a component that you have implemented a custom item renderer for.

    2. From the context menu for the component, select Open Item Renderer Declaration.

      The class implementing the item renderer opens in Source mode of the editor. You can also do the following to open the item renderer declaration:

      • Select the component in Design mode. In the Common section of the Properties view, select the icon near the Item Renderer field.

      • In Source mode, with the component selected, from the Flash Builder menu, select Navigate > Open Skin Declaration.