The collection of data displayed by the list. Changing this property to a new value is considered a drastic change to the list's data, so the horizontal and vertical scroll positions will be reset, and the list's selection will be cleared.

The following example passes in a data provider and tells the item renderer how to interpret the data:

    list.dataProvider = new ArrayHierarchicalCollection(
    [
        {
               header: "Dairy",
               children:
               [
                   { text: "Milk", thumbnail: textureAtlas.getTexture( "milk" ) },
                   { text: "Cheese", thumbnail: textureAtlas.getTexture( "cheese" ) },
               ]
        },
        {
            header: "Bakery",
            children:
            [
                { text: "Bread", thumbnail: textureAtlas.getTexture( "bread" ) },
            ]
        },
        {
            header: "Produce",
            children:
            [
                { text: "Bananas", thumbnail: textureAtlas.getTexture( "bananas" ) },
                { text: "Lettuce", thumbnail: textureAtlas.getTexture( "lettuce" ) },
                { text: "Onion", thumbnail: textureAtlas.getTexture( "onion" ) },
            ]
        },
    ]);
    
    list.itemRendererFactory = function():IGroupedListItemRenderer
    {
        var renderer:DefaultGroupedListItemRenderer = new DefaultGroupedListItemRenderer();
        renderer.labelField = "text";
        renderer.iconSourceField = "thumbnail";
        return renderer;
    };

Warning: A grouped list's data provider cannot contain duplicate items. To display the same item in multiple item renderers, you must create separate objects with the same properties. This restriction exists because it significantly improves performance.

Warning: If the data provider contains display objects, concrete textures, or anything that needs to be disposed, those objects will not be automatically disposed when the grouped list is disposed. Similar to how starling.display.Image cannot automatically dispose its texture because the texture may be used by other display objects, a list cannot dispose its data provider because the data provider may be used by other lists. See the dispose() function on IHierarchicalCollection to see how the data provider can be disposed properly.

The default value is null.

See also

When a list requires multiple item renderer types, this function is used to determine which type of item renderer is required for a specific item (or index). Returns the ID of the item renderer type to use for the item, or null if the default itemRendererFactory should be used.

The function is expected to have one of the following signatures:

function(item:Object):String

function(item:Object, groupIndex:int, itemIndex:int):String

The following example provides a factoryIDFunction:

    function regularItemFactory():IGroupedListItemRenderer
    {
        return new DefaultGroupedListItemRenderer();
    }
    function firstItemFactory():IGroupedListItemRenderer
    {
        return new CustomItemRenderer();
    }
    list.setItemRendererFactoryWithID( "regular-item", regularItemFactory );
    list.setItemRendererFactoryWithID( "first-item", firstItemFactory );
    
    list.factoryIDFunction = function( item:Object, groupIndex:int, itemIndex:int ):String
    {
        if(index == 0)
        {
            return "first-item";
        }
        return "regular-item";
    };

The default value is null.

See also

A function called that is expected to return a new item renderer for the first item in a group. Has a higher priority than firstItemRendererType. Typically, you would use an firstItemRendererFactory instead of an firstItemRendererType if you wanted to initialize some properties on each separate item renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListItemRenderer

