Recipe 8.1. Creating Text that You Can Modify at Runtime

Problem

You want to create a text field that can be controlled by ActionScript (in order to update the text content at runtime or animate using ActionScript).

Solution

Create a dynamic text field in the same way you would create a static text field (see Recipe 7.1), except that instead of selecting Static Text from the text type menu, choose Dynamic Text. Also, give the text field an instance name.

Alternatively, you can create dynamic text fields at runtime using the createTextField( ) ActionScript method:

 // Create a new dynamic text field in current timeline. var tField:TextField = this.createTextField("tField", 1, 0, 0, 100, 20); 

Discussion

If you want to be able to control text at runtime, you must use dynamic or input text fields. Although you can place static text in your movie at authoring time, Action-Script knows little about those text fields. However, ActionScript can access dynamic and input text fields while the movie is playing.

Technically, ActionScript is capable of reading the contents of static text fields. However, static text fields are not objects, and ActionScript does not have control over them as it does with dynamic and input text fields. Fortunately, while dynamic text fields are drastically different from static text in terms of what you can do with them, the process for creating a dynamic text field is almost identical to creating a static text field. Here are the steps you should follow:

1. Select the Text tool either by clicking the Text button in the toolbar or by pressing the keyboard shortcut (T).

2. Open the Property inspector and make sure that Dynamic Text is selected from the text type menu.

3. Draw a text field on the stage using the Text tool by clicking the mouse button and dragging out the text field outline. Unlike with static text fields, you can set a dynamic text field height in addition to its width.

4. When you release the mouse button to stop drawing the text field, the text field is automatically selected, and the text input cursor appears within it so that you can enter text if you want. However, unlike static text fields, you do not have to enter text into a dynamic text field at authoring time, and so you can choose to deselect the field without entering any values.

5. Give the dynamic text field object an instance name. Make sure that the text field is selected, and then specify an instance name in the Property inspector. The instance name must adhere to the ActionScript rules for naming identifiers. In simple terms, the name cannot include spaces and cannot begin with a number, and the name should contain only letters, numbers, and the underscore character.

You must always assign an instance name to dynamic text fields. Otherwise, Flash won't know how to refer to the text field via ActionScript.

Technically, it is possible to assign text to text fields even if they don't have instance names. It is possible to assign a variable name to a text field instead. However, assignment of variable names to text fields continues to exist for legacy purposes for compatibility with Flash 5 and earlier. But it is no longer recommended that you assign a variable name to a text field. You should always use an instance name, as discussed in this recipe.

Flash also allows you to create dynamic text fields at runtime using ActionScript instead of drawing it on the stage at authoring time. The method for doing this is createTextField( ), and you can invoke it from any movie clip (including the main timeline) in order to create a newdynamic text field within the clip. In order to use createTextField( ), you must know several pieces of information:

Instance name

You must provide the method with an instance name for the new text field.

Depth

All text fields (as well as movie clips and buttons) must have a unique, numeric depth value. Generally speaking, the depth value should be a positive number starting at 1. Make sure to always use a unique depth value, because if you use a value that has already been assigned to another object, the original object will be deleted.

x- and y-coordinates

You must provide Flash with the coordinates at which to place the new text field within the coordinate system of the movie clip.

Width and height

You must provide Flash with the width and height (in pixels) of the new text field to create.

The createTextField( ) method returns a reference to the newly created text field (as of Flash Player 8).

Here is an example of how you can create a dynamic text field in the current movie clip. This example creates a text field named tField that has a depth of 1, is positioned at 120,50, and has dimensions of 100 x 20 pixels.

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

If you don't know the exact dimensions of the text field that you want to create (because the dimensions are to be determined by the text you assign it via ActionScript), you can assign the value 0 to both the height and width when creating the text field, and then set the entire text field to autosize based on the contents. Likewise, you can always modify the x and y coordinates of the text field later on using the _x and _y properties.