01. v1 Components, We Hardly Knew Ye   02. Button Component   03. Alert Component   04. Checkbox Component   05. Radio Buttons   06. The List Box family of Components   07. Date Chooser Component   08. Date Field Component   09. Label Component

10. Loader / Progress Bar Components   11. Numeric Stepper Component   12. Text Area/Input Components   13. Menu / Menu Bar Components   14. Scroll Pane Component   15. Window Component   16. Tree Component   17. Accordion Component   18. Conclusion

go to previous page

- discuss this tutorial -

go to next page

06. The List Box family of Components

There are three components that fall into the List Box family of components and are very similar in the way that they work. These are the List Box, Combo Box and the Grid component. Instead of creating separate examples for each of them, let's examine them together in a running example that includes all three. In doing so, you will see the similarities between them and also the different ways in which to populate and use them. Use the following screenshot as a guide when laying out your example Flash application.

1. Start a new FLA.
   
   
2. Create a new layer. Label the topmost layer Actions and the one below it, Form Elements.
   
   
3. Drag a ComboBox, ListBox and Grid component on Stage and place them as shown in the screenshot, above. If you wish, you can label each with a Static Textfield, as I have done, to make it easier for you to differentiate them (although their Live Previews should be enough for you to do this just by looking at them.)
   
   
4. Using the Property Inspector, give the ComboBox the instance name myComboBox. Similarly, give the ListBox and Grid components the instance names myListBox and myGrid.
   

Combo Box

The ComboBox component is one of the easiest components to use. It allows you to display a list of data but does not take up as much space on screen as a ListBox component. Unlike a ListBox component, which can default to not having any of its items selected, the first item in a ComboBox is selected by default. The first item in a combo box is usually a prompt for the user to select one of the other items (e.g. "Please select your country...")

Without further ado, let's jump in and see the simplest way to use a ComboBox. In this example, you will be setting the labels of the ComboBox manually using the Property Inspector (PI). In the example with the ListBox, later, you will see how to do this through code.

1. Make sure you have followed instructions 1-4 in the section on The List Box family of Components, above, to set up your FLA.
   
   
2. Click on the myComboBox component instance to select it and enter four labels for it by clicking on the Labels cell and using the Values dialog. (Use the + button in the Values dialog to create the new label values.) It is possible, though not necessary, to give each item in a ComboBox a separate data value. In the next example, you will see an application where this will be necessary, but you can ignore it for now.
   
   
   
   
3. Enter the following script in Frame 1 of the Actions layer:
   

   myComboBoxListener = new Object();
   myComboBoxListener.change = function(eventObj)
   {
       var eventSource = eventObj.target;
              
       var theSelectedItem = eventSource.selectedItem;
       var theSelectedItemLabel = theSelectedItem.label;
              
       trace ( "You selected "+theSelectedItemLabel+".");
   } 
   myComboBox.addEventListener ("change", myComboBoxListener);

4. Test the movie, select an item from the ComboBox and note the message that gets traced out into the Output window.
   

In this simple example, you set up a listener for the ComboBox to listen for change events. Change events get fired whenever the user changes the selected item in the Combo Box. The event handler gets called with an Event Object that has a target property that points to the ComboBox instance that the event originated from. You can get the selectedItem object for this ComboBox instance using its selectedItem property. The selectedItem object, in turn, has data and label properties. The handler ends by tracing out the label of the selected item to the Output window.

Although easy to use, the ComboBox is also quite powerful and contains a myriad of events and methods for doing anything from responding to the Enter key being pressed on a ComboBox instance to when the user rolls over (as opposed to selects) an item within the ComboBox.

You may be wondering why I grouped the ComboBox along with the List and Grid components since, in appearance at least, it is very different. The reason is because the ComboBox actually contains a List Box -- the drop down that appears is none other than an instance of the List Box component, which you will be seeing next.

List Box

In the Combo Box example, above, you saw how to populate a list of labels manually, using the Property Inspector. Although it is definitely possible to do things this way (and perhaps even desirable for quick and dirty applications), more often than not you will be receiving this data from the server side and will need to populate a Combo Box or List Box dynamically at runtime. In this example, I will show you how to do this using the List Box.

1. Make sure you have followed instructions 1-4 in the section on The List Box family of Components, above, to set up your FLA.
   
   
2. Add the following script to Frame 1 of the Actions layer:
   

   // create the items
   var item1 = {label: "Organic cotton underwear", data: 7.25};
   var item2 = {label: "Organic T-Shirt", data: 15};
   var item3 = {label: "Recycled Office Paper", data: 6.99};
   var item4 = {label: "Organic Cola", data: 1.25}; 
   // populate the list box
   myListBox.addItem(item1);
   myListBox.addItem(item2);
   myListBox.addItem(item3);
   myListBox.addItem ( item4 );
              
   // listener
   myListBoxListener = new Object();
   myListBoxListener.change = function ( eventObj )
   {
       var eventSource = eventObj.target;
              
       var theSelectedItem = eventSource.selectedItem;
       var theSelectedItemLabel = theSelectedItem.label;
       var theSelectedItemData = theSelectedItem.data;
              
       trace(theSelectedItemLabel+" costs £" +theSelectedItemData);
   }
              
   myListBox.addEventListener ("change", myListBoxListener);

