Getting Started

The dndList component is very easy to setup. In fact we can do it in a few minutes.

The List component is designed to list and display information. The list has a property called "items". This property is an array of objects. When the list is being rendered it loops through each object in the items array and gets the value of the obects label property and displays that text to the user. You do not manipulate the items array directly. You would add items to the list by using the addItem or addItemAt methods or assigning an array to the List.dataProvider property.

You can add new rows of information by code or by going into the property inspector and adding new items to the Label and Data arrays. The text of each item in the Label array will be displayed to the user when the application is run. The Data array holds the values associated to the label and is associated by the index. There are times when you do not need to use the Data array. The list will still work without it.

To add items by code you can assign an array of objects to the dataProvider or use the built in list methods. Both examples will create the same result: 

// Method 1
// create a new array of objects
var myDataProvider = new Array();
myDataProvider.push ( {label:"First Item"} );
myDataProvider.push ( {label:"Second Item"} );
myDataProvider.push ( {label:"Third Item"} );
// assign to the list dataprovider
theList.dataProvider = myDataProvider;

// Method 2
theList.addItem({label:"First Item"});
theList.addItem({label:"Second Item"});
theList.addItem({label:"Third Item"});

Using that code the List will look like this:

When you want to know what item a user selects then check the selectedItem property. You can listen for the "change" or "singleClick" event and check the List.selectedItem property. 

// Change Event
var itemSelectListener = new Object()
itemSelectListener.change = function(evt) {
	// trace when a item is clicked
	var selectedItem = evt.target.selectedItem;
	trace("You selected " + selectedItem.label);
}
theList.addEventListener("change", itemSelectListener);

After you set up the List you may want to change the label of the items. By default the List uses the label property to get the text to display in the List. If you want to change the label text in any way you can change the labelField property or use the labelFunction function. 

// create a new array of objects
var myDataProvider = new Array();
myDataProvider.push({label:"dndList", price:34.95});
myDataProvider.push({label:"dndTree", price:34.95});
myDataProvider.push({label:"dndDataGrid", price:34.95});
// assign to the list dataprovider
theList.dataProvider = myDataProvider;
//set the label to use 
theList.labelFunction = function(theItem) {
	// this label function checks if a label 
	var label = theItem.label;
	var price = theItem.price;
	
	return label + " - $ " + price;
}

Here is the List using our labelFunction:


One of common feature in List controls is the rename or edit ability. The dndList has this built in. You double click on the label and an edit field or rename field appears. You can also use the context menu and select "Rename Item". You can restrict the text entered in, validate it, call it manually, disable it for certain items, disable it from appearing on double clicks or disable it completely.

It is common to want to show custom images, icons or movieclips in a List. For images you want to use as icons that will exist in the library use the iconFunction. It is better to use the iconFunction to set icons then load them in externally. See the icon example that is included. For loading in images from outside the swf we must use a cell renderer. A cell renderer gives you the ability to design the look and feel of the List cell. A cell is the column space inside the row of the List. You are able to layout and position the elements in the cell by attaching movieclips or components with ActionScript code. For dynamically loading in external images a cellrenderer has been made for you. See dynamic images example.

Dynamic external images example:

dynamic

We can make an working List file in 5 minutes like the ones described above,

  1. Create a new project and drag the dndList component to the stage and give it the instance name "theList".
  2. Save the file as ListExample.fla
  3. Now go into the actions panel on frame 1. Do not go into the actions for the dndList component but for the frame.
Type in this code:
theList.addItem({label:"First Item"});
theList.addItem({label:"Second Item"});
theList.addItem({label:"Third Item"});

Test the movie. Try dragging and dropping. Try double-clicking on a item's label. There is a similar finished example of this tutorial in the examples folder.

The dndList has many more features and benefits. Many examples are included and the help documentation provides numerous code examples.

More information is available on the dndList online at http://www.drumbeatinsight.com/examples/dndList/help/index.html. It is extended off the Macromedia List component and inherits all of it features. You can also learn and follow any Macromedia List example.

Documentation for these classes are included within the Macromedia Flash Help Panel.

Numerous examples have been included and will show you how to do the following:

It also comes with drag and drop classes. These allow you to drag and drop a movieclip onto a dndList and insert new items to the List. You can also use these classes to drag and drop a movieclip onto another movieclip and generate events. View the "drag & drop from a movieclip to a List" example to see this process in action.

© Drumbeat Insight 2006