Designing a Custom UI

The first thing you should do when sitting down to create a custom UI for one of your components is refamiliarize yourself with the component's parameters and their data types. In Figure 11.1, you can see the definition of the RandomSquares component. It contains two number data types, two object data types, two color data types, and a list.

Figure 11.1: The Component Definition dialog box for the RandomSquares component

We'll represent each of these quantities, with the exception of the list, as a simple text field for the user to enter values into. We can implement the list as a combo box, which happens to be in the set of components that Macromedia provides with Flash MX. Fortunately, the ComboBox component is very easy to use, as you will see.

Creating the Interface

Once you have planned out exactly how you will allow the user to change the values of the parameters, you can start to create the interface. The interface consists of two parts: the parameters, which we've already discussed, and a variable on the _root named xch, which is of Object data type. The variable xch is what makes the UI work in the first place. Any variables that are set inside the xch object will be passed to the component as the value for its parameters continuously while the UI is open.

Creating an Object variable and setting variables inside is a very easy task. In Flash MX, Object is an ActionScript class, which simply creates an empty container that you can fill up with variables of any data type, even another Object if you see fit. For example, you can create an xch object, with variables stage_width and stage_height inside, with the following code:

         _root.xch = new Object ();         _root.xch.stage_width = 550.0;         _root.xch.stage_height = 400.0; 

Component 

With this knowledge, go into the Chapter 11 folder on the CD and drag a copy of the file RandomSquares_UI.fla to somewhere on your hard drive. You will also need to grab a copy of the RandomSquaresComponent.fla file because it has one small addition to the version we discussed in Chapter 10. Make sure that both FLA files are in the same directory, and then open the RandomSquaresComponent.fla file. To see the UI that will be created for the component, right-click the instance of the component and click Component Parameters. The window that appears is simply a holder for the SWF of the UI. The sizing of the window is a little quirky, and you will usually need to resize the UI so that you can read all of the text inside. Figure 11.2 shows the custom UI created for the component.

Figure 11.2: The custom UI for the component

As you can see, the UI is simply a line of text fields and one combo box, in which the user enters the parameters of the component. On the right side of each input field is a question mark; if you roll over this question mark, a small tool tip appears, giving a short description of the component. There is also a button at the bottom of the UI that checks if all the values you have entered comply with any requirements of the component. If you were to enter an invalid value—such as a string for the number of squares—the component would draw and click the error-checking button and then open an output window informing you of the error. You can see an example of this in Figure 11.3.

Figure 11.3: Click the Check Parameters button to view a readout of any errors in the values you are using.

Now, close RandomSquaresComponent.fla and open the file RandomSquares_UI.fla. Once you open this file, you will see four layers: three of the layers—Initialization, onEnterFrame, and Parameters Check—handle the functionality of the UI through ActionScript, and the last layer, Parameters, holds all the graphics for the UI. Each of the input fields along the right side of the screen has been given an instance name corresponding to the variable name of the parameter it is associated with. This means that the text field that accepts input for the number of squares the component will create has an instance name "num_squares." To access the value of the text field, you simply reference the text property of the text field like this: num_squares.text. Creating these labels and text fields is repetitive; simply create static text for the label of the parameter, create a input text field for the user to edit, and finally give the text field an instance name.

The combo box is a slightly different story. Open the Components panel by pressing Command/Ctrl+F7 and select Flash UI Components from the drop-down menu, as shown in Figure 11.4. Note that the drop-down menu displays all component sets you have installed, so you may have more or fewer items to choose from.

Figure 11.4: Selecting the Flash UI Components set in the Components panel

The component we are interested in is the ComboBox component. There is already an instance of the component on the stage, but since using the combo box takes a little more effort than any of the other parameter interfaces, let's learn by creating a new one. Go ahead and delete that existing instance and drag a new one to the stage. Once you have an instance on the stage, position it next to the label for the component and give it the instance name color_type_cb. For this component, the combo box is associated with the Color Type parameter, which determines if the squares should be either randomly colored or colored the same. The two possible values are Random and Constant; these are the values that the user will choose from in the combo box. To add the items to the combo box, open the Component Parameters panel and double-click the brackets next to the parameter named Labels (see Figure 11.5).

Figure 11.5: Add the options for the drop-down menu through the Component Parameters panel.

For now, the last graphic to make is the error-checking button at the bottom. There is nothing special about this graphic; it's just a simple button. The main aspect of the button is its actions, which we'll code later.

Associating Actions with Graphics

With the graphics of the UI created, you are now only left with the actions, which will handle many things for the UI. The first thing you need to do is create an Object named xch if one does not already exist. You place these actions in the layer named Initialization. The layer also contains additional actions, which set up the component by setting the text fields and combo box with the values of the parameters from the last time the user had the UI opened. Because of this, the actions need to be executed only once when the UI is first opened; therefore, the actions are placed in the onLoad event. The onLoad event is a function, which when set on a movie's Timeline is called the instant the movie clip appears in the Timeline.

In Listing 11.1, you'll find the complete code used in the movie, which is found in the Initialization layer. Note that the code first creates the xch object if one does not already exist, and next displays the values of the parameters as they were when the UI was opened.