The following example provides a factory for the item renderer used for the first item in a group:

    list.firstItemRendererFactory = function():IGroupedListItemRenderer
    {
        var renderer:CustomItemRendererClass = new CustomItemRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The default value is null.

See also

The class used to instantiate the item renderer for the first item in a group. Must implement the IGroupedListItemRenderer interface.

The following example changes the first item renderer type:

    list.firstItemRendererType = CustomItemRendererClass;

The default value is null.

See also

When a list requires multiple footer renderer types, this function is used to determine which type of footer renderer is required for a specific footer (or group index). Returns the ID of the factory to use for the footer, or null if the default footerRendererFactory should be used.

The function is expected to have one of the following signatures:

function(footer:Object):String

function(footer:Object, groupIndex:int):String

The following example provides a footerFactoryIDFunction:

    function regularFooterFactory():IGroupedListFooterRenderer
    {
        return new DefaultGroupedListHeaderOrFooterRenderer();
    }
    function customFooterFactory():IGroupedListFooterRenderer
    {
        return new CustomFooterRenderer();
    }
    list.setFooterRendererFactoryWithID( "regular-footer", regularFooterFactory );
    list.setFooterRendererFactoryWithID( "custom-footer", customFooterFactory );
    
    list.footerFactoryIDFunction = function( footer:Object, groupIndex:int ):String
    {
        //check if the footerAccessory property exists in the footer data
        if( "footerAccessory" in footer )
        {
            return "custom-footer";
        }
        return "regular-footer";
    };

The default value is null.

See also

The field in a group that contains the data for a footer. If the group does not have this field, and a footerFunction is not defined, then no footer will be displayed for the group. In other words, a footer is optional, and a group may not have one.

All of the footer fields and functions, ordered by priority:

1. footerFunction
2. footerField

The following example sets the footer field:

    list.footerField = "controls";

The default value is "footer".

See also

A function used to generate footer data for a specific group. If this function is not null, then the footerField will be ignored.

The function is expected to have the following signature:

function( item:Object ):Object

All of the footer fields and functions, ordered by priority:

1. footerFunction
2. footerField

The following example sets the footer function:

    list.footerFunction = function( group:Object ):Object
    {
       return group.footer;
    };

The default value is null.

See also

A function called that is expected to return a new footer renderer. Has a higher priority than footerRendererType. Typically, you would use an footerRendererFactory instead of a footerRendererType if you wanted to initialize some properties on each separate footer renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListHeaderOrFooterRenderer

The following example provides a factory for the footer renderer:

    list.itemRendererFactory = function():IGroupedListHeaderOrFooterRenderer
    {
        var renderer:CustomFooterRendererClass = new CustomFooterRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The default value is null.

See also

An object that stores properties for all of the list's footer renderers, and the properties will be passed down to every footer renderer when the list validates. The available properties depend on which IGroupedListHeaderOrFooterRenderer implementation is returned by footerRendererFactory.

By default, the footerRendererFactory will return a DefaultGroupedListHeaderOrFooterRenderer instance. If you aren't using a custom footer renderer, you can refer to feathers.controls.renderers.DefaultGroupedListHeaderOrFooterRenderer for a list of available properties.

These properties are shared by every footer renderer, so anything that cannot be shared (such as display objects, which cannot be added to multiple parents) should be passed to footer renderers using the footerRendererFactory or in the theme.

The following example customizes some footer renderer properties:

    list.footerRendererProperties.contentLabelField = "footerText";
    list.footerRendererProperties.contentLabelStyleName = "custom-footer-renderer-content-label";

If the subcomponent has its own subcomponents, their properties can be set too, using attribute @ notation. For example, to set the skin on the thumb which is in a SimpleScrollBar, which is in a List, you can use the following syntax:

list.verticalScrollBarProperties.@thumbProperties.defaultSkin = new Image(texture);

Setting properties in a footerRendererFactory function instead of using footerRendererProperties will result in better performance.

The default value is null.

See also

The class used to instantiate footer renderers. Must implement the IGroupedListHeaderOrFooterRenderer interface.

The following example changes the footer renderer type:

    list.footerRendererType = CustomFooterRendererClass;

The default value is feathers.controls.renderers.DefaultGroupedListHeaderOrFooterRenderer.

See also

The default IStyleProvider for all GroupedList components.

The default value is null.

See also

When a list requires multiple header renderer types, this function is used to determine which type of header renderer is required for a specific header (or group index). Returns the ID of the factory to use for the header, or null if the default headerRendererFactory should be used.

The function is expected to have one of the following signatures:

function(header:Object):String

function(header:Object, groupIndex:int):String

The following example provides a headerFactoryIDFunction:

    function regularHeaderFactory():IGroupedListHeaderRenderer
    {
        return new DefaultGroupedListHeaderOrFooterRenderer();
    }
    function customHeaderFactory():IGroupedListHeaderRenderer
    {
        return new CustomHeaderRenderer();
    }
    list.setHeaderRendererFactoryWithID( "regular-header", regularHeaderFactory );
    list.setHeaderRendererFactoryWithID( "custom-header", customHeaderFactory );
    
    list.headerFactoryIDFunction = function( header:Object, groupIndex:int ):String
    {
        //check if the subTitle property exists in the header data
        if( "subTitle" in header )
        {
            return "custom-header";
        }
        return "regular-header";
    };

The default value is null.

See also

The field in a group that contains the data for a header. If the group does not have this field, and a headerFunction is not defined, then no header will be displayed for the group. In other words, a header is optional, and a group may not have one.

All of the header fields and functions, ordered by priority:

1. headerFunction
2. headerField

The following example sets the header field:

    list.headerField = "alphabet";

The default value is "header".

See also

A function used to generate header data for a specific group. If this function is not null, then the headerField will be ignored.

The function is expected to have the following signature:

function( item:Object ):Object

All of the header fields and functions, ordered by priority:

1. headerFunction
2. headerField

The following example sets the header function:

    list.headerFunction = function( group:Object ):Object
    {
       return group.header;
    };

The default value is null.

See also

A function called that is expected to return a new header renderer. Has a higher priority than headerRendererType. Typically, you would use an headerRendererFactory instead of a headerRendererType if you wanted to initialize some properties on each separate header renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListHeaderOrFooterRenderer

The following example provides a factory for the header renderer:

    list.itemRendererFactory = function():IGroupedListHeaderOrFooterRenderer
    {
        var renderer:CustomHeaderRendererClass = new CustomHeaderRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The default value is null.

See also

An object that stores properties for all of the list's header renderers, and the properties will be passed down to every header renderer when the list validates. The available properties depend on which IGroupedListHeaderOrFooterRenderer implementation is returned by headerRendererFactory.

By default, the headerRendererFactory will return a DefaultGroupedListHeaderOrFooterRenderer instance. If you aren't using a custom header renderer, you can refer to feathers.controls.renderers.DefaultGroupedListHeaderOrFooterRenderer for a list of available properties.

These properties are shared by every header renderer, so anything that cannot be shared (such as display objects, which cannot be added to multiple parents) should be passed to header renderers using the headerRendererFactory or in the theme.

The following example customizes some header renderer properties:

    list.headerRendererProperties.contentLabelField = "headerText";
    list.headerRendererProperties.contentLabelStyleName = "custom-header-renderer-content-label";

If the subcomponent has its own subcomponents, their properties can be set too, using attribute @ notation. For example, to set the skin on the thumb which is in a SimpleScrollBar, which is in a List, you can use the following syntax:

list.verticalScrollBarProperties.@thumbProperties.defaultSkin = new Image(texture);

Setting properties in a headerRendererFactory function instead of using headerRendererProperties will result in better performance.

The default value is null.

See also

The class used to instantiate header renderers. Must implement the IGroupedListHeaderOrFooterRenderer interface.

The following example changes the header renderer type:

    list.headerRendererType = CustomHeaderRendererClass;

The default value is feathers.controls.renderers.DefaultGroupedListHeaderOrFooterRenderer.

See also

Determines if this component's children can receive focus. This property is completely independent from the isFocusEnabled property. In other words, it's possible to disable focus on this component while still allowing focus on its children (or the other way around).

In the following example, the focus is disabled:

    object.isFocusEnabled = false;

The default value is true.

See also

Determines if an item in the list may be selected.

The following example disables selection:

     list.isSelectable = false;

The default value is true.

See also

A function called that is expected to return a new item renderer. Has a higher priority than itemRendererType. Typically, you would use an itemRendererFactory instead of an itemRendererType if you wanted to initialize some properties on each separate item renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListItemRenderer

The following example provides a factory for the item renderer:

    list.itemRendererFactory = function():IGroupedListItemRenderer
    {
        var renderer:CustomItemRendererClass = new CustomItemRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The first item and last item in a group may optionally use different item renderer factories, if desired. Use the firstItemRendererFactory and lastItemRendererFactory, respectively. Additionally, if a group contains only one item, it may also have a different factory. Use the singleItemRendererFactory.

The default value is null.

See also

An object that stores properties for all of the list's item renderers, and the properties will be passed down to every item renderer when the list validates. The available properties depend on which IGroupedListItemRenderer implementation is returned by itemRendererFactory.

By default, the itemRendererFactory will return a DefaultGroupedListItemRenderer instance. If you aren't using a custom item renderer, you can refer to feathers.controls.renderers.DefaultGroupedListItemRenderer for a list of available properties.

These properties are shared by every item renderer, so anything that cannot be shared (such as display objects, which cannot be added to multiple parents) should be passed to item renderers using the itemRendererFactory or in the theme.

The following example customizes some item renderer properties (this example assumes that the item renderer's label text renderer is a BitmapFontTextRenderer):

    list.itemRendererProperties.labelField = "text";
    list.itemRendererProperties.accessoryField = "control";

If the subcomponent has its own subcomponents, their properties can be set too, using attribute @ notation. For example, to set the skin on the thumb which is in a SimpleScrollBar, which is in a List, you can use the following syntax:

list.verticalScrollBarProperties.@thumbProperties.defaultSkin = new Image(texture);

Setting properties in a itemRendererFactory function instead of using itemRendererProperties will result in better performance.

The default value is null.

See also

The class used to instantiate item renderers. Must implement the IGroupedListItemRenderer interface.

To customize properties on the item renderer, use itemRendererFactory instead.

The following example changes the item renderer type:

    list.itemRendererType = CustomItemRendererClass;

The first item and last item in a group may optionally use different item renderer types, if desired. Use the firstItemRendererType and lastItemRendererType, respectively. Additionally, if a group contains only one item, it may also have a different type. Use the singleItemRendererType. Finally, factories for each of these types may also be customized.

The default value is feathers.controls.renderers.DefaultGroupedListItemRenderer.

See also

A function called that is expected to return a new item renderer for the last item in a group. Has a higher priority than lastItemRendererType. Typically, you would use an lastItemRendererFactory instead of an lastItemRendererType if you wanted to initialize some properties on each separate item renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListItemRenderer

The following example provides a factory for the item renderer used for the last item in a group:

    list.firstItemRendererFactory = function():IGroupedListItemRenderer
    {
        var renderer:CustomItemRendererClass = new CustomItemRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The default value is null.

See also

The class used to instantiate the item renderer for the last item in a group. Must implement the IGroupedListItemRenderer interface.

The following example changes the last item renderer type:

    list.lastItemRendererType = CustomItemRendererClass;

The default value is null.

See also

The pending group index to scroll to after validating. A value of -1 means that the scroller won't scroll to a group after validating.

The pending item index to scroll to after validating. A value of -1 means that the scroller won't scroll to an item after validating.

The group index of the currently selected item. Returns -1 if no item is selected.

Because the selection consists of both a group index and an item index, this property does not have a setter. To change the selection, call setSelectedLocation() instead.

The following example listens for when selection changes and requests the selected group index and selected item index:

    function list_changeHandler( event:Event ):void
    {
        var list:List = GroupedList(event.currentTarget);
        var groupIndex:int = list.selectedGroupIndex;
        var itemIndex:int = list.selectedItemIndex;
    
    }
    list.addEventListener( Event.CHANGE, list_changeHandler );

The default value is -1.

See also

The currently selected item. Returns null if no item is selected.

The following example listens for when selection changes and requests the selected item:

    function list_changeHandler( event:Event ):void
    {
        var list:GroupedList = GroupedList( event.currentTarget );
        var item:Object = list.selectedItem;
    
    }
    list.addEventListener( Event.CHANGE, list_changeHandler );

The default value is null.

The item index of the currently selected item. Returns -1 if no item is selected.

Because the selection consists of both a group index and an item index, this property does not have a setter. To change the selection, call setSelectedLocation() instead.

The following example listens for when selection changes and requests the selected group index and selected item index:

    function list_changeHandler( event:Event ):void
    {
        var list:GroupedList = GroupedList( event.currentTarget );
        var groupIndex:int = list.selectedGroupIndex;
        var itemIndex:int = list.selectedItemIndex;
    
    }
    list.addEventListener( Event.CHANGE, list_changeHandler );

The default value is -1.

See also

A function called that is expected to return a new item renderer for an item in a group with no other items. Has a higher priority than singleItemRendererType. Typically, you would use an singleItemRendererFactory instead of an singleItemRendererType if you wanted to initialize some properties on each separate item renderer, such as skins.

The function is expected to have the following signature:

function():IGroupedListItemRenderer

The following example provides a factory for the item renderer used for when only one item appears in a group:

    list.firstItemRendererFactory = function():IGroupedListItemRenderer
    {
        var renderer:CustomItemRendererClass = new CustomItemRendererClass();
        renderer.backgroundSkin = new Quad( 10, 10, 0xff0000 );
        return renderer;
    };

The default value is null.

See also

The class used to instantiate the item renderer for an item in a group with no other items. Must implement the IGroupedListItemRenderer interface.

The following example changes the single item renderer type:

    list.singleItemRendererType = CustomItemRendererClass;

The default value is null.

See also

Used to auto-size the list when a virtualized layout is used. If the list's width or height is unknown, the list will try to automatically pick an ideal size. This item is used to create a sample item renderer to measure item renderers that are virtual and not visible in the viewport.

The following example provides a typical item:

    list.typicalItem = { text: "A typical item", thumbnail: texture };

The default value is null.

Constructor.

Returns the current footer renderer used to render specific footer data. May return null if the footer data doesn't currently have a footer renderer. Most lists use virtual layouts where only the visible footers will have a footer renderer, so the result will usually be null for most footer data in the data provider.

Parameters

See also

Returns the footer renderer factory associated with a specific ID. Returns null if no factory is associated with the ID.

Parameters

See also

Returns the header renderer factory associated with a specific ID. Returns null if no factory is associated with the ID.

Parameters

See also

Returns the item renderer factory associated with a specific ID. Returns null if no factory is associated with the ID.

Parameters

See also

Extracts footer data from a group object.

Parameters

Extracts header data from a group object.

Parameters

Returns the current header renderer used to render specific header data. May return null if the header data doesn't currently have a header renderer. Most lists use virtual layouts where only the visible headers will have a header renderer, so the result will usually be null for most header data in the data provider.

Parameters

See also

Returns the current item renderer used to render a specific item. May return null if an item doesn't currently have an item renderer. Most lists use virtual layouts where only the visible items will have an item renderer, so the result will usually be null for most items in the data provider.

Parameters

See also

After the next validation, scrolls the list so that the specified item is visible. If animationDuration is greater than zero, the scroll will animate. The duration is in seconds.

The itemIndex parameter is optional. If set to -1, the list will scroll to the start of the specified group.

In the following example, the list is scrolled to display the third item in the second group:

    list.scrollToDisplayIndex( 1, 2 );

In the following example, the list is scrolled to display the third group:

    list.scrollToDisplayIndex( 2 );

Parameters

Associates a footer renderer factory with an ID to allow multiple types of footer renderers may be displayed in the list. A custom footerFactoryIDFunction may be specified to return the ID of the factory to use for a specific footer in the data provider.

Parameters

See also

Associates a header renderer factory with an ID to allow multiple types of header renderers may be displayed in the list. A custom headerFactoryIDFunction may be specified to return the ID of the factory to use for a specific header in the data provider.

Parameters

See also

Associates an item renderer factory with an ID to allow multiple types of item renderers may be displayed in the list. A custom factoryIDFunction may be specified to return the ID of the factory to use for a specific item in the data provider.

Parameters

See also

Sets the selected group and item index.

In the following example, the third item in the second group is selected:

    list.setSelectedLocation( 1, 2 );

In the following example, the selection is cleared:

    list.setSelectedLocation( -1, -1 );

Parameters

See also

Dispatched when the selected item changes.

The properties of the event object have the following values:

See also

Dispatched when an item renderer is added to the list. When the layout is virtualized, item renderers may not exist for every item in the data provider. This event can be used to track which items currently have renderers.

The properties of the event object have the following values:

Dispatched when an item renderer is removed from the list. When the layout is virtualized, item renderers may not exist for every item in the data provider. This event can be used to track which items currently have renderers.

The properties of the event object have the following values:

Dispatched when the the user taps or clicks an item renderer in the list. The touch must remain within the bounds of the item renderer on release, and the list must not have scrolled, to register as a tap or a click.

The properties of the event object have the following values:

An alternate name to use for item renderers to give them an inset style. Typically meant to be used for the renderer of the first item in a group. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's first item renderer:

    list.customFirstItemRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_FIRST_ITEM_RENDERER;

See also

An alternate name to use with footer renderers to give them an inset style. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's footer:

    list.customFooterRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_FOOTER_RENDERER;

An alternate name to use with header renderers to give them an inset style. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's header:

    list.customHeaderRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_HEADER_RENDERER;

See also

An alternate name to use with item renderers to give them an inset style. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's item renderer:

    list.customItemRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_ITEM_RENDERER;

See also

An alternate name to use for item renderers to give them an inset style. Typically meant to be used for the renderer of the last item in a group. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's last item renderer:

    list.customLastItemRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_LAST_ITEM_RENDERER;

See also

An alternate name to use for item renderers to give them an inset style. Typically meant to be used for the renderer of an item in a group that has no other items. This name is usually only referenced inside themes.

In the following example, the inset style is applied to a grouped list's single item renderer:

    list.customSingleItemRendererStyleName = GroupedList.ALTERNATE_CHILD_STYLE_NAME_INSET_SINGLE_ITEM_RENDERER;

See also

An alternate style name to use with GroupedList to allow a theme to give it an inset style. If a theme does not provide a style for an inset grouped list, the theme will automatically fall back to using the default grouped list style.

An alternate style name should always be added to a component's styleNameList before the component is initialized. If the style name is added later, it will be ignored.

In the following example, the inset style is applied to a grouped list:

    var list:GroupedList = new GroupedList();
    list.styleNameList.add( GroupedList.ALTERNATE_STYLE_NAME_INSET_GROUPED_LIST );
    this.addChild( list );

See also

The default name to use with footer renderers.

See also

The default name to use with header renderers.

See also