Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_textcontrols_tc.html
blob: 50db266770f69bfd5e694a819d6dc4452b102421 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="DC.Type" content="topic"/>
<meta name="DC.Title" content="MX text controls"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS2db454920e96a9e51e63e3d11c0bf69084-7d84_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>MX text controls</title>
</head>
<body id="WS2db454920e96a9e51e63e3d11c0bf69084-7d84_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d84_verapache"><!-- --></a>
<h1 class="topictitle1">MX text controls</h1>
<div>
<p>
MX text
controls in an Flex application can display
text, let the user enter text, or do both. </p>
<p>Flex defines two sets of components: Spark and MX. The Spark
components are new for Flex 4 and are defined in the spark.* packages.
The MX components shipped in previous releases of Flex and are defined
in the mx.* packages.</p>
<p>Even though you can use both component sets in a single application,
it’s best to use the Spark component set where possible. For information
about the Spark text controls, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache">Spark
text controls</a>.</p>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d3f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d3f_verapache"><!-- --></a>
<h2 class="topictitle2">About MX text controls</h2>
<div>
<p>You use Flex text-based controls to display text and to
let users enter text into your application. The following table
lists the controls, and indicates whether the control can have multiple
lines of input instead of a single line of text, and whether the
control can accept user input:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d913612e58">
<p>MX Control</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d913612e64">
<p>Multiline</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d913612e70">
<p>Allows user Input</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Label.html" target="_blank">Label</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e64 ">
<p>No</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e70 ">
<p>No</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextInput.html" target="_blank">TextInput</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e64 ">
<p>No</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e70 ">
<p>Yes</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Text.html" target="_blank">Text</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e64 ">
<p>Yes</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e70 ">
<p>No</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e64 ">
<p>Yes</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e70 ">
<p>Yes</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/RichTextEditor.html" target="_blank">RichTextEditor</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e64 ">
<p>Yes</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d913612e70 ">
<p>Yes</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>All controls except the RichTextEditor control are single components
with a simple text region. For example, the following code creates
an MX TextInput control in a simple form:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/FormItemLabel.mxml --&gt;
&lt;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"&gt;
&lt;s:Form id="myForm" width="500" backgroundColor="#909090"&gt;
&lt;!-- Use a FormItem to label the field. --&gt;
&lt;s:FormItem label="First Name"&gt;
&lt;s:TextInput id="ti1" width="150"/&gt;
&lt;/s:FormItem&gt;
&lt;/s:Form&gt;
&lt;/s:Application&gt;</pre>
<p>The RichTextEditor control is a compound control; it consists
of a Panel control that contains an MX TextArea control and a ControlBar
with several controls for specifying the text format and HTTP links.
The following image shows a RichTextEditor control: </p>
<div class="figborder">
<img src="images/tc_AboutRichText001.png" alt="The RichTextEditor control is a compound control; it consists of a Panel control that contains a TextArea control and a ControlBar control"/>
</div>
<p>The following code produces the preceding image:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/RTECDATA.mxml --&gt;
&lt;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"&gt;
&lt;mx:RichTextEditor id="rte1" title="Rich Text Editor"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[
&lt;p align='center'&gt;&lt;b&gt;&lt;font size='16'&gt;HTML Text&lt;/font&gt;&lt;/b&gt;
This paragraph has &lt;font color='#006666'&gt;&lt;b&gt;bold teal text.
&lt;/b&gt;&lt;/font&gt;&lt;/p&gt;
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:RichTextEditor&gt;
&lt;/s:Application&gt;</pre>
<p>Flex text-based controls let you set and get text by using the
following properties:</p>
<dl>
<dt class="dlterm">text</dt>
<dd>
<p>Plain text without formatting information. For information
on using the <samp class="codeph">text</samp> property, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using
the text property </a>.</p>
</dd>
<dt class="dlterm">htmlText</dt>
<dd>
<p>Rich text that represents formatting by using a subset of
HTML tags, and can include bulleted text and URL links. For information
on using the <samp class="codeph">htmlText</samp> property, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>.</p>
<p>Both properties set the same
underlying text, but you can use different formats. For example,
you can do the following to set, modify, and get text: </p>
<ul>
<li>
<p>You can set formatted text by using the <samp class="codeph">htmlText</samp> property,
and get it back as a plain text string by using the <samp class="codeph">text</samp> property. </p>
</li>
<li>
<p>You can set formatted text in user-editable text controls
(MX TextInput, TextArea, RichTextEditor) by setting the text string
with the <samp class="codeph">text</samp> property and formatting a section
of this text by using the TextRange class. If you get the text back
by using the <samp class="codeph">htmlText</samp> property, the property string
includes HTML tags for the formatting. For more information on using
the TextRange class, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d44_verapache">Selecting
and modifying text</a>.</p>
</li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache"><!-- --></a>
<h2 class="topictitle2">Using the text property </h2>
<div>
<p>
You
can use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Label.html#text" target="_blank">text</a> 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. </p>
<p>
You cannot specify
text formatting when you set the <samp class="codeph">text</samp> 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 <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/textClasses/TextRange.html" target="_blank">TextRange</a> class
to format ranges of text<strong>. (</strong>For more information on using
the TextRange class, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d44_verapache">Selecting
and modifying text</a>.)</p>
<p>The following code line uses a <samp class="codeph">text</samp> property
to specify label text:</p>
<pre class="codeblock"> &lt;mx:Label text="This is a simple text label"/&gt;</pre>
<p>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.</p>
<div class="note"><span class="notetitle">Note:</span> If you specify the value of the <samp class="codeph">text</samp> property
by using a string directly in MXML, Flex collapses white space characters.
If you specify the value of the <samp class="codeph">text</samp> property in ActionScript,
Flex does not collapse white space characters.</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-8000_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying special characters in
the text property</h3>
<div>
<p>The following rules specify how to include special characters
in the <samp class="codeph">text</samp> property of a text control MXML tag,
either in a property assignment, such as <samp class="codeph">text="the text"</samp>,
or in the body of an <samp class="codeph">&lt;mx:text&gt;</samp> subtag.</p>
<dl>
<dt class="dlterm">In standard text</dt>
<dd>
<p>The following rules determine how you use special characters if
you do not use a CDATA section:</p>
<ul>
<li>
<p>To use the special
characters left angle bracket (&lt;), right angle bracket (&gt;),
and ampersand (&amp;), insert the XML character entity equivalents
of <samp class="codeph">&amp;lt;,</samp>
<samp class="codeph">&amp;gt;</samp>, and <samp class="codeph">&amp;amp;,</samp> respectively.
You can also use <samp class="codeph">&amp;quot;</samp> and <samp class="codeph">&amp;apos;</samp> for
double-quotation marks (") and single-quotation marks ('), and you
can use numeric character references, such as &amp;#165 for the
Yen mark (¥)<samp class="codeph">. </samp>Do not use any other named character
entities; Flex treats them as literal text.</p>
</li>
<li>
<p>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 <samp class="codeph">\"</samp> for any double-quotation
marks in the string. If you surround the string in single-quotation
marks (') use the escape sequence <samp class="codeph">\'</samp> for any single-quotation
marks in the string. You <em>can</em> 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.</p>
</li>
<li>
<p>Flex text controls ignore escape characters such as \t or
\n in the <samp class="codeph">text</samp> property. They ignore or convert
to spaces, tabs and line breaks, depending on whether you are specifying
a property assignment or an <samp class="codeph">&lt;mx:text&gt;</samp> subtag. To
include line breaks, put the text in a CDATA section. In the Text
control <samp class="codeph">text="</samp>
<em>string</em>
<samp class="codeph">"</samp> attribute
specifications, you can also specify them as numeric character entities,
such as &amp;#013; for a Return character or &amp;#009; for a Tab character,
but you cannot do this in an <samp class="codeph">&lt;mx:text&gt;</samp> subtag.</p>
</li>
</ul>
<p>The
following code example uses the <samp class="codeph">text</samp> property with
standard text:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/StandardText.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;mx:Text width="400"
text="This string contains a less than, &amp;lt;,
greater than, &amp;gt;, ampersand, &amp;amp;, apostrophe, ', and
quotation mark &amp;quot;."/&gt;
&lt;mx:Text width="400"
text='This string contains a less than, &amp;lt;,
greater than, &amp;gt;, ampersand, &amp;amp;, apostrophe, &amp;apos;, and
quotation mark, ".'/&gt;
&lt;mx:Text width="400"&gt;
&lt;mx:text&gt;
This string contains a less than, &amp;lt;, greater than,
&amp;gt;, ampersand, &amp;amp;, apostrophe, ', and quotation mark, ".
&lt;/mx:text&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
<p>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.</p>
<pre class="codeblock"> This string contains a less than, &lt;, greater than, &gt;, ampersand, &amp;,apostrophe, ', and quotation mark, ".</pre>
</dd>
<dt class="dlterm">In a CDATA section</dt>
<dd>
<p>If you wrap the text string in the <samp class="codeph">CDATA</samp> tag,
the following rules apply:</p>
<ul>
<li>
<p>You cannot use a CDATA
section in a property assignment statement in the text control opening
tag; you must define the property in an <samp class="codeph">&lt;mx:text&gt;</samp> child
tag.</p>
</li>
<li>
<p>Text inside the CDATA section appears as it is entered, including
white space characters. Use literal characters, such as " or &lt;
for special characters, and use standard return and tab characters.
Character entities, such as &amp;gt;, and backslash-style escape
characters, such as \n, appear as literal text.</p>
</li>
</ul>
<p>The
following code example follows these CDATA section rules. The second
and third lines of text in the <samp class="codeph">&lt;mx:text&gt;</samp> tag
are not indented because any leading tab or space characters would
appear in the displayed text.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextCDATA.mxml --&gt;
&lt;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"
width="500"&gt;
&lt;mx:Text width="100%"&gt;
&lt;mx:text&gt;
&lt;![CDATA[This string contains a less than, &lt;, greater than, &gt;,
ampersand, &amp;, apostrophe, ', return,
tab. and quotation mark, ".]]&gt;
&lt;/mx:text&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
<p>The displayed text appears
on three lines, as follows:</p>
<pre class="codeblock"> This string contains a less than, &lt;, greater than, &gt;,
 ampersand, &amp;, apostrophe, ', return,
 tab. and quotation mark, ". </pre>
</dd>
</dl>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffe_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffe_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying special characters in
ActionScript</h3>
<div>
<p>
The following rules specify how to include
special characters in a text control when you specify the control’s <samp class="codeph">text</samp> 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:</p>
<ul>
<li>
<p>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.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>In standard text, but not in CDATA sections, you can use
the special characters left angle bracket (&lt;), right angle bracket
(&gt;), and ampersand (&amp;), by inserting the XML character entity
equivalents of <samp class="codeph">&amp;lt;,</samp>
<samp class="codeph">&amp;gt;</samp>,
and <samp class="codeph">&amp;amp;</samp>, respectively. You can also use <samp class="codeph">&amp;quot;</samp> and <samp class="codeph">&amp;apos;</samp> for
double-quotation marks ("), and single-quotation marks ('), and
you can use numeric character references, such as <samp class="codeph">&amp;#165;</samp> for
the Yen mark (¥)<samp class="codeph">. </samp>Do not use any other named character entities;
Flex treats them as literal text.</p>
</li>
<li>
<p>In CDATA sections only, do not use character entities or
references, such as <samp class="codeph">&amp;lt;</samp> or &amp;#165; because
Flex treats them as literal text. Instead, use the actual character,
such as &lt;.</p>
</li>
</ul>
<p>The following example uses an initialization function to set
the <samp class="codeph">text</samp> property to a string that contains these
characters: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/InitText.mxml --&gt;
&lt;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()"&gt;
&lt;fx:Script&gt;
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, &amp;lt;, greater than, &amp;gt;, " +
"ampersand, &amp;amp;, and apostrophe, ', characters.";
}
&lt;/fx:Script&gt;
&lt;mx:Text width="450" id="myText"/&gt;
&lt;/s:Application&gt;</pre>
<p>The following example uses an <samp class="codeph">&lt;fx:Script&gt;</samp> tag
with a variable in a CDATA section to set the <samp class="codeph">text</samp> property: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/VarText.mxml --&gt;
&lt;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"&gt;
&lt;fx:Script&gt;
&lt;![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, &lt;, greater than, &lt;, ampersand, &lt;;, and apostrophe, ', characters.";
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Text width="450" text="{myText}"/&gt;
&lt;/s:Application&gt;</pre>
<p>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.)</p>
<pre class="codeblock"> This string contains a return,
 , tab, , and quotation mark, ". This string also contains less than, &lt;,
 greater than, &gt;, ampersand, &amp;, and apostrophe, ', characters.</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache"><!-- --></a>
<h2 class="topictitle2">Using the htmlText property</h2>
<div>
<p>
You use the <samp class="codeph">htmlText</samp> property
to set or get an HTML-formatted text string. You can also use one
tag that is not part of standard HTML, the <samp class="codeph">textFormat</samp> tag.
For details of supported tags and attributes, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache">Using
tags in HTML text</a>.</p>
<p>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 <samp class="codeph">&lt;font&gt;</samp> tag.
In the following example, the <samp class="codeph">&lt;mx:Text&gt;</samp> tag
styles specify blue, italic, 14 point text, and the <samp class="codeph">&lt;mx:htmlText&gt;</samp> tag
includes HTML tags that override the color and point size.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/HTMLTags.mxml --&gt;
&lt;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"&gt;
&lt;mx:Text width="100%" color="blue" fontStyle="italic" fontSize="14"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[
This is 14 point blue italic text.&lt;br&gt;
&lt;b&gt;&lt;font color="#000000" size="10"&gt;This text is 10 point black, italic, and bold.&lt;/font&gt;&lt;/b&gt;
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff9_verapache"><!-- --></a>
<h3 class="topictitle3">Specifying HTML tags and text</h3>
<div>
<p>To prevent the Flex compiler from generating errors when
it encounters HTML tags in the text, use one of the following techniques:</p>
<ul>
<li>
<p>Wrap your text in a <samp class="codeph">CDATA</samp> tag.</p>
</li>
<li>
<p>Specify HTML markup by using the <samp class="codeph">&amp;lt;</samp>, <samp class="codeph">&amp;gt;</samp>,
and <samp class="codeph">&amp;amp;</samp> character entities in place of the
left angle bracket (&lt;), right angle bracket (&gt;), and ampersand
(&amp;) HTML delimiters. </p>
</li>
</ul>
<p>It’ best to use CDATA sections for all but simple HTML markup,
because the character entity technique has significant limitations: </p>
<ul>
<li>
<p>Extensive HTML markup can be cumbersome to write and
difficult to read. </p>
</li>
<li>
<p>You must use a complex escape sequence to include the less
than and ampersand characters in your text.</p>
</li>
</ul>
<p>For example, to display the following string:</p>
<p>A less than character &lt; and <strong>bold text</strong>.</p>
<p>without using a CDATA section, you must use the following text:</p>
<pre class="codeblock"> A less than character &amp;amp;c#060; and &amp;lt;b&amp;gtbold text&amp;lt;/b&amp;gt.</pre>
<p>In a CDATA section, you use the following text:</p>
<pre class="codeblock"> A less than character &amp;lt; and &lt;b&gt;bold text&lt;/b&gt;.</pre>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff8_verapache"><!-- --></a><h4 class="sectiontitle">Specifying
HTML text</h4>
<p>When you specify HTML text for a text control,
the following rules apply:</p>
<ul>
<li>
<p>You cannot use a CDATA
section directly in an inline <samp class="codeph">htmlText</samp> property
in an <samp class="codeph">&lt;mx:Text&gt;</samp> tag. You must put the text
in an <samp class="codeph">&lt;mx:htmlText&gt;</samp> subtag, or in ActionScript
code. </p>
</li>
<li>
<p>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. </p>
</li>
<li>
<p>If you specify the text in a CDATA section, you can use the
text control’s <samp class="codeph">condenseWhite</samp> property to control
whether Flex collapses white space. By default, the <samp class="codeph">condenseWhite</samp> property
is <samp class="codeph">false</samp>, and Flex does not collapse white space. </p>
</li>
<li>
<p>Use HTML &lt;p&gt; and &lt;br&gt; tags for breaks and paragraphs.
In ActionScript CDATA sections you can also use \n escape characters.</p>
</li>
<li>
<p>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 <samp class="codeph">&lt;mx:htmlText&gt;</samp> tag), you
must escape any uses of that quotation character in the string:</p>
<ul>
<li>
<p>If you use double-quotation marks for the assignment delimiters,
use &amp;quot; for the double-quotation mark (") character in your
HTML. In ActionScript, you can also use the escape sequence \".</p>
<div class="note"><span class="notetitle">Note:</span> 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.</div>
</li>
<li>
<p>If you use single-quotation marks for the assignment delimiters,
use &amp;apos; for the single-quotation mark character (') in your
HTML. In ActionScript, you can also use the escape sequence \’.</p>
</li>
</ul>
</li>
<li>
<p>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 <a href="flx_textcontrols_tc.html#WS19f279b149e7481ce38f4a412c12784e04-8000_verapache">Escaping
special characters in HTML text</a>.</p>
</li>
</ul>
<p>The following
example shows some simple HTML formatted text, using MXML and ActionScript
to specify the text:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/HTMLFormattedText.mxml --&gt;
&lt;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"
width="500"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;&lt;![CDATA[
//The following is on one line.
[Bindable]
public var myHtmlText:String="This string contains &lt;b&gt;less than &lt;/b&gt;, &amp;lt;, &lt;b&gt;greater than&lt;/b&gt;, &amp;gt;, &lt;b&gt;ampersand&lt;/b&gt;, &amp;amp;, and &lt;b&gt;double quotation mark&lt;/b&gt;, &amp;quot;, characters.";
]]&gt;&lt;/fx:Script&gt;
&lt;mx:Text id="htmltext2" width="450" htmlText="{myHtmlText}" /&gt;
&lt;mx:Text width="450"&gt;
&lt;mx:htmlText&gt;
&lt;!-- The following is on one line. Line breaks would appear in the output. --&gt;
&lt;![CDATA[
This string contains &lt;b&gt;less than&lt;/b&gt;, &amp;lt;, &lt;b&gt;greater than &lt;/b&gt;, &amp;gt;, &lt;b&gt;ampersand&lt;/b&gt;, &amp;amp;, and &lt;b&gt;double quotation mark&lt;/b&gt;,&amp;quot;, characters.
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested3" id="WS19f279b149e7481ce38f4a412c12784e04-8000_verapache"><a name="WS19f279b149e7481ce38f4a412c12784e04-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Escaping special characters in
HTML text</h4>
<div>
<p>
The
rules for escaping special characters in HTML text differ between
CDATA sections and standard text.</p>
<dl>
<dt class="dlterm">In CDATA sections</dt>
<dd>
<p>When you specify the <samp class="codeph">htmlText</samp> string, the
following rules apply: </p>
<ul>
<li>
<p>In ActionScript, but not in
an <samp class="codeph">&lt;mx:htmlText&gt;</samp> 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 \\xd5 and \" for single-
and double-quotation marks. You cannot use the combination \&lt;,
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.</p>
</li>
<li>
<p>In both ActionScript and the <samp class="codeph">&lt;mx:htmlText&gt;</samp> tag,
you can use HTML tags and numeric character entities; for example
in place of \n, you can use a <samp class="codeph">&lt;br&gt;</samp> tag. </p>
</li>
<li>
<p>To include a left angle bracket (&lt;), right angle bracket
(&gt;), or ampersand (&amp;) character in displayed text, use the
corresponding character entities: <samp class="codeph">&amp;lt;,</samp>
<samp class="codeph">&amp;gt;</samp>,
and <samp class="codeph">&amp;amp;, respectively</samp>. You can also use the <samp class="codeph">&amp;quot;</samp> and <samp class="codeph">&amp;apos;</samp> entities
for single- and double-quotation marks. These are the only named
character entities that Adobe<sup>®</sup> Flash<sup>®</sup> Player and Adobe<sup>®</sup> AIR™ recognize. They recognize numeric entities,
such as <samp class="codeph">&amp;#165;</samp> for the Yen mark (¥),;however,
they do not recognize the corresponding character entity, <samp class="codeph">&amp;yen;</samp>.</p>
<p>The
following code example uses the <samp class="codeph">htmlText</samp> property
to display formatted text:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/HTMLTags2.mxml --&gt;
&lt;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"
width="500"&gt;
&lt;mx:Text width="100%"&gt;
&lt;mx:htmlText&gt;&lt;![CDATA[&lt;p&gt;This string contains a &lt;b&gt;less than&lt;/b&gt;, &amp;lt;.
&lt;/p&gt;&lt;p&gt;This text is in a new paragraph.&lt;br&gt;This is a new line.&lt;/p&gt;]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
</li>
</ul>
</dd>
<dt class="dlterm">In standard text</dt>
<dd>
<p>The following rules apply:</p>
<ul>
<li>
<p>You must use character
entities, as described in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>, to use the left angle bracket (&lt;),
right angle bracket (&gt;), or ampersand (&amp;) character in HTML;
for example, when you open a tag or start a character entity.</p>
</li>
<li>
<p>You must use the <samp class="codeph">&amp;amp;</samp> named entity
combined with an HTML numeric character entity to display the less
than character (use <samp class="codeph">&amp;amp;#060;</samp>) and ampersand
character (use <samp class="codeph">&amp;amp;#038;</samp>). You can use the
standard character entities, <samp class="codeph">&amp;gt;</samp>, <samp class="codeph">&amp;quot;</samp>,
and <samp class="codeph">&amp;apos;,</samp> for the greater than, double-quotation
mark and single-quotation mark characters, respectively. For all other
character entities, use numeric entity combinations, such as <samp class="codeph">&amp;amp;#165;,</samp> for
the Yen mark (¥).</p>
</li>
<li>
<p>In ActionScript, but not in an <samp class="codeph">&lt;mx:htmlText&gt;</samp> tag
or inline <samp class="codeph">htmlText</samp> 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 <samp class="codeph">&amp;lt;br&amp;gt;</samp> tag
or <samp class="codeph">&amp;amp;#013;</samp> entity.</p>
</li>
</ul>
</dd>
</dl>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache"><!-- --></a>
<h3 class="topictitle3">Using tags in HTML text</h3>
<div>
<p>
When
you use the <samp class="codeph">htmlText</samp> property, you use a subset
of HTML that is supported by Flash Player and AIR, which support
the following tags: </p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d36_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d36_verapache"><!-- --></a><h4 class="sectiontitle">Anchor
tag (&lt;a&gt;)</h4>
<p>
The
anchor <samp class="codeph">&lt;a&gt;</samp> tag creates a hyperlink and supports
the following attributes:</p>
<dl>
<dt class="dlterm">href </dt>
<dd>
<p>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.</p>
</dd>
<dt class="dlterm">target </dt>
<dd>
<p>Specifies the name of the target window to load the page
into.</p>
<p>For example, the following HTML snippet creates the
link “Go Home” to the Adobe Web site.</p>
<pre class="codeblock"> &lt;a href='http://www.adobe.com' target='_blank'&gt;Go Home&lt;/a&gt;</pre>
<p>The <samp class="codeph">&lt;a&gt;</samp> tag
does <em>not</em> make the link text blue or underline the text. You
must apply formatting tags to change the text format. You can do
this with the <samp class="codeph">&lt;font color="</samp>
<samp class="codeph">
<em>color</em>
</samp>
<samp class="codeph">"&gt;</samp> tag
and the <samp class="codeph">&lt;u&gt;</samp> tag.</p>
<p>You can also define <samp class="codeph">a:link</samp>, <samp class="codeph">a:hover</samp>,
and <samp class="codeph">a:active</samp> styles for anchor tags by using the
StyleSheet class, if the component supports the <samp class="codeph">styleSheet</samp> property.
This property is defined on MX TextArea and TextField controls.
The following example shows how to use it on text inside an MX TextArea
control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/StyleSheetExample.mxml --&gt;
&lt;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"
creationComplete="initApp()"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flash.text.StyleSheet;
private function initApp():void {
var ss:StyleSheet = new StyleSheet;
// Define an object for the "hover" state of the "a" tag.
var hoverStyles:Object = new Object;
hoverStyles.textDecoration = "underline";
hoverStyles.color = "#FF00CC";
// Define an object for the non-hover state of the "a" tag.
var linkStyles:Object = new Object;
linkStyles.color = "#FF00CC";
// Apply the newly defined styles.
ss.setStyle("a:hover", hoverStyles);
ss.setStyle("a", linkStyles);
// Apply the StyleSheet to the TextArea control.
myTA.styleSheet = ss;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Style&gt;
@namespace mx "library://ns.adobe.com/flex/mx";
mx|TextArea {
fontFamily:Courier;
linkcolor:#CC3300;
}
&lt;/fx:Style&gt;
&lt;mx:TextArea id="myTA" height="100" width="200"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[&lt;a href="http://www.adobe.com"&gt;This&lt;/a&gt; is a link.]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:TextArea&gt;
&lt;/s:Application&gt;</pre>
<p>The MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Label.html" target="_blank">Label</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Text.html" target="_blank">Text</a>, and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a> controls
can dispatch a <samp class="codeph">link</samp> event when the user selects
a hyperlink in the <samp class="codeph">htmlText</samp> property. To generate
the <samp class="codeph">link</samp> event, prefix the hyperlink destination
with <samp class="codeph">event:</samp>, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/LabelControlLinkEvent.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![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')
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:Label selectable="true" link="linkHandler(event);"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[This link lets you &lt;a href='event:http://www.adobe.com'&gt;Navigate to Adobe.com.&lt;/a&gt;]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Label&gt;
&lt;mx:TextArea id="myTA"/&gt;
&lt;/s:Application&gt;</pre>
<p>The MX Label control must have
the <samp class="codeph">selectable</samp> property set to <samp class="codeph">true</samp> to generate
the <samp class="codeph">link</samp> event.</p>
<p>When you use the <samp class="codeph">link</samp> event,
the event is generated and the text following <samp class="codeph">event:</samp> in
the hyperlink destination is included in the <samp class="codeph">text</samp> 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. </p>
</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d35_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d35_verapache"><!-- --></a><h4 class="sectiontitle">Bold
tag (&lt;b&gt;)</h4>
<p>The bold <samp class="codeph">&lt;b&gt;</samp> 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.</p>
<p>The following snippet applies
boldface to the word <em>bold</em>:</p>
<pre class="codeblock"> This word is &lt;b&gt;bold&lt;/b&gt;.</pre>
<p>You
cannot use the <samp class="codeph">&lt;/b&gt;</samp> end tag to override bold
formatting that you set for all text in a control by using the <samp class="codeph">fontWeight</samp> style.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d34_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d34_verapache"><!-- --></a><h4 class="sectiontitle">Break
tag (&lt;br&gt;)</h4>
<p>The break <samp class="codeph">&lt;br&gt;</samp> tag
creates a line break in the text. This tag has no effect in MX Label
or MX TextInput controls.</p>
<p>The following snippet starts a new
line after the word <em>line</em>:</p>
<pre class="codeblock"> The next sentence is on a new line.&lt;br&gt;Hello there.</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d33_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d33_verapache"><!-- --></a><h4 class="sectiontitle">Font
tag (&lt;font&gt;)</h4>
<p>
The <samp class="codeph">&lt;font&gt;</samp> tag
specifies the following font characteristics: color, face, and size. </p>
<p>The
font tag supports the following attributes:</p>
<dl>
<dt class="dlterm">color </dt>
<dd>
<p>Specifies the text color. You must use hexadecimal (<samp class="codeph">#FFFFFF</samp>)
color values. Other formats are not supported.</p>
</dd>
<dt class="dlterm">face </dt>
<dd>
<p>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.</p>
</dd>
<dt class="dlterm">size </dt>
<dd>
<p>Specifies the size of the font in points. You can also use
relative sizes (for example, +2 or -4).</p>
<p>The following example
shows the use of the <samp class="codeph">&lt;font&gt;</samp>
<samp class="codeph">tag:</samp>
</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/FontTag.mxml --&gt;
&lt;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"&gt;
&lt;mx:TextArea height="100" width="250"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[
You can vary the &lt;font size='20'&gt;font size&lt;/font&gt;,&lt;br&gt;&lt;font color="#0000FF"&gt;color&lt;/font&gt;,&lt;br&gt;&lt;font face="CourierNew, Courier, Typewriter"&gt;face&lt;/font&gt;, or&lt;br&gt;&lt;font size="18" color="#FF00FF"face="Times, Times New Roman, _serif"&gt;any combination of the three.&lt;/font&gt;
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:TextArea&gt;
&lt;/s:Application&gt;</pre>
</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d32_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d32_verapache"><!-- --></a><h4 class="sectiontitle">Image
tag (&lt;img&gt;)</h4>
<div class="note"><span class="notetitle">Note:</span> The <samp class="codeph">&lt;img&gt;</samp> tag
is not fully supported, and might not work in some cases. </div>
<p>
The image <samp class="codeph">&lt;img&gt;</samp> 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. </p>
<p>By default, Flash displays
media embedded in a text field at full size. To specify dimensions
for embedded media, use the <samp class="codeph">&lt;img&gt;</samp> tag’s <samp class="codeph">height</samp> and <samp class="codeph">width</samp> attributes. </p>
<p>In
general, an image embedded in a text field appears on the line following
the <samp class="codeph">&lt;img&gt;</samp> tag. However, when the <samp class="codeph">&lt;img&gt;</samp> tag
is the first character in the text field, the image appears on the
first line of the text field.</p>
<p>The <samp class="codeph">&lt;img&gt;</samp> tag
has one required attribute, <samp class="codeph">src</samp>, which specifies
the path to an image file. All other attributes are optional.</p>
<p>The <samp class="codeph">&lt;img&gt;</samp> tag
supports the following attributes:</p>
<dl>
<dt class="dlterm">src</dt>
<dd>
<p>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.</p>
</dd>
<dt class="dlterm">align</dt>
<dd>
<p>Specifies the horizontal alignment of the embedded image
within the text field. Valid values are <samp class="codeph">left</samp> and <samp class="codeph">right</samp>.
The default value is <samp class="codeph">left</samp>.</p>
</dd>
<dt class="dlterm">height</dt>
<dd>
<p>Specifies the height of the image, in pixels.</p>
</dd>
<dt class="dlterm">hspace</dt>
<dd>
<p>Specifies the amount of horizontal space that surrounds the
image where no text appears. The default value is 8.</p>
</dd>
<dt class="dlterm">id</dt>
<dd>
<p>Specifies the identifier for the imported image. This is
useful if you want to control the embedded content with ActionScript.</p>
</dd>
<dt class="dlterm">vspace</dt>
<dd>
<p>Specifies the amount of vertical space that surrounds the
image where no text.</p>
</dd>
<dt class="dlterm">width</dt>
<dd>
<p>Specifies the width of the image, in pixels. The default
value is 8.</p>
<p>The following example shows the use of the <samp class="codeph">&lt;img&gt;</samp> tag
and how text can flow around the image:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/ImgTag.mxml --&gt;
&lt;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"
width="300" height="300"&gt;
&lt;mx:Text height="100%" width="100%"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[
&lt;p&gt;You can include an image in your HTML text with the &amp;lt;img&amp;gt; tag.&lt;/p&gt;
&lt;p&gt;&lt;img src='assets/butterfly.gif' width='30' height='30' align='left' hspace='10' vspace='10'&gt;
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.&lt;/p&gt;
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fea_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fea_verapache"><!-- --></a><h4 class="sectiontitle">Making
hyperlinks out of embedded images</h4>
<p>To make a hyperlink
out of an embedded image, enclose the <samp class="codeph">&lt;img&gt;</samp> tag
in an <samp class="codeph">&lt;a&gt;</samp> tag, as the following example shows:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/ImgTagWithHyperlink.mxml --&gt;
&lt;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"&gt;
&lt;mx:TextArea width="100%" height="100%"&gt;
&lt;mx:htmlText&gt;
&lt;![CDATA[
&lt;a href='http://www.adobe.com'&gt;&lt;img src='assets/butterfly.gif'/&gt;&lt;/a&gt;
Click the image to go to the Adobe home page.
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:TextArea&gt;
&lt;/s:Application&gt;</pre>
<p>When the user moves the mouse
pointer over an image that is enclosed by <samp class="codeph">&lt;a&gt;</samp> tags,
the mouse pointer does not change automatically to a hand icon,
as with standard hyperlinks. To display a hand icon, specify <samp class="codeph">buttonMode="true"</samp> for the
MX TextArea (or Text) control. Interactivity, such as mouse clicks
and key presses, do not register in SWF files that are enclosed
by <samp class="codeph">&lt;a&gt;</samp> tags.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d31_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d31_verapache"><!-- --></a><h4 class="sectiontitle">Italic
tag (&lt;i&gt;)</h4>
<p>The italic <samp class="codeph">&lt;i&gt;</samp> 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.</p>
<p>The following
snippet applies italic font to the word <em>italic</em>:</p>
<pre class="codeblock"> The next word is in &lt;i&gt;italic&lt;/i&gt;.</pre>
<p>You
cannot use the <samp class="codeph">&lt;/i&gt;</samp> end tag to override italic
formatting that you set for all text in a control by using the <samp class="codeph">fontStyle</samp> style.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d30_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d30_verapache"><!-- --></a><h4 class="sectiontitle">List
item tag (&lt;li&gt;)</h4>
<p>
The
list item <samp class="codeph">&lt;li&gt;</samp> 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 <samp class="codeph">&lt;/li&gt;</samp> tag ensures a line break (but <samp class="codeph">&lt;/li&gt;&lt;li&gt;</samp> generates
a single line break). Unlike in HTML, you do not surround <samp class="codeph">&lt;li&gt;</samp> tags
in <samp class="codeph">&lt;ul&gt;</samp> tags. For example, the following
Flex code generates a bulleted list with two items:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/BulletedListExample.mxml --&gt;
&lt;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"&gt;
&lt;mx:Text&gt;
&lt;mx:htmlText &gt;
&lt;![CDATA[
&lt;p&gt;This is a bulleted list:&lt;li&gt;First Item&lt;/li&gt;&lt;li&gt;Second Item&lt;/li&gt;&lt;/p&gt;
]]&gt;
&lt;/mx:htmlText&gt;
&lt;/mx:Text&gt;
&lt;/s:Application&gt;</pre>
<div class="note"><span class="notetitle">Note:</span> The <samp class="codeph">&lt;li&gt;</samp> tag
does not work properly with MX Label controls. With MX TextInput
controls, it must be put before the first character in the text. </div>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2f_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2f_verapache"><!-- --></a><h4 class="sectiontitle">Paragraph
tag (&lt;p&gt;)</h4>
<p>The paragraph <samp class="codeph">&lt;p&gt;</samp> tag
creates a new paragraph. The opening <samp class="codeph">&lt;p&gt;</samp> tag
does <em>not</em> force a line break, but the closing <samp class="codeph">&lt;/p&gt;</samp> tag
does. Unlike in HTML, the <samp class="codeph">&lt;p&gt;</samp> tag does not
force a double space between paragraphs; the spacing is the same
as that generated by the <samp class="codeph">&lt;br&gt;</samp> tag. </p>
<p>
The <samp class="codeph">&lt;p&gt;</samp> tag
supports the following attribute: </p>
<dl>
<dt class="dlterm">align</dt>
<dd>
<p>Specifies alignment of text in the paragraph; valid values
are <samp class="codeph">left</samp>, <samp class="codeph">right</samp>, <samp class="codeph">center</samp>,
and <samp class="codeph">justify</samp>.</p>
<p>The following snippet generates
two centered paragraphs:</p>
<pre class="codeblock"> &lt;p align="center"&gt;This is a first centered paragraph&lt;/p&gt;
 &lt;p align="center"&gt;This is a second centered paragraph&lt;/p&gt;</pre>
</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2e_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2e_verapache"><!-- --></a><h4 class="sectiontitle">Text
format tag (&lt;textformat&gt;)</h4>
<p>
The text format <samp class="codeph">&lt;textformat&gt;</samp> 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:</p>
<dl>
<dt class="dlterm">blockindent</dt>
<dd>
<p>Specifies the indentation, in points, from the left margin
to the text in the <samp class="codeph">&lt;textformat&gt;</samp> tag body.</p>
</dd>
<dt class="dlterm">indent</dt>
<dd>
<p>Specifies the indentation, in points, from the left margin
or the block indent, if any, to the first character in the <samp class="codeph">&lt;textformat&gt;</samp> tag
body.</p>
</dd>
<dt class="dlterm">leading</dt>
<dd>
<p>Specifies the amount of leading (vertical space) between
lines.</p>
</dd>
<dt class="dlterm">leftmargin</dt>
<dd>
<p>Specifies the left margin of the paragraph, in points.</p>
</dd>
<dt class="dlterm">rightmargin</dt>
<dd>
<p>Specifies the right margin of the paragraph, in points.</p>
</dd>
<dt class="dlterm">tabstops</dt>
<dd>
<p>Specifies custom tab stops as an array of nonnegative integers.</p>
</dd>
</dl>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2d_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d48_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d2d_verapache"><!-- --></a><h4 class="sectiontitle">Underline
tag (&lt;u&gt;)</h4>
<p>
The
underline <samp class="codeph">&lt;u&gt;</samp> tag underlines the tagged text. </p>
<p>The
following snippet underlines the word <em>underlined</em>:</p>
<pre class="codeblock"> The next word is &lt;u&gt;underlined&lt;/u&gt;.</pre>
<p>You
cannot use the <samp class="codeph">&lt;/u&gt;</samp> end tag to override underlining
that you set for all text in a control by using the <samp class="codeph">textDecoration</samp> style.</p>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d44_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d44_verapache"><!-- --></a>
<h2 class="topictitle2">Selecting and modifying text</h2>
<div>
<p>
You
can select and modify text in the MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a>,
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextInput.html" target="_blank">TextInput</a>,
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/RichTextEditor.html" target="_blank">RichTextEditor</a> controls.
To change a MX Label or Text control’s text, assign a new value
to the control’s <samp class="codeph">text</samp> or <samp class="codeph">HTMLtext</samp> property.
For more information on the <samp class="codeph">HTMLText</samp> property,
see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache"><!-- --></a>
<h3 class="topictitle3">Selecting text</h3>
<div>
<p>The Flex editable controls provide properties and methods
to select text regions and get selections. You can modify the contents
of the selection as described in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache">Modifying
text </a>.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d28_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d28_verapache"><!-- --></a><h4 class="sectiontitle">Creating
a selection</h4>
<p>The MX TextInput and TextArea controls, including
the RichTextEditor control’s TextArea subcontrol, provide the following
text selection properties and method:</p>
<ul>
<li>
<p>
<samp class="codeph">setSelection()</samp> method
selects a range of text. You specify the zero-based indexes of the
start character and the position immediately <em>after</em> the last character
in the text.</p>
</li>
<li>
<p>
<samp class="codeph">selectionBeginIndex</samp> and <samp class="codeph">selectionEndIndex</samp> set
or return the zero-based location in the text of the start and position
immediately <em>after</em> the end of a selection. </p>
</li>
</ul>
<p>To
select the first 10 characters of the myTextArea TextArea control,
for example, use the following method:</p>
<pre class="codeblock"> myTextArea.setSelection(0, 10);</pre>
<p>To
change the last character of this selection to be the twenty-fifth
character in the MX TextArea control, use the following statement:</p>
<pre class="codeblock"> myTextArea.endIndex=25;</pre>
<p>To
select text in a RichTextEditor control, use the control’s TextArea
subcontrol, which you access by using the <samp class="codeph">textArea</samp> id.
To select the first 10 characters in the myRTE RichTextEditor control,
for example, use the following code:</p>
<pre class="codeblock"> myRTE.textArea.setSelection(0, 10);</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d29_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf69084-7d29_verapache"><!-- --></a><h4 class="sectiontitle">Getting
a selection</h4>
<p>You get a text control’s selection by getting
a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/textClasses/TextRange.html" target="_blank">TextRange</a> object
with the selected text. You can then use the TextRange object to
modify the selected text, as described in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache">Modifying
text </a>. The technique you use to get the selection depends on
the control type.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd3_verapache"><!-- --></a><h4 class="sectiontitle">Get
the selection in an MX TextArea or MX TextInput control</h4>
<p>Use
the TextRange class constructor to get a TextRange object with the
currently selected text in an MX TextArea or MX TextInput control.
For example, to get the current selection of the myTextArea control,
use the following line:</p>
<pre class="codeblock"> var mySelectedTextRange:TextRange = new TextRange(myTextArea, true);</pre>
<p>The
second parameter, <samp class="codeph">true</samp>, tells the constructor to
return a TextRange object with the selected text.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd2_verapache"><!-- --></a><h4 class="sectiontitle">Get
the selection in a RichTextEditor control</h4>
<p>Use the <samp class="codeph">selection</samp> read-only
property of the RichTextEditor to get a TextRange object with the
currently selected text in its MX TextArea subcontrol. You can use the
TextRange object to modify the selected text, as described in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache">Modifying text </a>. For example, to get
the current selection of the MyRTE RichTextEditor control, us the
following line:</p>
<pre class="codeblock"> public var mySelectedTextRange:TextRange = myRTE.selection;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache"><!-- --></a>
<h3 class="topictitle3">Modifying text </h3>
<div>
<p>You use the TextRange class to modify the text in an MX
TextArea, MX TextInput, or RichTextEditor control. This class lets
you affect the following text characteristics:</p>
<ul>
<li>
<p>
<samp class="codeph">text</samp> or <samp class="codeph">htmltext</samp> property
contents</p>
</li>
<li>
<p>text color, decoration (underlining), and alignment</p>
</li>
<li>
<p>font family, size, style (italics), and weight (bold)</p>
</li>
<li>
<p>URL of an HTML &lt;a&gt; link</p>
</li>
</ul>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd7_verapache"><!-- --></a><h4 class="sectiontitle">Getting
a TextRange object</h4>
<p>To get a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/textClasses/TextRange.html" target="_blank">TextRange</a> object
you use the following techniques:</p>
<ul>
<li>
<p>Get a TextRange
object that contains the current text selection.</p>
</li>
<li>
<p>Create a TextRange object that contains a specific range
of text.</p>
</li>
</ul>
<p>To create a TextRange object with a specific
range of text, use a TextRange constructor with the following format:</p>
<pre class="codeblock"> new TextRange(control, modifiesSelection, beginIndex, endIndex)</pre>
<p>Specify
the control that contains the text, whether the TextRange object
corresponds to a selection (that is, represents and modifies selected
text), and the zero-based indexes in the text of the first and last
character of the range. As a general rule, do not use the TextRange
constructor to set a selection; use the <samp class="codeph">setSelection()</samp> method,
as described in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffb_verapache">Selecting
text</a>. For this reason, the second parameter should always
be <samp class="codeph">false</samp> when you specify the begin and end indexes.</p>
<p>To
get a TextRange object with the fifth through twenty-fifth characters
of an MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a> control
named myTextArea, for example, use the following line:</p>
<pre class="codeblock"> var myTARange:TextRange = new TextRange(myTextArea, false, 4, 25);</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d2c_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffd_verapache"><!-- --></a><h4 class="sectiontitle">Changing
text</h4>
<p>After you get a TextRange object, use its properties
to modify the text in the range. The changes you make to the TextRange
appear in the text control.</p>
<p>You can get or set the text in
a TextRange object as HTML text or as a plain text, independent
of any property that you might have used to initially set the text.
If you created an MX TextArea control, for example, and set its <samp class="codeph">text</samp> property,
you can use the TextRange <samp class="codeph">htmlText</samp> property to
get and change the text. The following example shows this usage,
and shows using the TextRange class to access a range of text and
change its properties. It also shows using String properties and
methods to get text indexes.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextRangeExample.mxml --&gt;
&lt;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"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;&lt;![CDATA[
import mx.controls.textClasses.TextRange
private function resetText():void {
ta1.text = "This is a test of the emergency broadcast system. It is only a test.";
}
public function alterText():void {
// Create a TextRange object starting with "the" and ending at the
// first period. Replace it with new formatted HTML text.
var tr1:TextRange = new TextRange(
ta1, false, ta1.text.indexOf("the", 0), ta1.text.indexOf(".", 0)
);
tr1.htmlText="&lt;i&gt;italic HTML text&lt;/i&gt;"
// Create a TextRange object with the remaining text.
// Select the text and change its formatting.
var tr2:TextRange = new TextRange(
ta1, true, ta1.text.indexOf("It", 0), ta1.text.length-1
);
tr2.color=0xFF00FF;
tr2.fontSize=18;
tr2.fontStyle = "italic"; // any other value turns italic off
tr2.fontWeight = "bold"; // any other value turns bold off
ta1.setSelection(0, 0);
}
]]&gt;&lt;/fx:Script&gt;
&lt;mx:TextArea id="ta1" fontSize="12" fontWeight="bold" width="100%" height="100"&gt;
&lt;mx:text&gt;
This is a test of the emergency broadcast system. It is only a test.
&lt;/mx:text&gt;
&lt;/mx:TextArea&gt;
&lt;s:HGroup&gt;
&lt;mx:Button label="Alter Text" click="alterText();"/&gt;
&lt;mx:Button label="Reset" click="resetText();"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fdc_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fdc_verapache"><!-- --></a>
<h3 class="topictitle3">Example: Changing selected text
in a RichTextEditor control</h3>
<div>
<p>The following example shows how you can use the <samp class="codeph">selectedText</samp> property
of the<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/RichTextEditor.html" target="_blank">RichTextEditor</a> control
to get a TextRange when a user selects some text, and use <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/textClasses/TextRange.html" target="_blank">TextRange</a> properties
to get and change the characteristics of the selected text. To use
the example, select a range of text with your mouse. When you release
the mouse button, the string “This is replacement text. ”, formatted
in fuchsia Courier 20-point font replaces the selection and the
text area reports on the original and replacement text.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextRangeSelectedText.mxml --&gt;
&lt;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"
width="600" height="500"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;&lt;![CDATA[
import mx.controls.textClasses.TextRange;
//The following text must be on a single line.
[Bindable]
public var htmlData:String="&lt;textformat leading='2'&gt;&lt;p align='center'&gt;&lt;b&gt;&lt;font size='20'&gt;HTML Formatted Text&lt;/font&gt;&lt;/b&gt;&lt;/p&gt;&lt;/textformat&gt;&lt;br&gt;&lt;textformat leading='2'&gt;&lt;p align='left'&gt;&lt;font face='_sans' size='12' color='#000000'&gt;This paragraph contains &lt;b&gt;bold&lt;/b&gt;, &lt;i&gt;italic&lt;/i&gt;, &lt;u&gt;underlined&lt;/u&gt;, and &lt;b&gt;&lt;i&gt;&lt;u&gt;bold italic underlined &lt;/u&gt;&lt;/i&gt;&lt;/b&gt;text. &lt;/font&gt;&lt;/p&gt;&lt;/textformat&gt;&lt;br&gt;&lt;p&gt;&lt;u&gt;&lt;font face='arial' size='14' color='#ff0000'&gt;This a red underlined 14-point arial font with no alignment set.&lt;/font&gt;&lt;/u&gt;&lt;/p&gt;&lt;p align='right'&gt;&lt;font face='verdana' size='12' color='#006666'&gt;&lt;b&gt;This a teal bold 12-pt. Verdana font with alignment set to right.&lt;/b&gt;&lt;/font&gt;&lt;/p&gt;";
public function changeSelectionText():void {
//Get a TextRange with the selected text and find its length.
var sel:TextRange = rte1.selection;
var selLength:int = sel.endIndex - sel.beginIndex;
//Do the following only if the user made a selection.
if (selLength) {
//Display the selection size and font color, size, and family.
t1.text="Number of characters selected: " + String(selLength);
t1.text+="\n\nOriginal Font Family: " + sel.fontFamily;
t1.text+="\nOriginal Font Size: " + sel.fontSize;
t1.text+="\nOriginal Font Color: " + sel.color;
//Change font color, size, and family and replace selected text.
sel.text="This is replacement text. "
sel.color="fuchsia";
sel.fontSize=20;
sel.fontFamily="courier"
//Show the new font color, size, and family.
t1.text+="\n\nNew text length: " + String(sel.endIndex - sel.beginIndex);
t1.text+="\nNew Font Family: " + sel.fontFamily;
t1.text+="\nNew Font Size: " + sel.fontSize;
t1.text+="\nNew Font Color: " + sel.color;
}
}
]]&gt;&lt;/fx:Script&gt;
&lt;!-- The text area. When you release the mouse after selecting text,
it calls the func1 function. --&gt;
&lt;mx:RichTextEditor id="rte1"
htmlText="{htmlData}"
width="100%" height="100%"
mouseUp="changeSelectionText()"/&gt;
&lt;mx:TextArea id="t1"
editable="false"
fontSize="12"
fontWeight="bold"
width="300" height="180"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d4e_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d4e_verapache"><!-- --></a>
<h2 class="topictitle2">MX Label control</h2>
<div>
<p>The Label control is part of both the MX and Spark component
sets. While you can use the MX controls in your application, it’s
best to use the Spark controls instead. For more information about
using Spark text controls, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache">Spark
text controls</a>.</p>
<p>The MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Label.html" target="_blank">Label</a> control
is a noneditable single-line text label. It has the following characteristics:</p>
<ul>
<li>
<p>The user cannot change the text, but the application
can modify it. </p>
</li>
<li>
<p>You can specify text formatting by using styles or HTML text. </p>
</li>
<li>
<p>You can control the alignment and sizing. </p>
</li>
<li>
<p>The control is transparent and does not have a <samp class="codeph">backgroundColor</samp> property, so
the background of the component’s container shows through.</p>
</li>
<li>
<p>The control has no borders, so the label appears as text
written directly on its background.</p>
</li>
<li>
<p>The control cannot take the focus.</p>
</li>
</ul>
<p>
To
create a multiline, noneditable text field, use a Text control.
For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d55_verapache">MX
Text control</a>. To create user-editable text fields, use MX
TextInput or MX TextArea controls. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache">MX
TextInput control</a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache">MX TextArea
control</a>. </p>
<p>The following image shows an MX Label control:</p>
<div class="figborder">
<img src="images/tc_label_example.png" alt="Label control"/>
</div>
<p>For the code used to create this sample, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d54_verapache">Creating an MX Label control</a>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d54_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d54_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX Label control</h3>
<div>
<p>
You
define an MX Label control in MXML by using the <samp class="codeph">&lt;mx:Label&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/LabelControl.mxml --&gt;
&lt;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"
width="150" height="80"&gt;
&lt;mx:Label text="Label1"/&gt;
&lt;/s:Application&gt;</pre>
<p>You use the <samp class="codeph">text</samp> property to specify a string
of raw text, and the <samp class="codeph">htmlText</samp> property to specify
an HTML‑formatted string. For more information on using these properties,
see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using
the text property </a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff7_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff7_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing an MX Label control</h3>
<div>
<p>If you do not specify a width, the MX Label control automatically
resizes when you change the value of the <samp class="codeph">text</samp> or <samp class="codeph">htmlText</samp> property.</p>
<p>If you explicitly size an MX Label control so that it is not
large enough to accommodate its text, the text is truncated and
terminated by an ellipsis (...). The full text displays as a tooltip
when you move the mouse over the MX Label control. If you also set
a tooltip by using the <samp class="codeph">tooltip</samp> property, the tooltip
is displayed rather than the text.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache"><!-- --></a>
<h2 class="topictitle2">MX TextInput control</h2>
<div>
<p>The TextInput control is part of both the MX and Spark
component sets. While you can use the MX controls in your application,
it’s best to use the Spark controls instead. For more information
about using Spark text controls, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache">Spark
text controls</a>.</p>
<p>
The MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextInput.html" target="_blank">TextInput</a> control
is a single-line text field that is optionally editable. The MX
TextInput control supports the HTML rendering capabilities of Adobe
Flash Player.</p>
<p>The following image shows an MX TextInput control:</p>
<div class="figborder">
<img src="images/tc_textinput_example.png" alt="TextInput control"/>
</div>
<p>To create a multiline, editable text field, use an MX TextArea
control. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache">MX
TextArea control</a>. To create noneditable text fields, use
MX Label and Text controls. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d4e_verapache">MX
Label control</a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d55_verapache">MX
Text control</a>.</p>
<p>The MX TextInput control does not include a label, but you can
add one by using an MX Label control or by nesting the MX TextInput
control in a FormItem container in a Form layout container, as shown
in the example in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d3f_verapache">About
MX text controls</a>. MX TextInput controls dispatch <samp class="codeph">change</samp>, <samp class="codeph">textInput</samp>,
and <samp class="codeph">enter</samp> events.</p>
<p>If you disable an MX TextInput control, it displays its contents
in a different color, represented by the <samp class="codeph">disabledColor</samp> style.
You can set an MX TextInput control’s <samp class="codeph">editable</samp> property
to <samp class="codeph">false</samp> to prevent editing of the text. You can set
an MX TextInput control’s <samp class="codeph">displayAsPassword</samp> property
to conceal the input text by displaying characters as asterisks.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff3_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX TextInput control</h3>
<div>
<p>
You
define an MX TextInput control in MXML by using the <samp class="codeph">&lt;mx:TextInput&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a control elsewhere in your MXML, either
in another tag or in an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextInputControl.mxml --&gt;
&lt;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"&gt;
&lt;mx:TextInput id="text1" width="100"/&gt;
&lt;/s:Application&gt;</pre>
<p>Just as you can for the MX Label control, you use the <samp class="codeph">text</samp> property
to specify a string of raw text, and the <samp class="codeph">htmlText</samp> property
to specify an HTML-formatted string. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using
the text property </a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff4_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7ff4_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing an MX TextInput control</h3>
<div>
<p>If you do not specify a width, the MX TextInput control
automatically resizes when you change the value of the <samp class="codeph">text</samp> or <samp class="codeph">htmlText</samp> property.
It does not resize in response to typed user input.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe9_verapache"><!-- --></a>
<h3 class="topictitle3">Binding to an MX TextInput control</h3>
<div>
<p>
In
some cases, you might want to bind a variable to the text property
of an MX TextInput control so that the control represents a variable
value, as the following example shows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/BoundTextInputControl.mxml --&gt;
&lt;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"&gt;
&lt;fx:Script&gt;&lt;![CDATA[
[Bindable]
public var myProp:String="This is the initial String myProp.";
]]&gt;&lt;/fx:Script&gt;
&lt;mx:TextInput text="{myProp}" width="250"/&gt;
&lt;/s:Application&gt;</pre>
<p>In this example, the MX TextInput control displays the value
of the myProp variable. Remember that you must use the <samp class="codeph">[Bindable]</samp> metadata
tag if the variable changes value and the control must track the
changed values; also, the compiler generates warnings if you do
not use this metadata tag.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d55_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d55_verapache"><!-- --></a>
<h2 class="topictitle2">MX Text control</h2>
<div>
<p>The MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Text.html" target="_blank">Text</a> control
displays multiline, noneditable text. The control has the following
characteristics:</p>
<ul>
<li>
<p>The user cannot change the text, but the application
can modify it. </p>
</li>
<li>
<p>The control does not support scroll bars. If the text exceeds
the control size, users can use keys to scroll the text. </p>
</li>
<li>
<p>The control is transparent so that the background of the
component’s container shows through.</p>
</li>
<li>
<p>The control has no borders, so the label appears as text
written directly on its background.</p>
</li>
<li>
<p>The control supports HTML text and a variety of text and
font styles. </p>
</li>
<li>
<p>
The
text always word-wraps at the control boundaries, and is always
aligned to the top of the control. </p>
</li>
</ul>
<p>To create a single-line, noneditable text field, use the MX Label
control. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d4e_verapache">MX
Label control</a>. To create user-editable text fields, use the
MX TextInput or TextArea controls. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache">MX
TextInput control</a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache">MX
TextArea control</a>. </p>
<p>The following image shows an example of a Text control with a
width of 175 pixels: </p>
<div class="figborder">
<img src="images/tc_text.png" alt="Text control with a with of 175 pixels"/>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe3_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe3_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Text control</h3>
<div>
<p>
You
define a Text control in MXML by using the <samp class="codeph">&lt;mx:Text&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a component elsewhere in your MXML, either
in another tag or in an ActionScript block.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextControl.mxml --&gt;
&lt;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"&gt;
&lt;mx:Text width="175"
text="This is an example of a multiline text string in a Text control."/&gt;
&lt;/s:Application&gt;</pre>
<p>You use the <samp class="codeph">text</samp> property to specify a string
of raw text, and the <samp class="codeph">htmlText</samp> property to specify
an HTML-formatted string. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using the
text property </a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>.</p>
<p>This control does not support a <samp class="codeph">backgroundColor</samp> property;
its background is always the background of the control’s container.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe2_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fe2_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a Text control</h3>
<div>
<p>Flex sizes the Text control as follows:</p>
<ul>
<li>
<p>If you specify a pixel value for both the <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties,
any text that exceeds the size of the control is clipped at the
border.</p>
</li>
<li>
<p>If you specify an explicit pixel width, but no height, Flex
wraps the text to fit the width and calculates the height to fit
the required number of lines. </p>
</li>
<li>
<p>If you specify a percentage-based width and no height, Flex
does <em>not</em> wrap the text, and the height equals the number
of lines as determined by the number of Return characters.</p>
</li>
<li>
<p>If you specify only a height and no width, the height value
does not affect the width calculation, and Flex sizes the control
to fit the width of the maximum line.</p>
</li>
</ul>
<p>As a general rule, if you have long text, you should specify
a pixel-based <samp class="codeph">width</samp> property. If the text might
change and you want to ensure that the Text control always takes
up the same space in your application, set explicit <samp class="codeph">height</samp> and <samp class="codeph">width</samp> properties
that fit the largest expected text.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache"><!-- --></a>
<h2 class="topictitle2">MX TextArea control</h2>
<div>
<p>The TextArea control is part of both the MX and Spark component
sets. While you can use the MX controls in your application, it’s
best to use the Spark controls instead. For more information about
using Spark text controls, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache">Spark
text controls</a>.</p>
<p>
The
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a> control
is a multiline, editable text field with a border and optional scroll
bars. The MX TextArea control supports the HTML and rich text rendering
capabilities of Flash Player and AIR. The MX TextArea control dispatches <samp class="codeph">change</samp> and <samp class="codeph">textInput</samp> events. </p>
<p>The following image shows an MX TextArea control:</p>
<div class="figborder">
<img src="images/tc_textarea_example.png" alt="TextArea control "/>
</div>
<p>To create a single-line, editable text field, use the MX TextInput
control. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d85_verapache">MX
TextInput control</a>. To create noneditable text fields, use
the MX Label and Text controls. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d4e_verapache">MX
Label control</a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d55_verapache">MX Text
control</a>. </p>
<p>If you disable an MX TextArea control, it displays its contents
in a different color, represented by the <samp class="codeph">disabledColor</samp> style.
You can set an MX TextArea control’s <samp class="codeph">editable</samp> property
to <samp class="codeph">false</samp> to prevent editing of the text. You can
set an MX TextArea control’s <samp class="codeph">displayAsPassword</samp> property
to conceal input text by displaying characters as asterisks.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fec_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fec_verapache"><!-- --></a>
<h3 class="topictitle3">Creating an MX TextArea control</h3>
<div>
<p>
You
define an MX TextArea control in MXML by using the <samp class="codeph">&lt;mx:TextArea&gt;</samp> tag, as
the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a control elsewhere in your MXML, either
in another tag or in an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/TextAreaControl.mxml --&gt;
&lt;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"&gt;
&lt;mx:TextArea id="textConfirm"
width="300" height="100"
text="Please enter your thoughts here."/&gt;
&lt;/s:Application&gt;</pre>
<p>Just as you can for the Text control, you use the <samp class="codeph">text</samp> property
to specify a string of raw text, and the <samp class="codeph">htmlText</samp> property
to specify an HTML-formatted string. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using
the text property </a> and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>. </p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fed_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fed_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing the MX TextArea control</h3>
<div>
<p>The MX TextArea control does not resize to fit the text
that it contains. If the new text exceeds the capacity of the MX
TextArea control and the <samp class="codeph">horizontalScrollPolicy</samp> is <samp class="codeph">true</samp> (the
default value), the control adds a scrollbar.</p>
</div>
</div>
</div>
<div class="nested1" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d89_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d89_verapache"><!-- --></a>
<h2 class="topictitle2">MX RichTextEditor control</h2>
<div>
<p>
The
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/RichTextEditor.html" target="_blank">RichTextEditor </a>control
lets users enter, edit, and format text. Users apply text formatting
and URL links by using subcontrols that are located at the bottom of
the RichTextEditor control. </p>
<p>There is no Spark equivalent of the RichTextEditor control. </p>
<p>For complete reference information, see the <em>Adobe Flex Language Reference</em>.</p>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d42_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d42_verapache"><!-- --></a>
<h3 class="topictitle3">About the RichTextEditor control</h3>
<div>
<p>
The
RichTextEditor control consists of a Panel control with two direct
children:</p>
<ul>
<li>
<p>An MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a> control
in which users can enter text</p>
</li>
<li>
<p>A tool bar container with format controls that let a user
specify the text characteristics. Users can use the tool bar subcontrols
to apply the following text characteristics:</p>
<ul>
<li>
<p>Font
family</p>
</li>
<li>
<p>Font size</p>
<div class="note"><span class="notetitle">Note:</span> When using the RichTextEditor
control, you specify the actual pixel value for the font size. This
size is not equivalent to the relative font sizes specified in HTML
by using the <samp class="codeph">size</samp> attribute of the HTML <samp class="codeph">&lt;font&gt;</samp>
<em> tag.</em>
</div>
</li>
<li>
<p>Any combination of bold, italic and underline font styles</p>
</li>
<li>
<p>Text color</p>
</li>
<li>
<p>Text alignment: left, center, right, or justified</p>
</li>
<li>
<p>Bullets</p>
</li>
</ul>
</li>
<li>
<p>URL links</p>
</li>
</ul>
<p>The following image shows a RichTextEditor control with some
formatted text:</p>
<div class="figborder">
<img src="images/tc_RTE1.png" alt="RichTextEditor control with some formatted text"/>
</div>
<p>For the source for this example, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d3a_verapache">Creating
a RichTextEditor control</a>.</p>
<p>You use the RichTextEditor interactively as follows:</p>
<ul>
<li>
<p>Text that you type is formatted as specified by the control
settings. </p>
</li>
<li>
<p>To apply new formatting to existing text, select the text
and set the controls to the required format. </p>
</li>
<li>
<p>To create a link, select a range of text, enter the link
target in the text box on the right, and press Enter. You can only
specify the URL; the link always opens in a _blank target. Also,
creating the link does not change the appearance of the link text;
you must separately apply any color and underlining.</p>
</li>
<li>
<p>You can cut, copy, and paste rich text within and between
Flash HTML text fields, including the RichTextEditor control’s TextArea
subcontrol, by using the normal keyboard commands. You can copy
and paste plain text between the TextArea and any other text application,
such as your browser or a text editor.</p>
</li>
</ul>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf69084-7d3a_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf69084-7d3a_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a RichTextEditor control</h3>
<div>
<p>
You
define a RichTextEditor control in MXML by using the <samp class="codeph">&lt;mx:RichTextEditor&gt;</samp> tag,
as the following example shows. Specify an <samp class="codeph">id</samp> value
if you intend to refer to a control elsewhere in your MXML, either
in another tag or in an ActionScript block. </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/RichTextEditorControl.mxml --&gt;
&lt;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"&gt;
&lt;mx:RichTextEditor id="myRTE" text="Congratulations, winner!" /&gt;
&lt;/s:Application&gt;</pre>
<p>You can use the <samp class="codeph">text</samp> property to specify an
unformatted text string, or the <samp class="codeph">htmlText</samp> property
to specify an HTML-formatted string. For more information on using
these properties, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d53_verapache">Using
the text property </a>, and <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d52_verapache">Using
the htmlText property</a>. For information on selecting, replacing,
and formatting text that is in the control, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d44_verapache">Selecting
and modifying text</a>.</p>
<p>The following example shows the code used to create the image
in <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d42_verapache">About
the RichTextEditor control</a>:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/RichTextEditorControlWithFormattedText.mxml --&gt;
&lt;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"&gt;
&lt;!-- The HTML text string used to populate the RichTextEditor control's
TextArea subcomponent. The text is on a single line. --&gt;
&lt;fx:Script&gt;&lt;![CDATA[
[Bindable]
public var htmlData:String="&lt;textformat leading='2'&gt;&lt;p align='center'&gt;&lt;b&gt;&lt;font size='20'&gt;HTML Formatted Text&lt;/font&gt;&lt;/b&gt;&lt;/p&gt;&lt;/textformat&gt;&lt;br&gt;&lt;textformat leading='2'&gt;&lt;p align='left'&gt;&lt;font face='_sans' size='12' color='#000000'&gt;This paragraph contains&lt;b&gt;bold&lt;/b&gt;, &lt;i&gt;italic&lt;/i&gt;, &lt;u&gt;underlined&lt;/u&gt;, and &lt;b&gt;&lt;i&gt;&lt;u&gt;bold italic underlined &lt;/u&gt;&lt;/i&gt;&lt;/b&gt;text.&lt;/font&gt;&lt;/p&gt;&lt;/textformat&gt;&lt;br&gt;&lt;p&gt;&lt;u&gt;&lt;font face='arial' size='14' color='#ff0000'&gt;This a red underlined 14-point arial font with no alignment set.&lt;/font&gt;&lt;/u&gt;&lt;/p&gt;&lt;p align='right'&gt;&lt;font face='verdana' size='12' color='#006666'&gt;&lt;b&gt;This a teal bold 12-pt.' Verdana font with alignment set to right.&lt;/b&gt;&lt;/font&gt;&lt;/p&gt;&lt;br&gt;&lt;li&gt;This is bulleted text.&lt;/li&gt;&lt;li&gt;&lt;font face='arial' size='12' color='#0000ff'&gt;&lt;u&gt; &lt;a href='http://www.adobe.com'&gt;This is a bulleted link with underline and blue color set.&lt;/a&gt;&lt;/u&gt;&lt;/font&gt;&lt;/li&gt;";
]]&gt;&lt;/fx:Script&gt;
&lt;!-- The RichTextEditor control. To reference a subcomponent prefix its ID with the RichTextEditor control ID. --&gt;
&lt;mx:RichTextEditor id="rte1"
backgroundColor="#ccffcc"
width="500"
headerColors="[#88bb88, #bbeebb]"
footerColors="[#bbeebb, #88bb88]"
title="Rich Text Editor"
htmlText="{htmlData}"
initialize="rte1.textArea.setStyle('backgroundColor', '0xeeffee')"
/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fdd_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fdd_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing the RichTextEditor control</h3>
<div>
<p>The control does not resize in response to the size of
the text in the MX TextArea control. If the text exceeds the viewable
space, by default, the MX TextArea control adds scroll bars. If
you specify a value for either the <samp class="codeph">height</samp> or <samp class="codeph">width</samp> property
but not both, the control uses the default value for the property
that you do not set.</p>
<p>If you set a <samp class="codeph">width</samp> value that results in a width
less than 605 pixels wide, the RichTextEditor control stacks the
subcontrols in rows.</p>
</div>
</div>
<div class="nested2" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache"><!-- --></a>
<h3 class="topictitle3">Programming RichTextEditor subcontrols</h3>
<div>
<p>Your application can control the settings of any of the
RichTextEditor subcontrols, such as the MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/TextArea.html" target="_blank">TextArea</a>,
the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ColorPicker.html" target="_blank">ColorPicker</a>,
or any of the MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/ComboBox.html" target="_blank">ComboBox</a> or
MX <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/Button.html" target="_blank">Button</a> controls
that control text formatting. To refer to a RichTextEditor subcontrol,
prefix the requested control’s ID with the RichTextEditor control
ID. For example, to refer to the ColorPicker control in a RichTextEditor
control that has the ID rte1, use rte1.colorPicker.</p>
<p>Inheritable styles that you apply directly to a RichTextEditor
control affect the underlying Panel control and the subcontrols.
Properties that you apply directly to a RichTextEditor control affect
the underlying Panel control only.</p>
<p>For more information, see the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/controls/RichTextEditor.html" target="_blank">RichTextEditor</a> in
the <em>Adobe Flex Language Reference</em>.</p>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd8_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd8_verapache"><!-- --></a><h4 class="sectiontitle">Setting
RichTextEditor subcontrol properties and styles</h4>
<p>The following
simple code example shows how you can set and change the properties
and styles of the RichTextEditor control and its subcontrols. This example
uses styles that the RichTextEditor control inherits from the Panel
class to set the colors of the Panel control header and the tool
bar container, and sets the MX TextArea control’s background color
in the RichTextEditor control’s creationComplete event member. When
users click the buttons, their click event listeners change the
TextArea control’s background color and the selected color of the
ColorPicker control.</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/RTESubcontrol.mxml --&gt;
&lt;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="420"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;!-- The RichTextEditor control. To set the a subcomponent's style or property,
fully qualify the control ID. The footerColors style sets the ControlBar colors. --&gt;
&lt;mx:RichTextEditor id="rte1"
backgroundColor="#ccffcc"
headerColors="[#88bb88, #bbeebb]"
footerColors="[#bbeebb, #88bb88]"
title="Rich Text Editor"
creationComplete="rte1.textArea.setStyle('backgroundColor','0xeeffee')"
text="Simple sample text"/&gt;
&lt;!-- Button to set a white TextArea background. --&gt;
&lt;s:Button
label="Change appearance"
click="rte1.textArea.setStyle('backgroundColor', '0xffffff');rte1.colorPicker.selectedIndex=27;"/&gt;
&lt;!-- Button to reset the display to its original appearance. --&gt;
&lt;s:Button
label="Reset Appearance"
click="rte1.textArea.setStyle('backgroundColor', '0xeeffee');rte1.colorPicker.selectedIndex=0;"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd1_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd1_verapache"><!-- --></a><h4 class="sectiontitle">Removing
and adding RichTextEditor subcontrols</h4>
<p>You can remove any
of the standard RichTextEditor subcontrols, such as the alignment
buttons. You can also add your own subcontrols, such as a button
that pops up a find-and-replace dialog box.</p>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd0_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd0_verapache"><!-- --></a><h4 class="sectiontitle">Remove
an existing subcontrol</h4>
<ol>
<li>
<p>Create a function that
calls the <samp class="codeph">removeChildAt</samp> method of the editor’s
tool bar Container subcontrol, specifying the control to remove. </p>
</li>
<li>
<p>Call the method in the RichTextEditor control’s <samp class="codeph">initialize</samp> event
listener.</p>
</li>
</ol>
<p>The following example removes the alignment
buttons from a RichTextEditor control, and shows the default appearance
of a second RichTextEditor control:</p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/RTERemoveAlignButtons.mxml --&gt;
&lt;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="700"&gt;
&lt;fx:Script&gt;&lt;![CDATA[
public function removeAlignButtons():void {
rt1.toolbar.removeChild(rt1.alignButtons);
}
]]&gt;&lt;/fx:Script&gt;
&lt;s:VGroup&gt;
&lt;mx:RichTextEditor id="rt1"
title="RichTextEditor With No Align Buttons"
creationComplete="removeAlignButtons()"/&gt;
&lt;mx:RichTextEditor id="rt2"
title="Default RichTextEditor"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="section" id="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffa_verapache"><a name="WS2db454920e96a9e51e63e3d11c0bf63fd7-7fd9_verapache__WS2db454920e96a9e51e63e3d11c0bf63fd7-7ffa_verapache"><!-- --></a><h4 class="sectiontitle">Add
a new subcontrol</h4>
<ol>
<li>
<p>Create an ActionScript function
that defines the subcontrol. Also create any necessary methods to
support the control’s function. </p>
</li>
<li>
<p>Call the method in the RichTextEditor control’s <samp class="codeph">initialize</samp> event
listener, as in the following tag:</p>
<pre class="codeblock"> &lt;mx:RichTextEditor id="rt" initialize="addMyControl()"</pre>
</li>
</ol>
<p>The
following example adds a find-and-replace dialog box to a RichTextEditor control.
It consists of two files: the application, and a custom TitleWindow
control that defines the find-and-replace dialog (which also performs
the find-and-replace operation on the text). The application includes
a function that adds a button to pop up the TitleWindow, as follows: </p>
<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/CustomRTE.mxml --&gt;
&lt;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"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.*;
import mx.containers.*;
import flash.events.*;
import mx.managers.PopUpManager;
import mx.core.IFlexDisplayObject;
/* The variable for the pop-up dialog box. */
public var w:IFlexDisplayObject;
/* Add the Find/Replace button to the Rich Text Editor control's
tool bar container. */
public function addFindReplaceButton():void {
var but:Button = new mx.controls.Button();
but.label = "Find/Replace";
but.addEventListener("click",findReplaceDialog);
rt.toolbar.addChild(but);
}
/* The event listener for the Find/Replace button's click event
creates a pop-up with a MyTitleWindow custom control. */
public function findReplaceDialog(event:Event):void {
var w:MyTitleWindow = MyTitleWindow(PopUpManager.createPopUp(this, MyTitleWindow, true));
w.height=200;
w.width=340;
/* Pass the a reference to the textArea subcomponent
so that the custom control can replace the text. */
w.RTETextArea = rt.textArea;
PopUpManager.centerPopUp(w);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;mx:RichTextEditor id="rt" width="95%"
title="RichTextEditor"
text="This is a short sentence."
initialize="addFindReplaceButton()"/&gt;
&lt;/s:Application&gt;</pre>
<p>The following MyTitleWindow.mxml
file defines the custom myTitleWindow control that contains the
find-and-replace interface and logic:</p>
<pre class="noswf">&lt;?xml version="1.0"?&gt;
&lt;!-- textcontrols/MyTitleWindow.mxml --&gt;
&lt;!-- A TitleWindow that displays the X close button. Clicking the close button
only generates a CloseEvent event, so it must handle the event to close the control. --&gt;
&lt;mx:TitleWindow
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:mx="library://ns.adobe.com/flex/mx"
xmlns:s="library://ns.adobe.com/flex/spark"
title="Find/Replace"
showCloseButton="true"
close="closeDialog();"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.controls.TextArea;
import mx.managers.PopUpManager;
/* Reference to the RichTextArea textArea subcomponent.
It is set by the application findReplaceDialog method
and used in the replaceAndClose method, below. */
public var RTETextArea:TextArea;
/* The event handler for the Replace button's click event.
Replace the text in the RichTextEditor TextArea and
close the dialog box. */
public function replaceAndClose():void{
RTETextArea.text = RTETextArea.text.replace(ti1.text, ti2.text);
PopUpManager.removePopUp(this);
}
/* The event handler for the TitleWindow close button. */
public function closeDialog():void {
PopUpManager.removePopUp(this);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;!-- The TitleWindow subcomponents: the find and replace inputs,
their labels, and a button to initiate the operation. --&gt;
&lt;mx:Label text="Find what:"/&gt;
&lt;mx:TextInput id="ti1"/&gt;
&lt;mx:Label text="Replace with:"/&gt;
&lt;mx:TextInput id="ti2"/&gt;
&lt;mx:Button label="Replace" click="replaceAndClose();"/&gt;
&lt;/mx:TitleWindow&gt;</pre>
<p/>
</div>
</div>
</div>
<p>Adobe, Adobe AIR, Adobe Flash and Adobe Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries and are used by permission from Adobe. No other license to the Adobe trademarks are granted.</p>
</div>
</body>
</html>