Recipe 13.3. Adding a Menu Form Control

Problem

You want to add a form control that allows the user to select a value or values from a menu.

Solution

Use a ComboBox or List component.

Discussion

The ComboBox and List components provide you with a simple way to add menu form controls to your Flash application. Flash Professional includes a Menu component that requires some slightly more advanced ActionScript than this book discusses, but for the purposes of this discussion, the term "menu" is meant in a general sense. Combo boxes are often referred to in laymen's terms as drop-down or pop-up menus. A combo box will display only one menu item at a time, though you can open and close the menu to display more items at once. A user can select only one item at a time from a combo box. A list, on the other hand, cannot be opened and closed, but instead displays multiple selections at the same time. If the list contains too many items to fit within the vertical space, the list will be made scrollable. Though lists allow a user to select only one item at a time by default, it is possible to enable them to accept multiple selections.

You can add either a combo box or a list component by dragging an instance from the Components panel onto the stage. After you've created the instance, you should be sure to give it an instance name (exp 3pod.com) using the Property inspector. The instance name (exp 3pod.com) provides the way in which you can later retrieve the selected value or values from the menu form control.

The next thing you should do is add values to the component instance. Without values within the menu control, it would be of little use to someone trying to make a selection. There are a variety of ways in which you can add values to menu form controls, including adding values using a graphical user interface and by way of Action-Script code.

Adding values through the graphical user interface (via the Component Inspector panel or the Property inspector) has the advantage that you don't need to know ActionScript to add values. And for short lists of values, this technique will work just fine. When you select your combo box or list instance and open the Property inspector or Component Inspector panel, you will see that among the available parameters are two called "labels" and "data." The labels parameter determines the values that get displayed in the form control. The data parameter allows you to specify additional values that are associated with the labels, but hidden from the user. Setting the data parameter is optional, but you should be sure to set the labels parameter for each form control, or else the user will not be able to see what he is selecting. In many cases, you may not need to specify any data values. It depends on the type of application you are building. The data values are usually used when your application needs to interface with a server-side script that requires specially formatted identifiers that differ from the labels that you want to display. For example, you may want to use a combo box to display to the user a list of products, such as Flash, Dreamweaver, ColdFusion, and the like. However, when you submit that information to the server, the server-side script may require specific numeric identifiers that it uses to correspond to the correct information in a database. If you are the one developing the server-side script, then you will know what the server-side requirements are. Alternatively, if you are working with someone else who is developing the server-side script, you may want to consult the developer to ask if there are any such special requirements.

You can add values for the labels and the data parameters in the same way. Within the Component Inspector panel or the Property inspector, double-click in the value column on the right where you see the square brackets displayed ([]). Doing so will open the Values dialog box from which you can add, remove, and reorder the values for the selected parameter.

You can also add values to a menu form control via ActionScript. Adding values with ActionScript obviously means that you need to be somewhat familiar with how to write code, but it also offers several advantages. If the values are actually being retrieved at runtime (e.g., if they are drawn from a database), you must use Action-Script. Additionally, when you want to populate a form control with a long list of values, using the graphical interface can be rather unwieldy, and ActionScript provides a slightly more user-friendly interface at that point. For example, if you want to populate a combo box with the names of the 50 United States, you would likely find it easier to do so using ActionScript rather than the Component Property inspector.

Within ActionScript, there are a few different ways you can add values, depending on whether you want to add one value at a time or add a whole list of values at once. You can add a single value at a time using the addItem( ) method. The addItem( ) method must be called using dot syntax and the instance name (exp 3pod.com) of the combo box or list. The method requires at least one parameterthe label that you want to display. That parameter should be a string value, so place the value in quotation marks. The following is an example that adds the label of Flash to a combo box with an instance name (exp 3pod.com) of ccbProducts:

 

	ccbProducts.addItem("Flash");

You can optionally add both a label and data value with the addItem( ) method by passing two parameters. The first parameter is the value used as the label, and the second parameter is used as the data value. For example:

	ccbProducts.addItem("Flash", 1);

Flash also allows for yet another variation on the addItem( ) method, in which you can pass the method an object that contains a label property and optionally a data property. The effect is the same as with the other variations already discussed, and it involves some slightly more advanced ActionScript knowledge, so that discussion is left for the ActionScript Cookbook (O'Reilly).

If you want to add more than one item at a time to the form control, the data provider technique is the option you'll want to use. You can assign an array of values to the component instance's dataProvider property using ActionScript, and Flash will take care of the rest. If you're familiar with ActionScript arrays, you may know that there are several ways to make new arrays. Any which way you make an array will be fine with the dataProvider property, but for simplicity, I'll show only one way in this discussion. To assign four items to a combo box with an instance name (exp 3pod.com) of ccbProducts using the dataProvider property and an array created using array literal notation:

	ccbProducts.dataProvider = ["Flash", "Dreamweaver", "ColdFusion", "Fireworks"];

Note that to create an array with array literal notation, you should enclose a commadelimited list of quoted string values in square brackets. If you omit the square brackets, the quotes, or the commas, you will get an error.

The preceding example demonstrates how to add items in which each item has a label, but no corresponding data value. It is possible to use an array of objects to assign both label and data values for each item, but that example requires slightly advanced ActionScript knowledge that is left for the ActionScript Cookbook.

A combo box lets a user select one value at a time. A list, on the other hand, can potentially allow a user to select multiple options. In order to enable a list so that the user can choose more than one option at a time, set the multipleSelection parameter to TRue by choosing the list instance and then changing the parameter value using the Component Inspector panel or the Property inspector. When a list's multipleSelection parameter is set to true, the user can select and deselect multiple values by holding down the Ctrl or Command key while clicking on items in the list. Holding down Shift will allow the user to select consecutive items.

You can change the dimensions of either a combo box or a list by using the Property inspector to assign specific values for the width and height or by using the tools to scale and transform the instances. The only exception is that you likely don't want to change the height of a combo box from its default height of 22 pixels. The reason is that a combo box is designed to have a fixed height, and resizing it in the y direction will cause the artwork to appear distorted.