Using the text property
You can use the text property to specify the text string that appears in a text control or to get the text in the control as a plain text String. When you set this property, any HTML tags in the text string appear in the control as literal text.
You cannot specify text formatting when you set the text property, but you can format the text in the control. You can use the text control styles to format all of the text in the control, and you can use the TextRange class to format ranges of text. (For more information on using the TextRange class, see Selecting and modifying text.)
The following code line uses a text property to specify label text:
<mx:Label text="This is a simple text label"/>
The way you specify special characters, including quotation marks, greater than and less than signs, and apostrophes, depends on whether you use them in MXML tags or in ActionScript. It also depends on whether you specify the text directly or wrap the text in a CDATA section.
Specifying special characters in the text property
The following rules specify how to include special characters in the text property of a text control MXML tag, either in a property assignment, such as text="the text", or in the body of an <mx:text> subtag.
In standard text
The following rules determine how you use special characters if you do not use a CDATA section:
- To use the special characters left angle bracket (<), right angle bracket (>), and ampersand (&), insert the XML character entity equivalents of <, >, and &, respectively. You can also use " and ' for double-quotation marks (") and single-quotation marks ('), and you can use numeric character references, such as ¥ for the Yen mark (¥). Do not use any other named character entities; Flex treats them as literal text.
- You cannot use the character that encloses the property text string inside the string. If you surround the string in double-quotation marks ("), use the escape sequence \" for any double-quotation marks in the string. If you surround the string in single-quotation marks (') use the escape sequence \' for any single-quotation marks in the string. You can use single-quotation marks inside a string that is surrounded in double-quotation marks, and double-quotation marks inside a string that is surrounded in single-quotation marks.
- Flex text controls ignore escape characters such as \t or \n in the text property. They ignore or convert to spaces, tabs and line breaks, depending on whether you are specifying a property assignment or an <mx:text> subtag. To include line breaks, put the text in a CDATA section. In the Text control text="string" attribute specifications, you can also specify them as numeric character entities, such as 
 for a Return character or 	 for a Tab character, but you cannot do this in an <mx:text> subtag.
The following code example uses the text property with standard text:
<?xml version="1.0"?>
<!-- textcontrols/StandardText.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" height="400">
<mx:Text width="400" text="This string contains a less than, <,
greater than, >, ampersand, &, apostrophe, ', and
quotation mark "."/>
<mx:Text width="400" text='This string contains a less than, <,
greater than, >, ampersand, &, apostrophe, ', and
quotation mark, ".'/>
<mx:Text width="400">
<mx:text>
This string contains a less than, <, greater than,
>, ampersand, &, apostrophe, ', and quotation mark, ".
</mx:text>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
The resulting application contains three almost identical text controls, each with the following text. The first two controls, however, convert any tabs in the text to spaces.
This string contains a less than, <, greater than, >, ampersand, &,apostrophe, ', and quotation mark, ".
In a CDATA section
If you wrap the text string in the CDATA tag, the following rules apply:
- You cannot use a CDATA section in a property assignment statement in the text control opening tag; you must define the property in an <mx:text> child tag.
- Text inside the CDATA section appears as it is entered, including white space characters. Use literal characters, such as " or < for special characters, and use standard return and tab characters. Character entities, such as >, and backslash-style escape characters, such as \n, appear as literal text.
The following code example follows these CDATA section rules. The second and third lines of text in the <mx:text> tag are not indented because any leading tab or space characters would appear in the displayed text.
<?xml version="1.0"?>
<!-- textcontrols/TextCDATA.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="500">
<mx:Text width="100%">
<mx:text>
<![CDATA[This string contains a less than, <, greater than, >,
ampersand, &, apostrophe, ', return,
tab. and quotation mark, ".]]>
</mx:text>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
The displayed text appears on three lines, as follows:
This string contains a less than, <, greater than, >, ampersand, &, apostrophe, ', return, tab. and quotation mark, ".
Specifying special characters in ActionScript
The following rules specify how to include special characters in a text control when you specify the control's text property value in ActionScript; for example, in an initialization function, or when assigning a string value to a variable that you use to populate the property:
- You cannot use the character that encloses the text string inside the string. If you surround the string in double-quotation marks ("), use the escape sequence \" for any double-quotation marks in the string. If you surround the string in single-quotation marks ('), use the escape sequence \' for any single-quotation marks in the string.
- Use backslash escape characters for special characters, including \t for the tab character, and \n or \r for a return/line feed character combination. You can use the escape character \" for the double-quotation mark and \' for the single-quotation mark.
- In standard text, but not in CDATA sections, you can use the special characters left angle bracket (<), right angle bracket (>), and ampersand (&), by inserting the XML character entity equivalents of <, >, and &, respectively. You can also use " and ' for double-quotation marks ("), and single-quotation marks ('), and you can use numeric character references, such as ¥ for the Yen mark (¥). Do not use any other named character entities; Flex treats them as literal text.
- In CDATA sections only, do not use character entities or references, such as < or ¥ because Flex treats them as literal text. Instead, use the actual character, such as <.
The following example uses an initialization function to set the text property to a string that contains these characters:
<?xml version="1.0"?> <!-- textcontrols/InitText.mxml --> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize="initText()"> <mx:Script>
public function initText():void {
//The following is on one line.
myText.text="This string contains a return, \n, tab, \t, and quotation mark, \". " +
"This string also contains less than, <, greater than, >, " +
"ampersand, &, and apostrophe, ', characters.";
}
</mx:Script>
<mx:Text width="450" id="myText" initialize="initText();"/> </mx:Application>The executing SWF file for the previous example is shown below:
The following example uses an <mx:Script> tag with a variable in a CDATA section to set the text property:
<?xml version="1.0"?>
<!-- textcontrols/VarText.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
[Bindable]
//The following is on one line.
public var myText:String ="This string contains a return, \n, tab, \t, and quotation mark, \". This string also contains less than, <, greater than, <, ampersand, <;, and apostrophe, ', characters.";
]]>
</mx:Script>
<mx:Text width="450" text="{myText}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
The displayed text for each example appears on three lines. The first line ends at the return specified by the \n character. The remaining text wraps onto a third line because it is too long to fit on a single line. (Note: Although the tab character may be noticeable in the following output, it is included in the right location.)
This string contains a return, , tab, , and quotation mark, ". This string also contains less than, <, greater than, >, ampersand, &, and apostrophe, ', characters.