Listing 11.1: The onLoad Event for the UI

           // onLoad event that sets the values of the parameters to           // what the user had last time the UI was open           _root.onLoad = function ()           {              // check if the xch object already exists              if (_root.xch == undefined)              {                 // create the xch object                 _root.xch = new Object ();              }              // set the text fields to the parameters in the xch object              this.num_squares.text = this.xch.num_squares;              if (this.xch.color_type == "Random") {                 this.color_type_cb.setSelectedIndex (0);              }              else {                 this.color_type_cb.setSelectedIndex (1);              }              this.fill_color.text = this.xch.fill_color;              this.border_color.text = this.xch.border_color;              this.border_thickness.text = this.xch.border_thickness;              this.dimensions_range_max.text = this.xch.dimensions_range.max;              this.dimensions_range_min.text = this.xch.dimensions_range.min;              this.stage_dimensions_width.text = this.xch.stage_dimensions.width;              this.stage_dimensions_height.text = this.xch.stage_dimensions.height;           } 

Most of the code is straightforward, except for the lines with the conditional statements concerning the call to the setSelectedIndex function. The combo box component has many methods attached to it for handling its functionality through ActionScript, one of them being setSelectedIndex. The method takes one argument, a number corresponding to an item in the combo box, and then sets the selected item for the combo box. The number 0 corresponds to the first entry, Random, and the number 1 corresponds to the second entry, Constant. This is why you need to use an if statement to set the selected item depending on the value of the Color Type parameter.

After the initialization of the values in the text fields and combo box, you need to write the code that will continuously take the values set by the user and place them in the xch object. If you create an onEnterFrame function in the _root, then that function will be called every frame the movie is opened. That event handler will be used to update the values in the xch object with those that the user has entered. The code to do this is in Listing 11.2.

Listing 11.2: Updating the xch Object Values with the User's Values

           // onEnterFrame event that takes all of the user's input and           // sets it in the xch object           _root.onEnterFrame = function ()           {              this.xch.num_squares = Number (this.num_squares.text);              this.xch.color_type = this.color_type_cb.getSelectedItem ().label;              this.xch.fill_color = parseInt (this.fill_color.text);              this.xch.border_color = parseInt (this.border_color.text);              this.xch.border_thickness = Number (this.border_thickness.text);              this.xch.dimensions_range.max = Number (this.dimensions_range_max.text);              this.xch.dimensions_range.min = Number (this.dimensions_range_min.text);              this.xch.stage_dimensions.width = Number           (this.stage_dimensions_width.text);              this.xch.stage_dimensions.height = Number           (this.stage_dimensions_height.text);           } 

Finally, we write the code for the error-checking button. The actions for this button are quite long, but also simple. The idea is to do a separate if statement for each parameter that you want to provide error checking for; if you find something wrong with the value that the user entered, then you will do something to notify the user about the error.

Determining whether there is an error can be done in many ways. Since the component we are using has mostly numeric values, we only need to check if a value is of the number data type. You can do this using a few ActionScript functions. Suppose you have a variable named foo; you can use the code in Listing 11.3 to determine if the variable is a number.

Listing 11.3: Determining Whether a Variable Is a Number

           if (Number (foo).toString () == "NaN")           {             // the variable is not a number           }           else           {             // the variable is a number           } 

In the case of your UI, you will check if all of the numeric parameters are entered as numbers, and if any fail to be a number, then you can report it to the user. That is another issue you must decide on: how to inform users that they have entered invalid data. This UI uses a simple trace action. Since the SWF of the UI is run directly in the Flash authoring environment, the trace actions work just as they normally would. So, if you enter unacceptable values while using the UI for the RandomSquares component, an output window will appear to detail what values you need to change. The code listing for the error checking is too long to repeat here, but if you open the actions on the Parameter Check layer, you will see the onRelease button handler that has been written for it.

So far you have done quite a bit of work, but you are not home free yet. The final step is to set the custom UI for the component. Open the RandomSquaresComponent.fla file. In the library, right-click the component and select Component Definition. In the middle of the dialog box is a text field labeled RandomSquares_UI.swf (embedded). This is because the UI has already been embedded into the FLA. However, before the UI was embedded it read (none). When that is the case you have to set the Custom UI yourself. To do this click the Set button on the right. The dialog box that appears here has a few options, but you are only interested in two settings. As Figure 11.6 shows, you want to set the Type radio button to embedding the custom UI movie, and the Display radio button to displaying in the Components Parameters panel. You also need to specify the file path to the SWF of the custom UI, which can be either absolute or relative to the directory the component is in.

Figure 11.6: You can embed the UI movie into the component and make the UI display only in the Component Parameters panel.

Next, click OK in both dialog boxes and test your UI by opening the Component Parameters panel. A practical feature of the UI is that once you have embedded it into a component, you no longer need the SWF. That does not mean you should delete the FLA and SWF files of the UI, but you can relocate an FLA that uses the component to anywhere on your computer without worrying about taking the UI along with it.

You are now done with the custom UI! You may have noticed that there is a very formulaic approach to creating a custom UI:

1. Create and position the graphics and text fields that allow the user to change the parameters of the component.

2. Write the code that initializes the UI by taking the current parameters in the component and setting the interface elements' initial values; you should do all this in an onLoad event handler.

3. Write the code that continuously takes the user's values and sets them in the xch object every frame; you should do all this in an onEnterFrame handler.

4. Finally, create a button for error checking, if you feel your UI needs one.