Work with a DataProvider

You can create a simple data provider for the ComboBox, List, and TileList components by clicking the dataProvider parameter on the Parameters tab of the Property inspector or the Component inspector.

If you double-click the value cell, which initially shows an empty Array, you will open the Values dialog box, which allows you to enter multiple label and data values to create the data provider.

Values dialog box for dataProvider

Click the plus sign to add an item to the dataProvider. Click the minus sign to delete an item. Click the up arrow to move a selected item up in the list or click the down arrow to move a selected item down in the list. The following illustration shows a Values dialog box that creates a list of children’s names and their birthdays.

Values dialog box with data

The Array you create consists of pairs of label and value fields. The label fields are label and data and the value fields are the children’s names and their birthdays. The label field identifies the content that appears in the List, which in this case is the names of the children. The resulting ComboBox looks like this:

The ComboBox populated by the DataProvider

When you finish adding data, click OK to close the dialog box. The Array in the dataProvider parameter is now populated with the items that you created.

dataProvider parameter with data

You can access the label and data values that you created by using ActionScript to access the component’s dataProvider property.

You can create a DataProvider by creating the data in an Array or XML object and providing the object as the value parameter to the DataProvider constructor.

The following example populates a List component, which is a single column of rows, with the names of several children and their birthdays. The example defines the list in the items Array and supplies it as the parameter when it creates the DataProvider instance ( new DataProvider(items) ) and assigns it to the dataProvider property of the List component.

import fl.controls.List; 
import fl.data.DataProvider; 
 
var aList:List = new List(); 
var items:Array = [ 
{label:"David", data:"11/19/1995"}, 
{label:"Colleen", data:"4/20/1993"}, 
{label:"Sharon", data:"9/06/1997"}, 
{label:"Ronnie", data:"7/6/1993"}, 
{label:"James", data:"2/15/1994"}, 
]; 
aList.dataProvider = new DataProvider(items); 
addChild(aList); 
aList.move(150,150);

The Array consists of pairs of label and value fields. The label fields are label and data and the value fields are the children’s names and their birthdays. The label field identifies the content that appears in the List, which in this case is the names of the children. The resulting List looks like this:

A List populated by a DataProvider

The value of the data field is available when the user selects an item in the list by clicking it and causing a change event. The following example adds a TextArea ( aTa ) and an event handler ( changeHandler ) to the preceding example to display the child’s birthday when a user selects a name in the List.

import fl.controls.List; 
import fl.controls.TextArea; 
import flash.events.Event; 
import fl.data.DataProvider; 
 
var aList:List = new List(); 
var aTa:TextArea = new TextArea(); 
var items:Array = [ 
{label:"David", data:"1/19/1995"}, 
{label:"Colleen", data:"4/20/1993"}, 
{label:"Sharon", data:"9/06/1994"}, 
{label:"Ronnie", data:"7/6/1993"}, 
{label:"James", data:"2/15/1994"}, 
]; 
aList.dataProvider = new DataProvider(items); 
 
addChild(aList); 
addChild(aTa); 
 
aList.move(150,150); 
aTa.move(150, 260); 
 
aList.addEventListener(Event.CHANGE, changeHandler); 
 
function changeHandler(event:Event):void { 
    aTa.text = event.target.selectedItem.data; 
};

Now when a user selects a child’s name in the List, the child’s birthday displays in the TextArea as shown in the following illustration. This is accomplished by the changeHandler() function when it sets the text property of the TextArea ( aTa.text ) to the value of the data field in the selected item ( event.target.selectedItem.data ). The event.target property is the object that triggered the event, which in this case is the List.

Displaying the data field from a List’s DataProvider

You can include data other than text in a DataProvider. The following example includes MovieClips in a DataProvider that supplies data to a TileList. It builds the DataProvider by calling addItem() to add each item after it creates the MovieClip, a colored box.

import fl.data.DataProvider; 
import flash.display.DisplayObject; 
 
var aBox:MovieClip = new MovieClip(); 
var i:uint = 0; 
var colors:Array = new Array(0x00000, 0xFF0000, 0x0000CC, 0x00CC00, 0xFFFF00); 
var colorNames:Array = new Array("Midnight", "Cranberry", "Sky", "Forest", "July"); 
var dp:DataProvider = new DataProvider(); 
for(i=0; i < colors.length; i++) { 
    drawBox(aBox, colors[i]);    // draw box w next color in array 
    dp.addItem( {label:colorNames[i], source:aBox} ); 
} 
aTl.dataProvider = dp; 
aTl.columnWidth = 110; 
aTl.rowHeight = 130; 
aTl.setSize(280,150); 
aTl.move(150, 150); 
aTl.setStyle("contentPadding", 5); 
 
function drawBox(box:MovieClip,color:uint):void { 
            box.graphics.beginFill(color, 1.0); 
            box.graphics.drawRect(0, 0, 100, 100); 
            box.graphics.endFill();        

You can also use XML data (instead of an array) to populate a DataProvider object. For example, the following code stores data in an XML object named employeesXML , and then passes that object as the value parameter of the DataProvider() constructor function:

import fl.controls.DataGrid; 
import fl.data.DataProvider; 
 
var aDg:DataGrid = new DataGrid(); 
addChild(aDg); 
 
var employeesXML:XML =  
    <employees> 
        <employee Name="Edna" ID="22" /> 
        <employee Name="Stu" ID="23" /> 
    </employees>; 
 
var myDP:DataProvider = new DataProvider(employeesXML); 
 
aDg.columns = ["Name", "ID"]; 
aDg.dataProvider = myDP;

You can provide data as attributes of the XML data, as in the previous code, or as properties of the XML data, as in the following code:

var employeesXML:XML =  
    <employees> 
        <employee> 
            <Name>Edna</Name> 
            <ID>22</ID> 
        </employee> 
        <employee> 
            <Name>Stu</Name> 
            <ID>23</ID> 
        </employee> 
    </employees>;

The DataProvider also has a set of methods and properties that allow you to access and manipulate it. You can use the DataProvider API to add, remove, replace, sort, and merge items in a DataProvider.