Recipe 8.11. Specifying Wrapping of Multiline Fields

Problem

You want to set the word wrapping setting for a multiline text field or text area.

Solution

If you are using a text area component, set the wordWrap parameter to TRue.

For a text field, choose the appropriate selection in the Line type menu (see Recipe 8. 9 for more information) in order to accomplish this at authoring time. Set the value of the wordWrap property using ActionScript to modify word wrapping at runtime.

Discussion

If you are working with a text area component, the default behavior is that it wraps words. You can toggle the wordWrap parameter on and off, which can be found in the Component Inspector panel. Select the instance on stage, open the Component Inspector panel, and change the value of the wordWrap parameter. A value of true (the default setting) makes the text wrap to the next line if and when it is too long to fit within the horizontal boundaries of the text area. A value of false means that new lines appear only when they have been placed there by way of a newline, carriage return, or form feed character. (In addition, if the text area is configured to render HTML, <p> and <br> tags will cause new lines of text.) Otherwise, the text continues to extend horizontally, even though it may not fit within the boundaries of the viewable area.

There are two ways to specify the word wrapping settings for multiline text field: one for authoring time control, and another for runtime control. Both ways result in the same effect at runtime, but the former is done using the Property inspector, and the latter is done with ActionScript.

When a multiline text field is not set to wrap words, new lines are created only when a newline character is encountered (in the case of dynamic text being set at runtime) or when the user enters a carriage return (for input text fields). Therefore, in non-word- wrapping text fields, some text might appear outside of the text field's horizontal viewable area. By setting the text field to wrap words, Flash will intelligently wrap the text to a newline so that all the text fits within the text field horizontally (though it still may not fit within the text field verticallysee Recipe 8.10 for information about scrolling text). If possible, Flash will avoid splitting words when it performs a line wrap. However, if a line contains non-breaking text that is too long to fit on a single line, Flash will fill the first line and then wrap to the next line even in the middle of a word.

When you create a multiline text field at authoring time, you can select from either Multiline or Multiline No Wrap in the Line type menu. Each option creates a multiline text field, but the former automatically wraps words and the latter does not.

You can also use ActionScript to control the word wrap by setting the wordWrap property of the text field. By default, wordWrap is set to false, which means that the lines continue, even beyond the visible area of the text field, until a line break or carriage return is encountered. If you set wordWrap to TRue, however, Flash will wrap lines of text to make sure that the contents fit (horizontally) within the viewable area of the text field:

 tField.wordWrap = true;