Recipe 8.2. Changing Text at Runtime

Problem

You want to customize text field at runtime in order to display text retrieved from a text file, a database, user input, and so on.

Solution

Set the value of the text field's text property.

Discussion

Every dynamic and input text field has a text property that controls what is displayed to the user at runtime. You can use ActionScript to set the text property for a text field, and the value you assign to the property is displayed:

	// Display the assigned string value in the text field.
	tMessage.text = "Don't think about pink crocodiles.";

You can also use variables and more complex expressions on the right side of the equals sign (known as an assignment statement):

	// Assign a value to a variable, susername.
	var susername:String = "Fred";

	// Use the susername variable, and concatenate its value with a quoted string
	// to create a dynamic value to assign to the text field. In this case, the
	// text field displays: "Fred, don't think about pink crocodiles.";
	tMessage.text = susername + ", don't think about pink crocodiles.";

If using a multiline text field, you can add line breaks using a newline character. You can use either the special characters \n or \r within the quoted string, or you can use the ActionScript constant, newline. Both are equivalent, but you must use the \n or \r character within quotes, and you must use the newline constant outside of quotes.

	// The following two lines are equivalent, but the first is more convenient.
	tMessage.text = "Don't think about pink crocodiles\n…or yellow walruses.";
	tMessage.text = "Don't think about pink crocodiles" + newline + "…or yellow
	walruses.";

The whole purpose of dynamic text is that you can assign values to it at runtime instead of being limited to authoring time only. This feature is extremely useful in many situations. For example, as in the preceding examples, you might want to customize the output so that the user's name (exp 3pod.com) is included in a message. In more practical situations, you need to use dynamic text any time you want text values on the stage to update based on user interaction. For instance, in a shopping cart, you want the shopper's total purchase price to reflect the items they have selected. Additionally, you can populate dynamic text fields with data drawn from external sources, such as text files, databases, and web services. (These last few examples involve some slightly more complex ActionScript that is not within the scope of this book. For more information, see the ActionScript Cookbook, O'Reilly.)