Recipe 8.3. Accepting User Input

Problem

You want to accept user input at runtime.

Solution

Use a text input or text area component.

Alternatively, create an input text field in the same way as you create a dynamic text field (see Recipe 8.1), except that instead of selecting Dynamic Text from the text type menu, select Input Text. Additionally, in most cases you should make sure that input text fields have a border, so that the user can see where to insert text. Optionally, you can create an input text field using ActionScript by first creating a dynamic text field with createTextField( ) and then setting the object's type property to input.

Discussion

Flash provides two ways of accepting text input from the user: components and dynamic text fields. Each has its own advantages and disadvantages, so you should learn about each to best determine which to use.

In the UI components that ship with Flash, you can find two components for accepting user input: TextInput and TextArea. The text input component provides you with a rather simple way to create an input control that looks like a standard HTML text input control. All you need to do is drag-and-drop an instance from the Components panel to the stage, and give it an instance name in the Property inspector. Although the text input component makes it very simple for you to create a way to accept text that the user enters, that is not a distinct advantage over the dynamic text field, because the latter is quite simple as well. However, the text input component does offer at least two advantages. One is that the component is part of the standard UI components, and as such it provides the same common functionality, such as built-in style management (see Chapter 15). That means that you can apply the same styles (such as font color, font face, etc.) to the text input component instances as all other component instances within the movie using just a few lines of simple ActionScript code. You don't have to actually apply the changes to each instance individually. Another advantage is that the text input component has the slightly recessed appearance of a standard HTML text input control. Though you could create that same effect in just a few minutes with the drawing tools, it is convenient to be able to simply drag-and-drop an instance. The flip side is that if you don't want your input control to appear like a standard HTML text input, it is rather difficult to make changes to the appearance of the component in that respect. Furthermore, perhaps the most distinct disadvantage is that a text input component adds 27KB to your .swf file size.

The text area component is much like a standard HTML text area. It is a multiline field with a built-in scrollbar. Like the text input component, the text area component has the advantage of ease of use and built-in style management. It also has the same disadvantages as the text input component.

The other option for accepting user input is an input text field. Input text fields are practically the same as dynamic text fields. In fact, the only difference is that a user can type or paste text into an input text field, something that is not possible with a dynamic text field. Therefore, it should come as no surprise that creating an input text field is almost the same as creating a dynamic text field. You should follow the same instructions as in Recipe 8.1, but in step 2, specify Input Text rather than Dynamic Text. Additionally, in most cases you should add a border, to ensure that the user can see where they can input text. You can add a border to an input text field by selecting it on the stage and pressing the "Show border" button in the Property inspector (see Figure 8-1).

Figure 8-1. Select the "Show border" button in order to display a border around a text field

When you add a border to a text field at authoring time, the border color defaults to black. There is no way to modify this value at authoring time. What's more, when you specify a border for your text field at authoring time, Flash also adds a white background to it. As with the border, you cannot change the color of the background (nor can you turn it off) at authoring time. You can, however, modify these settings at runtime using ActionScript. All dynamic (including input) text fields have four properties related to border and background:

border

This property is either true or false, and determines whether the border shows up. When you choose to turn on the border at authoring time, Flash sets the border property to true.

background

This property is also either true or false, and it determines whether the background shows up. When you turn on the border at authoring time, Flash sets not only the border property to true, but also the background property.

borderColor

This property determines the color value of the border. The default value is 0x000000, but you can assign any number value that represents a valid color.

backgroundColor

This property determines the color value of the background. The default value is 0xFFFFFF, but you can assign any number value that represents a valid color.

Here is an example of some ActionScript that modifies the border and background colors for a text field:

 tField.borderColor = 0x0000FF; tField.backgroundColor = 0xCDCDCD; 

Or, if you want to keep the border on but hide the background you can do so like this:

 tField.background = false; 

Optionally, if you don't want to use the standard border and/or background for a text field, you can add artwork on a layer beneath the text field. If the text field's border and background are off, then the artwork on the lower layer will give the appearance of being the border and background for the text field. This technique enables you to add more complex borders and backgrounds.

You can also create an input text field at runtime using ActionScript. See Recipe 8.1 for more information on creating text fields at runtime, and follow the same process. Then, in addition, set the new text field's type property to input:

 var tInputField:TextField = this.createTextField("tInputField", 1, 120, 50, 100, 20); tInputField.type = "input"; 

If you're adding a text field programmatically and you want to add a border programmatically, you can accomplish that by setting the border property of the text field to true:

 tInputField.border = true; 

Although this approach is not used frequently, it is entirely possible to assign a value to an input text field or text input component instance at authoring time or at runtime. You can assign a text value to an input text field at authoring time in the same way as you can add a value to a dynamic text field. If you want to add a value to a text input component instance at authoring time, enter the value for the text parameter in the Component Inspector panel. If you want to assign a value to an input text field or a text input component at runtime, the code is the same: assign the value to the text property of the instance. For example:

 tInputField.text = "Some value"; 

For an example of why you might use this functionality, consider the following code snippet, which assigns an initial value to an input text field that tells the user what to enter.

 tUserName.text = "<type your name here>"; 

If you want to use an input text field instead of a text area component, follow the preceding instructions. Then, in addition, set the text field to display more than one line of text.