3. Test the movie and click on the various items in the List Box and notice the messages traced out in the Output window.

The code in this example is pretty much self-descriptive. First you create the four items as objects with label and data properties and then use the addItem() method of the List Box component to add them to the component. Finally, you create a listener for the change event, just as you did for the Combo Box example and trace out the cost of the currently selected item.

The Grid

The most complex of the the three List Box family of components is the Grid. You can think of a Grid as a multi-column list box. In fact, this is exactly how the component was architected. Unlike the List Box and Combo Box components, which can only have label and data properties in their data sources, the Grid can have any number of custom columns. In this example you will see how to set up a three column grid.

1. Make sure you have followed instructions 1-4 in the section on The List Box family of Components, above, to set up your FLA.
   
   
2. Add the following script to Frame 1 of the Actions layer:
   

   // create the items
   var item1 = {Product: "Underwear", Price: 7.25, Quantity: 3};
   var item2 = {Product: "T-Shirt", Price: 15, Quantity: 1};
   var item3 = {Product: "Paper", Price: 6.99, Quantity: 7};
   var item4 = {Product: "Cola", Price: 1.25, Quantity: 24};            
   // populate the grid
   myGrid.addItem(item1);
   myGrid.addItem(item2);
   myGrid.addItem(item3);
   myGrid.addItem(item4);
              
   // listener
   myGridListener = new Object();
              
   myGridListener.change = function ( eventObj )
   {
       var eventSource = eventObj.target;
              
       var theSelectedItem = eventSource.selectedItem;
       var theSelectedItemName = theSelectedItem.Product;
       var theSelectedItemPrice = theSelectedItem.Price;
       var theSelectedItemQuantity = theSelectedItem.Quantity;
              
       trace
       ( 
           theSelectedItemName 
           + " costs £" + theSelectedItemPrice 
           + " (" + theSelectedItemQuantity + " left in stock)"            
       );
   }
              
   myGrid.addEventListener("change", myGridListener);

3. Test the movie and click on the various items in the Grid and notice the messages traced out in the Output window.

Notice, if you will, how similar the code in this example is to the code in the List Box component example. The difference is that the item objects for the Grid contain custom properties (Product, Price and Quantity) instead of label and data. Also notice how we can query the selected item in a Grid directly to learn the values of its properties. The trace in the change() event handler is broken up over several lines to make it easier to see the message being constructed. Finally, note that the Grid automatically creates your header fields for you using the names of the properties in your items. This is actually a mixed blessing: For the names to display correctly, you had to use capital letters to start the names of the properties. This is actually bad practice. Property names, like method names should start with a lowercase letter.

There is a way to display a column name in the header of the grid that is independent of the name of the property for that column, but it is messy. Here's one way of doing it:

1. Alter the script in Frame 1 of the Actions layer to match the listing below:
   

   // create the items
   var item1 = {product: "Underwear", price: 7.25, quantity: 3};
   var item2 = {product: "T-Shirt", price: 15, quantity: 1};
   var item3 = {product: "Paper", price: 6.99, quantity: 7};
   var item4 = {product: "Cola", price: 1.25, quantity: 24};
   // populate the list box
   myGrid.addItem(item1);
   myGrid.addItem(item2);
   myGrid.addItem(item3);
   myGrid.addItem(item4);
              
   // set the displayed header independently of the
   // column (property) name
   myGrid.getColumnAt(0).headerText = "Product Name";
   myGrid.getColumnAt(1).headerText = "Price";
   myGrid.getColumnAt(2).headerText = "Quantity Left";
              
   // listener
   myGridListener = new Object();
              
   myGridListener.change = function ( eventObj )
   {
       var eventSource = eventObj.target;
              
       var theSelectedItem = eventSource.selectedItem;
       var theSelectedItemName = theSelectedItem.product;
       var theSelectedItemPrice = theSelectedItem.price;
       var theSelectedItemQuantity = theSelectedItem.quantity;
              
       trace
       ( 
           theSelectedItemName 
           + " costs £" + theSelectedItemPrice 
           + " (" + theSelectedItemQuantity + " left in stock)";          
       );
   }
              
   myGrid.addEventListener("change", myGridListener);
   

2. Test the movie and notice how the column names displayed in the header differ from the property names used for the columns.
   The problem I have with this method is that it should not be this hard to give a column a name that is separate from the name of its data property. Almost any application that uses a grid will require this functionality.

If you haven't been following along in Flash, you can find the completed FLA with all three of the previous examples, combo_list_grid.fla, in your downloads. You can play with a slightly modified version, below, where I've replaced the traces with messages displayed in a TextArea component. (To see how to do this, see the exercises in the Check Box and Radio Button sections.)

go to previous page

- discuss this tutorial -

go to next page