If true multiple items may be selected at a time. If false, then only a single item may be selected at a time, and if the selection changes, other items are deselected. Has no effect if isSelectable is false.

In the following example, multiple selection is enabled:

list.allowMultipleSelection = true;

The default value is false.

See also

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 ArrayCollection(
[
    { text: "Milk", thumbnail: textureAtlas.getTexture( "milk" ) },
    { text: "Eggs", thumbnail: textureAtlas.getTexture( "eggs" ) },
    { text: "Bread", thumbnail: textureAtlas.getTexture( "bread" ) },
    { text: "Chicken", thumbnail: textureAtlas.getTexture( "chicken" ) },
]);
list.itemRendererFactory = function():IListItemRenderer
{
    var renderer:DefaultListItemRenderer = new DefaultListItemRenderer();
    renderer.labelField = "text";
    renderer.iconSourceField = "thumbnail";
    return renderer;
};

Warning: A 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 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 IListCollection to see how the data provider can be disposed properly.

The default value is null.

See also

Indicates if this list can initiate drag and drop operations by touching an item and dragging it. The dragEnabled property enables dragging items, but dropping items must be enabled separately with the dropEnabled property.

In the following example, a list's items may be dragged:

list.dragEnabled = true;

See also

Drag and drop is restricted to components that have the same dragFormat.

In the following example, the drag format of two lists is customized:

list1.dragFormat = "my-custom-format";
list2.dragFormat = "my-custom-format";

The default value is "feathers-list-item".

Indicates if this list can accept items that are dragged and dropped over the list's hit area.

In the following example, a list's items may be dropped:

list.dropEnabled = true;

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, index:int):String

The following example provides a factoryIDFunction:

function regularItemFactory():IListItemRenderer
{
    return new DefaultListItemRenderer();
}
function headerItemFactory():IListItemRenderer
{
    return new CustomItemRenderer();
}
list.setItemRendererFactoryWithID( "regular-item", regularItemFactory );
list.setItemRendererFactoryWithID( "header-item", listHeaderFactory );

list.factoryIDFunction = function( item:Object, index:int ):String
{
    if(index == 0)
    {
        return "header-item";
    }
    return "regular-item";
};

The default value is null.

See also

The default IStyleProvider for all List components.

The default value is null.

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 items in the list may be selected. By default only a single item may be selected at any given time. In other words, if item A is selected, and the user selects item B, item A will be deselected automatically. Set allowMultipleSelection to true to select more than one item without automatically deselecting other items.

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():IListItemRenderer

The following example provides a factory for the item renderer:

