How to use the LayoutGroupItemRenderer component

The LayoutGroupItemRenderer class is a base class for creating custom item renderers to display in data containers, such as ListView or GridView.

The Basics

Item renderers are managed by data containers, like ListView, GridView, and GroupListView. Unlike other components, item renderers generally aren't added to the display list directly. Instead, the data container will use a DisplayObjectRecycler to manage its item renderers. For instance, ListView has a itemRendererRecycler property.

var recycler = DisplayObjectRecycler.withFunction(() -> {
    var itemRenderer = new LayoutGroupItemRenderer();
    // set common properties, or create sub-components, for all renderers
    // in the same container here
    var label = new Label();
    label.name = "label";
    itemRenderer.addChild(label);
    return itemRenderer;
});
listView.itemRendererRecycler = recycler;

A custom update() method on the recycler can be used to set properties for a specific item from the container's data provider.

// handle properties for a specific item in update()
recycler.update = (itemRenderer:LayoutGroupItemRenderer, state:ListViewItemState) -> {
    var label = cast(itemRenderer.getChildByName("label"), Label);
    label.text = state.text;
};

The second parameter contains the current state of the item being displayed, including the original data from the data provider, its position within the data provider, the text to display, whether the item is selected, and more. In this case, we pass the text to the item renderer's label sub-component.

States

When the user interacts with a layout group item renderer using the mouse, keyboard, or touchscreen, its state will change, which may affect its appearance. For instance, the item renderer's background skin may be rendered differently in different states.

The ToggleButtonState enum defines the available states, similar to the ItemRenderer class.

  • UP(selected:Bool) is the item renderer's default state when the user is not interacting with it, and the item renderer is enabled.
  • DOWN(selected:Bool) is the state when the user presses the item renderer with a mouse, touchscreen, or by pressing Keyboard.SPACE when the item renderer is focused.
  • HOVER(selected:Bool) is the state when the mouse is hovering over the item renderer. This state is not used for touchscreens or keyboard interaction.
  • DISABLED(selected:Bool) is the item renderer's state when its enabled property has been set to false.

Notice that each state also defines a boolean value to indicate if the item renderer is selected or not. DOWN(true) and DOWN(false) both indicate that the item renderer is currently pressed down, but the value of true indicates that it is currently selected, while false means that it is not selected.

Styles

A number of styles may be customized on a LayoutGroupItemRenderer component, including the background skin and the layout.

Background skin

Give the item renderer a background using the backgroundSkin property. The following example sets it to a RectangleSkin instance.

var skin = new RectangleSkin();
skin.border = SolidColor(1.0, 0x999999);
skin.fill = SolidColor(0xcccccc);
skin.width = 64.0;
skin.height = 32.0;
itemRenderer.backgroundSkin = skin;

The border and fill properties of the RectangleSkin are used to adjust its appearance. They support a variety of values — from solid colors to gradients to bitmaps.

The button automatically calculates its preferred size based on the initial dimensions of its background skin (accounting for some other factors too, like the dimensions of the text and icon), so it's important to set a skin's width and height properties to appropriate values to use in this calculation.

See Skinning with common shapes for more details about how to use RectangleSkin with the LineStyle and FillStyle enums that change its border and fill appearance.

The appearance of the item renderer's border or fill may change when the item renderer is selected. In the next example, the same RectangleSkin displays a different fill when selected by setting the selectedFill property.

skin.selectedFill = SolidColor(0xcc9999);

Similarly, use the selectedBorder property to set the border when selected.

skin.selectedBorder = SolidColor(2.0, 0x999999);

The fill or border may be customized for an exact state too. In the next example, the same RectangleSkin displays a different border when the item renderer is down and not selected.

skin.setFillForState(ToggleButtonState.DOWN(false), SolidColor(0xaa9999));
skin.setBorderForState(ToggleButtonState.DOWN(false), SolidColor(1.0, 0x9999cc));

In the examples above, the item renderer uses the same RectangleSkin for all states, and that skin listens for changes to the item renderer's current state. Alternatively, the item renderer's selectedBackgroundSkin property and setSkinForState() method allow the item renderer to display a completely different display object when its current state changes.

var defaultSkin = new RectangleSkin();
// ... set border, fill, width, and height
itemRenderer.backgroundSkin = defaultSkin;

var selectedSkin = new RectangleSkin();
// ... set border, fill, width, and height
itemRenderer.selectedBackgroundSkin = selectedSkin;

var hoverSkin = new RectangleSkin();
// ... set border, fill, width, and height
itemRenderer.setSkinForState(ToggleButtonState.HOVER(false), hoverSkin);

In the example above, the item renderer will display a custom skin when it is not selected and the mouse is hovering over it, the selected states will share the selectedBackgroundSkin, and all remaining states will share the default backgroundSkin.

Layout

Set the item renderer's layout property to automatically position its children.

var itemLayout = new HorizontalLayout();
itemLayout.paddingTop = 4.0;
itemLayout.paddingRight = 10.0;
itemLayout.paddingBottom = 4.0;
itemLayout.paddingLeft = 10.0;
itemLayout.gap = 2.0;
itemRenderer.layout = itemLayout;

The example above uses HorizontalLayout, but a number of different layouts are available in Feathers UI, and it's possible to create custom layouts.