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.
Note: If you specify the value of the text property
by using a string directly in MXML, Flex collapses white space characters.
If you specify the value of the text property in ActionScript,
Flex does not collapse white space characters.
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 -->
<s:Application
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"
height="400">
<s:layout>
<s:VerticalLayout/>
</s:layout>
<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>
</s: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.
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 -->
<s:Application
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"
initialize="initText()">
<fx: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.";
}
</fx:Script>
<mx:Text width="450" id="myText"/>
</s:Application>
The executing SWF file for the previous example is shown below:
The following example uses an <fx:Script> tag
with a variable in a CDATA section to set the text property:
<?xml version="1.0"?>
<!-- textcontrols/VarText.mxml -->
<s:Application
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark">
<fx: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.";
]]>
</fx:Script>
<mx:Text width="450" text="{myText}"/>
</s: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.
