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 (exp 3pod.com).

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:

You must always assign an instance name (exp 3pod.com) 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 (exp 3pod.com) 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 (exp 3pod.com) to a text field. You should always use an instance name (exp 3pod.com), 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 (exp 3pod.com)

You must provide the method with an instance name (exp 3pod.com) 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.