list.itemRendererFactory = function():IListItemRenderer
{
    var renderer:CustomItemRendererClass = new CustomItemRendererClass();
    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 item renderers, and the properties will be passed down to every item renderer when the list validates. The available properties depend on which IListItemRenderer implementation is returned by itemRendererFactory.

By default, the itemRendererFactory will return a DefaultListItemRenderer instance. If you aren't using a custom item renderer, you can refer to feathers.controls.renderers.DefaultListItemRenderer 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 IListItemRenderer interface.

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

The following example changes the item renderer type:

list.itemRendererType = CustomItemRendererClass;

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

See also

The minimum physical distance (in inches) that a touch must be from the edge of the container during a drag and drop action before the container starts scrolling.

In the following example, the minimum auto-scroll distance is customized:

scroller.minimumAutoScrollDistance = 0.1;

The default value is 0.3.

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 index of the currently selected item. Returns -1 if no item is selected.

The following example selects an item by its index:

list.selectedIndex = 2;

The following example clears the selected index:

list.selectedIndex = -1;

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

function list_changeHandler( event:Event ):void
{
    var list:List = List( event.currentTarget );
    var index:int = list.selectedIndex;
}
list.addEventListener( Event.CHANGE, list_changeHandler );

The default value is -1.

See also

The indices of the currently selected items. Returns an empty Vector.<int> if no items are selected. If allowMultipleSelection is false, only one item may be selected at a time.

The following example selects two items by their indices:

list.selectedIndices = new <int>[ 2, 3 ];

The following example clears the selected indices:

list.selectedIndices = null;

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

function list_changeHandler( event:Event ):void
{
    var list:List = List( event.currentTarget );
    var indices:Vector.<int> = list.selectedIndices;
}
list.addEventListener( Event.CHANGE, list_changeHandler );

See also

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

The following example changes the selected item:

list.selectedItem = list.dataProvider.getItemAt(0);

The following example clears the selected item:

list.selectedItem = null;

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

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

The default value is null.

See also

The currently selected item. The getter returns an empty Vector.<Object> if no item is selected. If any items are selected, the getter creates a new Vector.<Object> to return a list of selected items.

The following example selects two items:

list.selectedItems = new <Object>[ list.dataProvider.getItemAt(2) , list.dataProvider.getItemAt(3) ];

The following example clears the selected items:

list.selectedItems = null;

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

function list_changeHandler( event:Event ):void
{
    var list:List = List( event.currentTarget );
    var items:Vector.<Object> = list.selectedItems;
}
list.addEventListener( Event.CHANGE, list_changeHandler );

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.

Adds an item from the data provider and animates its item renderer using an effect.

In the following example, an effect fades the item renderer's alpha property from 0 to 1:

list.addItemWithEffect(newItem, list.dataProvider.length, Fade.createFadeBetweenEffect(0, 1));

A number of animated effects may be found in the feathers.motion package. However, you are not limited to only these effects. It's possible to create custom effects too.

A custom effect function should have the following signature:

function(target:DisplayObject):IEffectContext

The IEffectContext is used by the component to control the effect, performing actions like playing the effect, pausing it, or cancelling it.

Custom animated effects that use starling.display.Tween typically return a TweenEffectContext. In the following example, we recreate the Fade.createFadeBetweenEffect() used in the previous example.

function customEffect(target:DisplayObject):IEffectContext
{
    target.alpha = 0;
    var tween:Tween = new Tween(target, 0.5, Transitions.EASE_OUT);
    tween.fadeTo(1);
    return new TweenEffectContext(target, tween);
}
list.addItemWithEffect(newItem, list.dataProvider.length, customEffect);

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

Returns the selected items, with the ability to pass in an optional result vector. Better for performance than the selectedItems getter because it can avoid the allocation, and possibly garbage collection, of the result object.

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

Removes an item from the data provider after animating its item renderer using an effect.

In the following example, an effect fades the item renderer's alpha property to 0:

list.removeItemWithEffect(newItem, list.dataProvider.length, Fade.createFadeOutEffect());

A number of animated effects may be found in the feathers.motion package. However, you are not limited to only these effects. It's possible to create custom effects too.

A custom effect function should have the following signature:

function(target:DisplayObject):IEffectContext

The IEffectContext is used by the component to control the effect, performing actions like playing the effect, pausing it, or cancelling it.

Custom animated effects that use starling.display.Tween typically return a TweenEffectContext. In the following example, we recreate the Fade.createFadeOutEffect() used in the previous example.

function customEffect(target:DisplayObject):IEffectContext
{
    var tween:Tween = new Tween(target, 0.5, Transitions.EASE_OUT);
    tween.fadeTo(0);
    return new TweenEffectContext(target, tween);
}
list.removeItemWithEffect(newItem, customEffect);

Parameters

See also

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.

If the layout is virtual with variable item dimensions, this function may not accurately scroll to the exact correct position. A virtual layout with variable item dimensions is often forced to estimate positions, so the results aren't guaranteed to be accurate.

If you want to scroll to the end of the list, it is better to use scrollToPosition() with maxHorizontalScrollPosition or maxVerticalScrollPosition.

In the following example, the list is scrolled to display index 10:

list.scrollToDisplayIndex( 10 );

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

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:

The layout algorithm used to position and, optionally, size the list's items.

By default, if no layout is provided by the time that the list initializes, a vertical layout with options targeted at touch screens is created.

The following example tells the list to use a horizontal layout:

var layout:HorizontalLayout = new HorizontalLayout();
layout.gap = 20;
layout.padding = 20;
list.layout = layout;

The default value is null.

The duration, in seconds, of the animation when the selected item is changed by keyboard navigation and the item scrolls into view.

In the following example, the duration of the animation that scrolls the list to a new selected item is set to 500 milliseconds:

list.keyScrollDuration = 0.5;

The default value is 0.25.

A skin to display when dragging one an item to indicate where it can be dropped.

In the following example, the list's drop indicator is provided:

list.dropIndicatorSkin = new Image( texture );

The default value is null.

A style name to add to all item renderers in this list. Typically used by a theme to provide different skins to different lists.

The following example sets the item renderer name:

list.customItemRendererStyleName = "my-custom-item-renderer";

In your theme, you can target this sub-component name to provide different skins than the default style:

getStyleProviderForClass( DefaultListItemRenderer ).setFunctionForStyleName( "my-custom-item-renderer", setCustomItemRendererStyles );

The default value is null.

See also