Recipe 11.3 Adding Menus to a Form

11.3.1 Problem

You want to add menus to your form.

11.3.2 Solution

Use combo boxes or list boxes.

11.3.3 Discussion

You can choose from two types of form menus in your Flash movies: combo boxes and list boxes. A combo box is analogous to the standard HTML <SELECT> tag, which is often referred to as a pop-up menu or drop-down list. A combo box allows a user to select one item at a time, and it displays only the selected item when the menu is not in use. Additionally, if you set a combo box's editable property to true (using setEditable(true)), the user can enter a value by typing it into the text area associated with the combo box.

You can populate a combo box one item at a time using the addItem( ) and addItemAt( ) methods. However, it is usually easier to use the setDataProvider( ) method to assign all the menu items at once. You can pass the setDataProvider( ) method a reference to an array or any object that inherits from the DataProvider class, such as a RecordSet object. The combo box is automatically populated with the data provider elements in the order they appear within the data provider object. Here is an example:

// Create a new combo box.
_root.attachMovie("FComboBoxSymbol", "myComboBox_cb", 1);

// Place the combo box at (100,100).
myComboBox_cb._x = 100;
myComboBox_cb._y = 100;

// Create an array to use as the data provider.
menuItems = ["item a", "item b", "item c", "item d"];

// Populate the combo box.
myComboBox_cb.setDataProvider(menuItems);

A list box allows the user to see more than one item at a time. You can populate a list box the same way you would a combo box, that is, by using setDataProvider( ). List boxes also have two additional initialization parameters: the number of menu items to display at a time and a Boolean indicating whether to allow multiple selections. List boxes default to six visible menu items, but you can change this value with setRowCount( ). List boxes do not allow for multiple selections by default, but you can change this using setSelectMultiple(true). Users can then select multiple values by Shift-clicking to select multiple contiguous values or Ctrl-clicking (Windows) or Cmd-clicking (Macintosh) to select multiple, noncontiguous values. Here is an example:

// Create a new list box.
_root.attachMovie("FListBoxSymbol", "myListBox_lb", 1);

// Place the list box at (100,100).
myListBox_lb._x = 100;
myListBox_lb._y = 100;

// Create an array to use as the data provider.
menuItems = ["item a", "item b", "item c", "item d"];

// Populate the list box.
myListBox_lb.setDataProvider(menuItems);

// Set the list box to display three menu items at a time.
myListBox_lb.setRowCount(3);

// Allow the user to select multiple items at once.
myListBox_lb.setSelectMultiple(true);

Each menu item has two properties: label and data. The label value is displayed in the menu, while the data value is available behind the scenes. This allows you to associate data with each item displayed in the menu. When you populate a menu with an array of strings, as shown earlier, the label properties of the menu items correspond to the array elements, but the data properties are left as undefined. It is a best practice to associate both label and data values with each menu item, which you can accomplish using an array of objects, where each object contains both label and data properties. For example:

// Create an array of objects. Each element should have both label and data 
// properties. The label is displayed in the menu, while data is available for
// programmatic use.
menuItems = [{label: "item a", data: "test a"}, {label: "item b", data: "test b"}];

// Populate the menu using the setDataProvider(  ) method, as usual.
myListBox_lb.setDataProvider(menuItems);

11.3.4 See Also

Recipe 11.6