Using the htmlText property
You use the htmlText property to set or get an HTML-formatted text string. You can also use one tag that is not part of standard HTML, the textFormat tag. For details of supported tags and attributes, see Using tags in HTML text.
You can also specify text formatting by using Flex styles. You can set a base style, such as the font characteristics or the text weight, by using a style, and override the base style in sections of your text by using tags, such as the <font> tag. In the following example, the <mx:Text> tag styles specify blue, italic, 14 point text, and the <mx:htmlText> tag includes HTML tags that override the color and point size.
<?xml version="1.0"?>
<!-- textcontrols/HTMLTags.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
backgroundGradientColors="[#FFFFFF, #FFFFFF]"
>
<mx:Text width="100%" color="blue" fontStyle="italic" fontSize="14">
<mx:htmlText>
<![CDATA[
This is 14 point blue italic text.<br>
<b><font color="#000000" size="10">This text is 10 point black, italic, and bold.</font></b>
]]>
</mx:htmlText>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
This code results in the following output:
Specifying HTML tags and text
To prevent the Flex compiler from generating errors when it encounters HTML tags in the text, use one of the following techniques:
- Wrap your text in a CDATA tag.
- Specify HTML markup by using the <, >, and & character entities in place of the left angle bracket (<), right angle bracket (>), and ampersand (&) HTML delimiters.
Adobe recommends using CDATA sections for all but simple HTML markup, because the character entity technique has significant limitations:
- Extensive HTML markup can be cumbersome to write and difficult to read.
- You must use a complex escape sequence to include the less than and ampersand characters in your text.
For example, to display the following string:
A less than character < and bold text.
without using a CDATA section, you must use the following text:
A less than character &c#060; and <b>bold text</b>.
In a CDATA section, you use the following text:
A less than character < and <b>bold text</b>.
When you specify HTML text for a text control, the following rules apply:
- You cannot use a CDATA section directly in an inline htmlText property in an <mx:Text> tag. You must put the text in an <mx:htmlText> subtag, or in ActionScript code.
- Flex collapses consecutive white space characters, including return, space, and tab characters, in text that you specify in MXML property assignments or ActionScript outside of a CDATA section.
- If you specify the text in a CDATA section, you can use the text control's condenseWhite property to control whether Flex collapses white space. By default, the condenseWhite property is false, and Flex does not collapse white space.
- Use HTML <p> and <br> tags for breaks and paragraphs. In ActionScript CDATA sections you can also use \n escape characters.
- If your HTML text string is surrounded by single- or double-quotation marks because it is in an assignment statement (in other words, if it is not in an <mx:htmlText> tag), you must escape any uses of that quotation character in the string:
- If you use double-quotation marks for the assignment delimiters, use " for the double-quotation mark (") character in your HTML. In ActionScript, you can also use the escape sequence \".
Note: You do not need to escape double-quotation marks if you're loading text from an external file; it is only necessary if you're assigning a string of text in ActionScript.- If you use single-quotation marks for the assignment delimiters, use ' for the single-quotation mark character (') in your HTML. In ActionScript, you can also use the escape sequence \'.
- When you enter HTML-formatted text, you must include attributes of HTML tags in double- or single-quotation marks. Attribute values without quotation marks can produce unexpected results, such as improper rendering of text. You must follow the escaping rules for quotation marks within quotation marks, as described in Escaping special characters in HTML text.
The following example shows some simple HTML formatted text, using MXML and ActionScript to specify the text:
<?xml version="1.0"?>
<!-- textcontrols/HTMLFormattedText.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="500">
<mx:Script><![CDATA[
//The following is on one line.
[Bindable]
public var myHtmlText:String="This string contains <b>less than </b>, <, <b>greater than</b>, >, <b>ampersand</b>, &, and <b>double quotation mark</b>, ", characters.";
]]></mx:Script>
<mx:Text id="htmltext2" width="450" htmlText="{myHtmlText}" />
<mx:Text width="450">
<mx:htmlText>
<!-- The following is on one line. Line breaks would appear in the output. -->
<![CDATA[
This string contains <b>less than</b>, <, <b>greater than </b>, >, <b>ampersand</b>, &, and <b>double quotation mark</b>,", characters.
]]>
</mx:htmlText>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
Each Text control displays the following text:
This string contains less than, <, greater than, >, ampersand, &, and double quotation mark, " characters.
Escaping special characters in HTML text
The rules for escaping special characters in HTML text differ between CDATA sections and standard text.
In CDATA sections
When you specify the htmlText string, the following rules apply:
- In ActionScript, but not in an <mx:htmlText> tag, you can use standard backslash escape sequences for special characters, such as \t for tab and \n for a newline character. You can also use the backslash character to escape many special characters, such as \' and \" for single- and double-quotation marks. You cannot use the combination \<, and a backslash before a return character has no effect on displayed text; it allows you to break the assignment statement across multiple text lines.
- In both ActionScript and the <mx:htmlText> tag, you can use HTML tags and numeric character entities; for example in place of \n, you can use a <br> tag.
- To include a left angle bracket (<), right angle bracket (>), or ampersand (&) character in displayed text, use the corresponding character entities: <, >, and &, respectively. You can also use the " and ' entities for single- and double-quotation marks. These are the only named character entities that Adobe® Flash® Player and Adobe® AIR™ recognize. They recognize numeric entities, such as ¥ for the Yen mark (¥),;however, they do not recognize the corresponding character entity, ¥.
The following code example uses the htmlText property to display formatted text:
<?xml version="1.0"?>
<!-- textcontrols/HTMLTags2.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="500">
<mx:Text width="100%">
<mx:htmlText><![CDATA[<p>This string contains a <b>less than</b>, <.
</p><p>This text is in a new paragraph.<br>This is a new line.</p>]]>
</mx:htmlText>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
This code displays the following text:
This string contains a less than, <. This text is in a new paragraph. This is a new line.
In standard text
The following rules apply:
- You must use character entities, as described in Using the htmlText property, to use the left angle bracket (<), right angle bracket (>), or ampersand (&) character in HTML; for example, when you open a tag or start a character entity.
- You must use the & named entity combined with an HTML numeric character entity to display the less than character (use &#060;) and ampersand character (use &#038;). You can use the standard character entities, >, ", and ', for the greater than, double-quotation mark and single-quotation mark characters, respectively. For all other character entities, use numeric entity combinations, such as &#165;, for the Yen mark (¥).
- In ActionScript, but not in an <mx:htmlText> tag or inline htmlText property, you can use a backslash character to escape special characters, including the tab, newline, and quotation mark characters (but not the ampersand). In all cases, you can use (properly escaped) HTML tags and numeric character entities; for example in place of \n, you can use a <br> tag or &#013; entity.
Using tags in HTML text
When you use the htmlText property, you use a subset of HTML that is supported by Flash Player and AIR, which support the following tags:
- Anchor tag (<a>)
- Bold tag (<b>)
- Break tag (<br>)
- Font tag (<font>)
- Image tag (<img>)
- Italic tag (<i>)
- List item tag (<li>)
- Paragraph tag (<p>)
- Text format tag (<textformat>)
- Underline tag (<u>)
The anchor <a> tag creates a hyperlink and supports the following attributes:
href Specifies the URL of the page to load in the browser. The URL can be absolute or relative to the location of the SWF file that is loading the page.
target Specifies the name of the target window to load the page into.
For example, the following HTML snippet creates the link "Go Home" to the Adobe Web site.
<a href='http://www.adobe.com' target='_blank'>Go Home</a>
You can also define a:link, a:hover, and a:active styles for anchor tags by using style sheets.
The <a> tag does not make the link text blue. You must apply formatting tags to change the text format. You can also define a:link, a:hover, and a:active styles for anchor tags by using style sheets.
The Label, Text, and TextArea controls can dispatch a link event when the user selects a hyperlink in the htmlText property. To generate the link event, prefix the hyperlink destination with event:, as the following example shows:
<?xml version="1.0"?>
<!-- textcontrols/LabelControlLinkEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
borderStyle="solid"
backgroundGradientColors="[#FFFFFF, #FFFFFF]">
<mx:Script>
<![CDATA[
import flash.events.TextEvent;
public function linkHandler(event:TextEvent):void {
myTA.text="The link was clicked.";
// Open the link in a new browser window.
navigateToURL(new URLRequest(event.text), '_blank')
}
]]>
</mx:Script>
<mx:Label selectable="true" link="linkHandler(event);">
<mx:htmlText>
<![CDATA[<a href='event:http://www.adobe.com'>Navigate to Adobe.com.</a>]]>
</mx:htmlText>
</mx:Label>
<mx:TextArea id="myTA"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
The Label control must have the selectable property set to true to generate the link event.
When you use the link event, the event is generated and the text following event: in the hyperlink destination is included in the text property of the event object. However, the hyperlink is not automatically executed; you must execute the hyperlink from within your event handler. This allows you to modify the hyperlink, or even prohibit it from occurring, in your application.
The bold <b> tag renders text as bold. If you use embedded fonts, a boldface font must be available for the font or no text appears. If you use fonts that you expect to reside on the local system of your users, their system may approximate a boldface font if none exists, or it may substitute the normal font face instead of boldface. In either case, the text inside the bold tags will appear.
The following snippet applies boldface to the word bold:
This word is <b>bold</b>.
You cannot use the </b> end tag to override bold formatting that you set for all text in a control by using the fontWeight style.
The break <br> tag creates a line break in the text. This tag has no effect in Label or TextInput controls.
The following snippet starts a new line after the word line:
The next sentence is on a new line.<br>Hello there.
The <font> tag specifies the following font characteristics: color, face, and size.
The font tag supports the following attributes:
color Specifies the text color. You must use hexadecimal (#FFFFFF) color values. Other formats are not supported.
face Specifies the name of the font to use. You can also specify a list of comma-separated font names, in which case Flash Player and AIR choose the first available font. If the specified font is not installed on the playback system, or isn't embedded in the SWF file, Flash Player and AIR choose a substitute font. The following example shows how to set the font face.
size Specifies the size of the font in points. You can also use relative sizes (for example, +2 or -4).
The following example shows the use of the <font> tag:
<?xml version="1.0"?>
<!-- textcontrols/FontTag.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" backgroundGradientColors="[#FFFFFF, #FFFFFF]">
<mx:TextArea height="100" width="250">
<mx:htmlText>
<![CDATA[
You can vary the <font size='20'>font size</font>,<br><font color="#0000FF">color</font>,<br><font face="CourierNew, Courier, Typewriter">face</font>, or<br><font size="18" color="#FF00FF"face="Times, Times New Roman, _serif">any combination of the three.</font>
]]>
</mx:htmlText>
</mx:TextArea>
</mx:Application>
The executing SWF file for the previous example is shown below:
This code results in the following output:
The image <img> tag lets you embed external JPEG, GIF, PNG, and SWF files inside text fields. Text automatically flows around images you embed in text fields. This tag is supported only in dynamic and input text fields that are multiline and wrap their text.
By default, Flash displays media embedded in a text field at full size. To specify dimensions for embedded media, use the <img> tag's height and width attributes.
In general, an image embedded in a text field appears on the line following the <img> tag. However, when the <img> tag is the first character in the text field, the image appears on the first line of the text field.
The <img> tag has one required attribute, src, which specifies the path to an image file. All other attributes are optional.
The <img> tag supports the following attributes:
src Specifies the URL to a GIF, JPEG, PNG, or SWF file. This attribute is required; all other attributes are optional. External files are not displayed until they have downloaded completely.
align Specifies the horizontal alignment of the embedded image within the text field. Valid values are left and right. The default value is left.
height Specifies the height of the image, in pixels.
hspace Specifies the amount of horizontal space that surrounds the image where no text appears. The default value is 8.
id Specifies the identifier for the imported image. This is useful if you want to control the embedded content with ActionScript.
vspace Specifies the amount of vertical space that surrounds the image where no text.
width Specifies the width of the image, in pixels. The default value is 8.
The following example shows the use of the <img> tag and how text can flow around the image:
<?xml version="1.0"?>
<!-- textcontrols/ImgTag.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" backgroundGradientColors="[#FFFFFF, #FFFFFF]" width="300" height="300">
<mx:Text height="100%" width="100%">
<mx:htmlText>
<![CDATA[
<p>You can include an image in your HTML text with the <img> tag.</p><p><img src='../assets/butterfly.gif' width='30' height='30' align='left' hspace='10' vspace='10'>Here is text that follows the image. I'm extending the text by lengthening this sentence until it's long enough to show wrapping around the bottom of the image.</p>
]]>
</mx:htmlText>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
Making hyperlinks out of embedded images
To make a hyperlink out of an embedded image, enclose the <img> tag in an <a> tag, as the following example shows:
<?xml version="1.0"?>
<!-- textcontrols/ImgTagWithHyperlink.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" borderStyle="solid">
<mx:TextArea width="100%" height="100%">
<mx:htmlText>
<![CDATA[
<a href='http://www.adobe.com'><img src='../assets/butterfly.gif'/></a>
Click the image to go to the Adobe home page.
]]>
</mx:htmlText>
</mx:TextArea>
</mx:Application>
The executing SWF file for the previous example is shown below:
When the user moves the mouse pointer over an image that is enclosed by <a> tags, the mouse pointer does not change automatically to a hand icon, as with standard hyperlinks. To display a hand icon, specify buttonMode="true" for the TextArea (or Text) control. Interactivity, such as mouse clicks and key presses, do not register in SWF files that are enclosed by <a> tags.
The italic <i> tag displays the tagged text in italic font. If you're using embedded fonts, an italic font must be available or no text appears. If you use fonts that you expect to reside on the local system of your users, their system may approximate an italic font if none exists, or it may substitute the normal font face instead of italic. In either case, the text inside the italic tags appears.
The following snippet applies italic font to the word italic:
The next word is in <i>italic</i>.
You cannot use the </i> end tag to override italic formatting that you set for all text in a control by using the fontStyle style.
The list item <li> tag ensures that the text that it encloses starts on a new line with a bullet in front of it. You cannot use it for any other type of HTML list item. The ending </li> tag ensures a line break (but </li><li> generates a single line break). Unlike in HTML, you do not surround <li> tags in <ul> tags. For example, the following Flex code generates a bulleted list with two items:
<?xml version="1.0"?>
<!-- textcontrols/BulletedListExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Text>
<mx:htmlText >
<![CDATA[
<p>This is a bulleted list:<li>First Item</li><li>Second Item</li></p>
]]>
</mx:htmlText>
</mx:Text>
</mx:Application>
The executing SWF file for the previous example is shown below:
The paragraph <p> tag creates a new paragraph. The opening <p> tag does not force a line break, but the closing </p> tag does. Unlike in HTML, the <p> tag does not force a double space between paragraphs; the spacing is the same as that generated by the <br> tag.
The <p> tag supports the following attribute:
align Specifies alignment of text in the paragraph; valid values are left, right, center, and justify.
The following snippet generates two centered paragraphs:
<p align="center">This is a first centered paragraph</p> <p align="center">This is a second centered paragraph</p>
Text format tag (<textformat>)
The text format <textformat> tag lets you use a subset of paragraph formatting properties of the TextFormat class in HTML text fields, including line leading, indentation, margins, and tab stops. You can combine text format tags with the built-in HTML tags. The text format tag supports the following attributes:
- blockindent Specifies the indentation, in points, from the left margin to the text in the <textformat> tag body.
- indent Specifies the indentation, in points, from the left margin or the block indent, if any, to the first character in the <textformat> tag body.
- leading Specifies the amount of leading (vertical space) between lines.
- leftmargin Specifies the left margin of the paragraph, in points.
- rightmargin Specifies the right margin of the paragraph, in points.
- tabstops Specifies custom tab stops as an array of nonnegative integers.
The underline <u> tag underlines the tagged text.
The following snippet underlines the word underlined:
The next word is <u>underlined</u>.
You cannot use the </u> end tag to override underlining that you set for all text in a control by using the textDecoration style.