The List and TileList controls take input from a data provider, an object that contains the data displayed by the control. To provide this data, you assign a collection, which is usually an ArrayCollection or XMLListCollection object, to the control's dataProvider property. Each item in the control is then displayed by using an item renderer.

Data effects make it possible to apply effects to the item renderers in List and TileList controls when the data provider for the control changes. For example, when an item is deleted from the data provider of a List control, the item renderer for that item might fade out and shrink.

For more information about data providers and controls that use data providers, see Using Data Providers and Collections. For more information about item renderers, see Using Item Renderers and Item Editors.

By default, the List and TileList control do not use a data effect. To specify the effect to apply to the control, use the control's itemsChangeEffect style property. For the List control, use the DefaultListEffect class to configure the data effect. For the TileList control, use the DefaultTileListEffect class.

You can also create custom data effects. For more information, see Effects.

Example: Applying a data effect

The following example applies the DefaultListEffect effect to the List control when items are added to or removed from the control. When an item in the List control is removed, this effect first fades out the item, then collapses the size of the item to 0. When you add an item to the List control, this effect expands the slot for the item, then fades in the new item.

Because the DefaultListEffect effect grows and shrinks item renderers as it plays, you must set the List.variableRowHeight property to true to enable the List control to dynamically change its row height, as the following example shows:

<?xml version="1.0"?>
<!-- dataEffects\ListEffectCustomDefaultEffect.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.effects.DefaultListEffect;
            import mx.collections.ArrayCollection;
            
            [Bindable]
            private var myDP:ArrayCollection = new ArrayCollection(
                ['A','B','C','D','E']);
            
            private function deleteItem():void {
                // As each item is removed, the index of the other items changes.
                // So first get the items to delete, and then determine their indices
                // as you remove them.
                var toRemove:Array = [];
                for (var i:int = 0; i < list0.selectedItems.length; i++)
                    toRemove.push(list0.selectedItems[i]);
                for (i = 0; i < toRemove.length; i++)
                    myDP.removeItemAt(myDP.getItemIndex(toRemove[i]));
            }

            private var zcount:int = 0;
            private function addItem():void {
                // Always add the new item after the third item,
                // or after the last item if the length is less than 3.
                myDP.addItemAt("Z"+zcount++,Math.min(3,myDP.length));
            }            
        ]]>
    </mx:Script>

    <!-- Define an instance of the DefaultListEffect effect, 
         and set its fadeOutDuration and color properties. -->
    <mx:DefaultListEffect id="myDLE" 
        fadeOutDuration="1000"
    />

    <mx:List id="list0" 
        width="150"
        dataProvider="{myDP}" 
        variableRowHeight="true" 
        fontSize="24" 
        allowMultipleSelection="true" 
        itemsChangeEffect="{myDLE}"
    />

    <mx:Button 
        label="Delete Item" 
        click="deleteItem();"
    />
    <mx:Button 
        label="Add Item" 
        click="addItem();"
    />
</mx:Application>
The executing SWF file for the previous example is shown below:

To use a data effect with the TileList class, apply the DefaultTileListEffect effect to the control. When an item in the TileList control is removed, this effect first fades out the item, and then moves the remaining items to their new position. When you add an item to the TileList control, this effect moves the existing items to their new position, and then fades in the new item.

You typically set the offscreenExtraRowsOrColumns property of the TileList control when you apply a data effect. This property specifies the number of extra rows or columns of offscreen item renderers used in the layout of the control. This property is useful because data effects work by first determining a before layout of the list-based control, then determining an after layout, and finally setting the properties of the effect to create an animation from the before layout to the after layout. Because many effects cause currently invisible items to become visible, or currently visible items to become invisible, this property configures the control to create the offscreen item renderers so that they already exist when the data effect plays.

You typically set the offscreenExtraRowsOrColumns property to a nonzero, even value, such as 2 or 4, for a TileList control, as the following example shows:

<?xml version="1.0"?>
<!-- dataEffects\TileListEffectCustomDefaultEffect.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.effects.DefaultTileListEffect;
            import mx.effects.easing.Elastic;
            import mx.collections.ArrayCollection;
            import mx.effects.Move;
            
            [Bindable]
            private var myDP:ArrayCollection = new ArrayCollection(
                ["A","B",'C','D','E','F','G','H','I','J','K','L','M','N','O','P']);

            private function deleteItems():void {
                // As each item is removed, the index of the other items changes.
                // So first get the items to delete, and then determine their indices
                // as you remove them.
                var toRemove:Array = [];
                for (var i:int = 0; i < tlist0.selectedItems.length; i++)
                    toRemove.push(tlist0.selectedItems[i]);
                for (i = 0; i < toRemove.length; i++)
                    myDP.removeItemAt(myDP.getItemIndex(toRemove[i]));
            }

            private var zcount:int = 0;
            private function addItems():void {
                myDP.addItemAt("Z"+zcount++,Math.min(2,myDP.length));
            }            
        ]]>
    </mx:Script>
    
    <!-- Define an instance of the DefaultTileListEffect effect, 
         and set its moveDuration and color properties. -->
    <mx:DefaultTileListEffect id="myDTLE" 
        moveDuration="100"/>

    <mx:TileList id="tlist0" 
        height="400" width="400" 
        columnCount="4" rowCount="4" 
        fontSize="30" fontWeight="bold"
        direction="horizontal" 
        dataProvider="{myDP}" 
        allowMultipleSelection="true" 
        offscreenExtraRowsOrColumns="2" 
        itemsChangeEffect="{myDTLE}" />

    <mx:Button 
        label="Delete Selected Item(s)" 
        click="deleteItems();"/>
    <mx:Button 
        label="Add Item" 
        click="addItems();"/>
</mx:Application>
The executing SWF file for the previous example is shown below: