Google Git
Sign in
apache / flex-site / ec799639d0bc0fab0451242bf01d2720166d9a1a / . / content / doc / flex / using / flx_sparktextcontrols_stc.html
blob: 56dcdab190efabb25ab0f9d8e8845a13065f0cb6 [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="Spark text controls"/>
<meta name="DC.Format" content="XHTML"/>
<meta name="DC.Identifier" content="WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache"/>
<link rel="stylesheet" type="text/css" href="commonltr.css"/>
<title>Spark text controls</title>
</head>
<body id="WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-8000_verapache"><!-- --></a>
<h1 class="topictitle1">Spark text controls</h1>
<div>
<p>
Text controls
in a Flex application can display text,
let the user enter text, or do both. </p>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fff_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fff_verapache"><!-- --></a>
<h2 class="topictitle2">About the Spark text controls</h2>
<div>
<p>You use Flex text-based controls to display text and to
let users enter text into your application. </p>
<p>The following table lists the primary Flex text-based controls:</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="d891776e58">
<p>Control</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e64">
<p>Component set</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e70">
<p>Superclass</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e76">
<p>Multi Line</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e82">
<p>Editable</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e89">
<p>textFlow/text/textDisplay</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Label.html" target="_blank">Label</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e64 ">
<p>Spark</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e70 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e76 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e82 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e89 ">
<p>text</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RichEditableText.html" target="_blank">RichEditableText</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e64 ">
<p>Spark</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e70 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e76 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e82 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e89 ">
<p>textFlow/text</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RichText.html" target="_blank">RichText</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e64 ">
<p>Spark</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e70 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e76 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e82 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e89 ">
<p>textFlow/text</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextArea.html" target="_blank">TextArea</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e64 ">
<p>Spark</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e70 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e76 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e82 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e89 ">
<p>textFlow/text</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e58 ">
<p>
<a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextInput.html" target="_blank">TextInput</a>
</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e64 ">
<p>Spark</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e70 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e76 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e82 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e89 ">
<p>text/textDisplay (textFlow)</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b167739a25a5e12695211e42-8000_verapache"><a name="WS02f7d8d4857b167739a25a5e12695211e42-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Comparing Spark and MX text controls</h3>
<div>
<p>This section describes the Spark text controls. For information
on the MX text controls, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d84_verapache">MX
text controls</a>.</p>
<p>How much control you have over the formatting of the text in
the control depends on the type of control. The MX controls support
a small set of formatting options with their style properties and
the <samp class="codeph">htmlText</samp> property. The Spark controls support
a richer set of formatting options because they are based on Flash
Text Engine (FTE) and Text Layout Framework (TLF). </p>
<p>Some MX controls can also use limited functionality of FTE and
TLF. For more information, see <a href="flx_fonts_ft.html#WSda78ed3a750d6b8f-26a13bbf123c441239d-8000_verapache">Using
FTE in MX controls</a>.</p>
<p>When building Flex 4 applications, you should use the Spark text
controls where possible. This is especially true if you plan on
using TLF or embedded fonts. In some cases, there are both MX and
Spark versions of the same text-based control. For example, there
are MX and Spark versions of the Label, TextArea, and TextInput
controls. The MX versions are in the mx.controls package.*. The
Spark versions are in the spark.components.* package.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b167739a25a5e12695211e42-7fff_verapache"><a name="WS02f7d8d4857b167739a25a5e12695211e42-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Spark text control feature overview</h3>
<div>
<p>The primary Spark controls for displaying text are Label,
RichText, and RichEditableText. The Label control has the least
amount of functionality, but is also the most lightweight. The RichEditableText
control has the most functionality, but also uses the most system
resources. </p>
<p>The following image shows the relationship among the Spark text
controls and FTE/TLE:</p>
<div class="figborder"><span class="figdesc">Relationship of the Spark text controls to FTE/TLF</span>
<img src="images/stc_text.png"/>
</div>
<p>The following table shows more information about these Spark
text primitives:</p>
<div class="p">
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="rows">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e407">
<p>Feature</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e413">
<p>Spark Label</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e419">
<p>RichText</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e425">
<p>RichEditableText</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Extends</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>UIComponent</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>UIComponent</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Uses</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>FTE</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>TLF</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>TLF</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Advanced typography</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Alpha</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Rotation</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Bi-directional text</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Default formatting with CSS
styles</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Multiple lines</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Multiple formats</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Multiple paragraphs</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Text object model</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Markup language</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Clickable HTML links</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Inline graphics</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>Y</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Hyperlinks</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Scrolling</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Selection</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e407 ">
<p>Editing</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e413 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e419 ">
<p>N</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e425 ">
<p>Y</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-3e3ce9f812699ed2335-8000_verapache"><a name="WS02f7d8d4857b1677-3e3ce9f812699ed2335-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Styling text controls</h3>
<div>
<div class="p">The default styles for Spark text control are set in CSS.
The easiest way to customize your text controls is to use CSS to
change style properties. For example, you can adjust the font size
and color by using the fontSize and color style properties as the
following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleStyleExample.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|RichText {
color: #33CC66;
fontStyle: italic;
fontSize: 24;
}
&lt;/fx:Style&gt;
&lt;s:RichText id="myRET"&gt;
This is the text.
&lt;/s:RichText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>CSS lets you adjust the styles of all controls of a certain type
(using a type selector) or any controls that match a certain class
(using a class selector).</p>
<div class="p">Spark text controls have a much richer set of style properties
than standard CSS because they support TLF. These style properties
include paragraph spacing, line spacing, and margins. The following
example sets the line height and space after each paragraph:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/AnotherStyleExample.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|RichText {
fontSize: 18;
lineHeight:16;
paragraphSpaceAfter: 10;
}
&lt;/fx:Style&gt;
&lt;s:RichText id="myRET" width="200"&gt;
&lt;s:p&gt;This is my text. There are many others like it, but this one is mine.&lt;/s:p&gt;
&lt;s:p&gt;My text is my best friend.&lt;/s:p&gt;
&lt;s:p&gt;It is my life. I must master it as I must master my life.&lt;/s:p&gt;
&lt;s:p&gt;Without me, my text is useless.&lt;/s:p&gt;
&lt;/s:RichText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>With TLF, you can also manipulate the appearance of text within
the TextFlow at compile time or run-time. For more information,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff2_verapache">Styling
TLF-based text controls</a>.</p>
<p>When styling the TextInput and TextArea controls, you should
keep in mind that the text is rendered by a RichEditableText subcomponent.
You access properties of this subcomponent with the <samp class="codeph">textDisplay</samp> property.
For more information, see <a href="flx_styles_st.html#WS2db454920e96a9e51e63e3d11c0bf69084-7ed9_verapache">Subcomponent
styles</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fde_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fde_verapache"><!-- --></a>
<h2 class="topictitle2">Label control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Label.html" target="_blank">Label</a> control
displays noneditable text. It is the lightest weight of the text controls.
The Label 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>You can control the alignment and sizing. </p>
</li>
<li>
<p>The control’s background is transparent, 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>
<li>
<p>The control can display multiple lines.</p>
</li>
<li>
<p>The control cannot be made selectable.</p>
</li>
</ul>
<p>For complete reference information, see the <em>
<a href="http://www.adobe.com/go/learn_flex4_apiref_en" target="_blank">ActionScript 3.0 Reference for the Adobe<sup>®</sup>
Flash<sup>®</sup> Platform</a>
</em>.</p>
<p>To create user-editable text fields, use the TextInput or TextArea
controls. For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fdb_verapache">TextInput
control</a> and <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fd3_verapache">TextArea
control</a>. </p>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdd_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdd_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a Label control</h3>
<div>
<div class="p">
You
define a Label control in MXML by using the <samp class="codeph">&lt;s: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. <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkLabelControl.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;s:Label text="Label1"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdc_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdc_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a Label control</h3>
<div>
<p>If you do not specify a width, the Label control automatically
resizes when you change the value of the <samp class="codeph">text</samp> property.</p>
<p>If you explicitly size a 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 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="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd3_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd3_verapache"><!-- --></a>
<h2 class="topictitle2">TextArea control</h2>
<div>
<p>
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextArea.html" target="_blank">TextArea</a> control
is a multiline, editable text field with a border and optional scroll
bars. The TextArea control supports the rich text rendering capabilities
of Flash Player and AIR. The TextArea control dispatches <samp class="codeph">change</samp> and <samp class="codeph">textInput</samp> events. </p>
<p>The TextArea control supports TLF. The text is rendered by a
RichEditableText subcomponent that is defined in the TextArea control’s
skin class.</p>
<p>For complete reference information, see the <em>
<a href="http://www.adobe.com/go/learn_flex4_apiref_en" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
<p>To create a single-line, editable text field, use the TextInput
control. For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fdb_verapache">TextInput
control</a>. To create noneditable text fields, use the Label
control. For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fde_verapache">Label
control</a>. </p>
<p>To change the disabled color for the TextArea control, you must
edit the TextAreaSkin class. </p>
<p>You can set a TextArea control’s <samp class="codeph">editable</samp> property
to <samp class="codeph">false</samp> to prevent editing of the text. You can
set a TextArea control’s <samp class="codeph">displayAsPassword</samp> property
to conceal input text by displaying characters as asterisks.</p>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd2_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd2_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a TextArea control</h3>
<div>
<div class="p">
You
define a TextArea control in MXML by using the <samp class="codeph">&lt;s:TextArea&gt;</samp> tag,
as the following example shows: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkTextAreaControl.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:TextArea id="textConfirm"
width="300" height="100"
text="Please enter your thoughts here."/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>Using large amounts of text in the TLF-based TextArea control
can cause a degradation in performance. As a result, in some cases,
you should use the MX TextArea control. For more information, see <a href="flx_textcontrols_tc.html#WS2db454920e96a9e51e63e3d11c0bf69084-7d51_verapache">MX
TextArea control</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd1_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd1_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing the TextArea control</h3>
<div>
<p>The TextArea control does not resize to fit the text that
it contains. </p>
<p>If the new text exceeds the capacity of a TextArea control and
the <samp class="codeph">horizontalScrollPolicy property</samp> is set to <samp class="codeph">true</samp> (the
default value), the control adds a scrollbar. </p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd0_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd0_verapache"><!-- --></a>
<h3 class="topictitle3">Using TLF with the TextArea control</h3>
<div>
<p>The TextArea control supports the advanced text formatting
and manipulation of TLF. You add TLF content to the TextArea control
by using either the <samp class="codeph">textFlow</samp> or <samp class="codeph">content</samp> properties. </p>
<div class="p">The following example adds a block of TLF-formatted text to the
TextArea control:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparktextcontrols/TextAreaTLF.mxml --&gt;
&lt;s:Application name="RichEditableTextExample"
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:Panel title="TextArea TLF"
width="90%" height="90%"
horizontalCenter="0" verticalCenter="0"&gt;
&lt;s:TextArea id="ta1" textAlign="left" percentWidth="90"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p fontSize="24"&gt;TextArea with TLF block&lt;/s:p&gt;
&lt;s:p&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:p&gt;
&lt;s:p&gt;2) Cras posuere posuere sem, &lt;s:span fontWeight="bold"&gt;eu congue orci mattis quis&lt;/s:span&gt;.&lt;/s:p&gt;
&lt;s:p&gt;3) Curabitur &lt;s:span textDecoration="underline"&gt;pulvinar tellus&lt;/s:span&gt; venenatis ipsum tempus lobortis.&lt;s:br/&gt;
&lt;s:span color="0x6600CC"&gt;Vestibulum eros velit&lt;/s:span&gt;, bibendum at aliquet ut.
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:TextArea&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt; </pre>
</div>
<p>For more information about using TLF with Spark text controls,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache">Using
Text Layout Framework</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-7d190b8d126b3bd198b-8000_verapache"><a name="WS02f7d8d4857b1677-7d190b8d126b3bd198b-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Styling the TextArea control</h3>
<div>
<p>The TextArea control uses a RichEditableText control as
a subcomponent to render the text. You can set the values of inheritable
style properties on the TextArea contorl, and those properties are
inherited by the RichEditableText subcomponent.</p>
<p>To access the RichEditableText control, you use the <samp class="codeph">textDisplay</samp> property.
You can access this property to set style properties that are noninheritable;
for example, the <samp class="codeph">columnCount</samp> and <samp class="codeph">columnGap</samp> properties. </p>
<p>There are some exceptions to noninheritable styles. For example,
the <samp class="codeph">verticalAlign</samp>, <samp class="codeph">lineBreak</samp>,
and <samp class="codeph">paddingBottom/Left/Right/Top</samp> style properties
are noninheritable. You can set these properties, which are defined
on the RichEditableText control, directly on the TextArea control
because the TextAreaSkin class passes them through to the subcomponent.</p>
<div class="p">The following example sets styles on the RichEditableText subcomponent
with the <samp class="codeph">textDisplay</samp> property, and also sets the
values of some noninheriting style properties that are not normally
accessible. You must cast the <samp class="codeph">textDisplay</samp> property
as a RichEditableText object before you can call methods such as <samp class="codeph">setStyle()</samp> on
it.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkTextAreaStyles.mxml --&gt;
&lt;s:Application
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"
creationComplete="initApp()"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
/*
Non-inheriting styles you must set on textDisplay:
columnCount
columnGap
columnWidth
Non-inheriting styles that you can set on TextArea because
they are passed to the subcomponent through the TextAreaSkin class:
lineBreak
paddingTop/Bottom/Left/Right
verticalAlign
*/
import spark.components.RichEditableText;
private function initApp():void {
RichEditableText(ta1.textDisplay).setStyle("columnCount", 3);
RichEditableText(ta1.textDisplay).setStyle("columnWidth", 100);
RichEditableText(ta1.textDisplay).setStyle("columnGap", 15);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextArea id="ta1" height="100" width="400" verticalAlign="bottom" paddingBottom="20"&gt;
This is a text area control. Because the text rendering is done by a RichEditableText subcontrol,
you have to use the textDisplay property to set the values of some non-inheriting styles.
Other non-inheriting styles are defined in the skin class and are passed through to the
subcomponent.
For inheriting styles, they are inherited by the RichEditableText subcontrol.
&lt;/s:TextArea&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdb_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fdb_verapache"><!-- --></a>
<h2 class="topictitle2">TextInput control</h2>
<div>
<p>
The Spark <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextInput.html" target="_blank">TextInput</a> control
is a single-line text field that is optionally editable. This control
supports TLF. The text is rendered by a RichEditableText subcomponent
in its skin class.</p>
<p>For complete reference information, see the <em>
<a href="http://www.adobe.com/go/learn_flex4_apiref_en" target="_blank">ActionScript 3.0 Reference for the Adobe
Flash Platform</a>
</em>.</p>
<p>To create a multiline, editable text field, use a TextArea control.
For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fd3_verapache">TextArea
control</a>. To create noneditable text fields, use the Label
or RichText controls. For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fde_verapache">Label
control</a> and <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fca_verapache">RichText
control</a>.</p>
<p>The TextInput control does not include a label, but you can add
one by using a Label control or by nesting the TextInput control
in a FormItem container in a Form layout container. </p>
<div class="p">To change the disabled color for the Spark TextInput control,
you must edit the TextInputSkin class. The following example shows
the differences between the enabled and disabled versions of the
Spark and MX TextInput controls:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextInputDisabledColors.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:VGroup&gt;
&lt;mx:TextInput enabled="false" text="disabled MX"/&gt;
&lt;mx:TextInput enabled="true" text="enabled MX"/&gt;
&lt;s:TextInput enabled="false" text="disabled Spark"/&gt;
&lt;s:TextInput enabled="true" text="enabled Spark"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can set a TextInput control’s <samp class="codeph">editable</samp> property
to <samp class="codeph">false</samp> to prevent users from editing the text.
You can set a 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="WS02f7d8d4857b1677-165a04e1126951a2d98-7fda_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fda_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a TextInput control</h3>
<div>
<div class="p">
You
define a TextInput control in MXML by using the <samp class="codeph">&lt;s: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. <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkTextInputControl.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:TextInput id="text1" width="100"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can use the <samp class="codeph">text</samp> property to specify a string
of raw text in the TextInput control.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd9_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd9_verapache"><!-- --></a>
<h3 class="topictitle3">Sizing a TextInput control</h3>
<div>
<p>If you do not specify a width, the TextInput control is
automatically sized when the application first completes loading.
The size of the TextInput control does not change in response to
user input or programmatic text input.</p>
<p>The TextInput control determines the value of its <samp class="codeph">measuredWidth</samp> property
by using a <samp class="codeph">widthInChars</samp> property rather than measuring
the text assigned to it, because the text frequently starts out
empty. This property is calculated based on the current font size
and style.</p>
<p>The value of its <samp class="codeph">measuredHeight</samp> property is
determined by the height of the current font. If you change the
font style or size, then the TextInput control resizes to accomodate
the new settings, even if there is no text in the control at the
time of the resizing.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd8_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd8_verapache"><!-- --></a>
<h3 class="topictitle3">Binding to a TextInput control</h3>
<div>
<div class="p">
In
some cases, you might want to bind a variable to the <samp class="codeph">text</samp> property
of a TextInput control so that the control represents a variable
value, as the following example shows: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkBoundTextInputControl.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;s:TextInput text="{myProp}"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>In this example, the TextInput control displays the value of
the <samp class="codeph">myProp</samp> 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 class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd7_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fd7_verapache"><!-- --></a>
<h3 class="topictitle3">Using TLF with the TextInput control</h3>
<div>
<p>You can use TLF with a TextInput control by accessing the <samp class="codeph">textDisplay</samp> property
and casting it as a RichEditableText object. This property points
to the underlying RichEditableText object that renders the text
in the TextInput control. The RichEditableText object is a subcomponent
that is defined in the TextInput control’s skin class.</p>
<div class="p">The following example defines a TextFlow as XML, and assigns
that to the TextInput control’s <samp class="codeph">textDisplay</samp>:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextInputTLF.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:Declarations&gt;
&lt;fx:XML id="myXML"&gt;
&lt;div&gt;
&lt;p&gt;Hello &lt;span fontWeight='bold'&gt;world&lt;/span&gt;!&lt;/p&gt;
&lt;/div&gt;
&lt;/fx:XML&gt;
&lt;/fx:Declarations&gt;
&lt;fx:Script&gt;
import spark.utils.TextFlowUtil;
import spark.components.RichEditableText;
private function initApp():void {
RichEditableText(text1.textDisplay).textFlow = TextFlowUtil.importFromXML(myXML);
}
&lt;/fx:Script&gt;
&lt;s:TextInput id="text1" width="100"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>For more information about using TLF with Spark text controls,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache">Using
Text Layout Framework</a>.</p>
</div>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fca_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fca_verapache"><!-- --></a>
<h2 class="topictitle2">RichText control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RichText.html" target="_blank">RichText</a> control
is a middleweight Spark text control. It can display richly-formatted
text, with multiple character and paragraph formats. However, it
is non-interactive: it does not support hyperlinks, scrolling, selection,
or editing. If you want a control that supports formatted text plus
scrolling, selection, and editing, you can use the RichEditableText
control.</p>
<p>For specifying the text, the RichText control supports the <samp class="codeph">textFlow</samp>, <samp class="codeph">text</samp>,
and <samp class="codeph">content</samp> properties. If you set the <samp class="codeph">text</samp> property,
the contents are read in as a String; tags such as <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;img&gt;</samp> are
ignored. If you set the <samp class="codeph">textFlow</samp> or <samp class="codeph">content</samp> properties,
then the contents are parsed by TLF and stored as a TextFlow object.
Tags such as <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;img&gt;</samp> are
mapped to instances of the ParagraphElement and InlineGraphicElement
classes.</p>
<div class="p">To create a RichText control, you use the <samp class="codeph">&lt;s:RichText&gt;</samp> tag
in MXML, as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/RichTextExample.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;!-- You can display simple text with the text property. --&gt;
&lt;s:RichText text="Hello World!"/&gt;
&lt;!-- Or the text child tag. --&gt;
&lt;s:RichText&gt;
&lt;s:text&gt;
Hello World!
&lt;/s:text&gt;
&lt;/s:RichText&gt;
&lt;!-- You can display formatted text with the default property. --&gt;
&lt;s:RichText&gt;
Hello &lt;s:span fontSize='16'&gt;BIG NEW&lt;/s:span&gt; World!
&lt;/s:RichText&gt;
&lt;!-- Or the TextFlow child tag. --&gt;
&lt;s:RichText&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
Hello &lt;s:span fontSize='16'&gt;BIG NEW&lt;/s:span&gt; World!
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The text in a RichText control can be horizontally and vertically
aligned but it cannot be scrolled. The contents of the control wraps
at the right edge of the control’s bounds. If the content extends
below the bottom, it is clipped. It is also clipped if you turn
off wrapping by setting the <samp class="codeph">lineBreak</samp> style property
to <samp class="codeph">explicit</samp> and add content that extends past the
right edge of the control.</p>
<p>The contents of a RichText control can be exported to XML using
the <samp class="codeph">export()</samp> method, which produces XML. </p>
<p>For more information about using TLF with Spark text controls,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache">Using
Text Layout Framework</a>.</p>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fc9_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fc9_verapache"><!-- --></a>
<h2 class="topictitle2">RichEditableText control</h2>
<div>
<p>The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/RichEditableText.html" target="_blank">RichEditableText</a> is
similar to the RichText control in that it can display richly-formatted
text, with multiple character and paragraph formats. In addition,
the RichEditableText control is interactive: it supports hyperlinks,
scrolling, selection, and editing. </p>
<p>The RichEditableText class is similar to the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/TextArea.html" target="_blank">TextArea</a> control,
except that it does not have a border, scroll bars, or focus glow.</p>
<p>
<strong>Creating a RichEditableText control</strong>
</p>
<div class="p">To create a RichEditableText control in MXML, you use the <samp class="codeph">&lt;s:RichEditableText&gt;</samp> tag,
as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/RichEditableTextExample.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;s:RichEditableText height="100" width="200"&gt;
&lt;s:text&gt;
Hello World!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>For specifying the text, the RichEditableText control supports
the <samp class="codeph">textFlow</samp>, <samp class="codeph">text</samp>, and <samp class="codeph">content</samp> properties.
If you set the <samp class="codeph">text</samp> property, the contents are read
in as a String; tags such as <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;img&gt;</samp> are
ignored. If you set the <samp class="codeph">textFlow</samp> or <samp class="codeph">content</samp> properties,
then the contents are parsed by TLF and stored in a TextFlow object.
Tags such as <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;img&gt;</samp> are
mapped to instances of the ParagraphElement and InlineGraphicElement
classes.</p>
<p>
<strong>Inserting and appending text</strong>
</p>
<p>The RichEditableText control also supports the <samp class="codeph">insertText()</samp> and <samp class="codeph">appendText()</samp> methods.
These methods let you add text to the contents of the control as
if you had typed it. The <samp class="codeph">insertText()</samp> method either
replaces a selection (if there is one) or adds the new text at the
current insertion point. The <samp class="codeph">appendText()</samp> adds
the text to the end of the contents. New text added with these methods
is not parsed by the TLF parser; it is read in as a literal string. </p>
<p>The <samp class="codeph">insertText()</samp> method does not insert text
unless the RichEditableText control has focus. The <samp class="codeph">appendText()</samp> appends
text even if the RichEditableText control does not have the focus.
If the RichEditableText control gets focus by pressing the Tab key,
the <samp class="codeph">insertText()</samp> method inserts the text before
any existing text. If the control gets focus by clicking within
the control, the text is inserted at the insertion point.</p>
<div class="p">The following example lets you append or insert new text to the
RichEditableText control:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/AddTextExample.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[
[Bindable]
private var newText:String = "&lt;p&gt;This is the new text.&lt;/p&gt;";
private function insertNewText():void {
myRET.insertText(newText);
}
private function appendNewText():void {
myRET.appendText(newText);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;This is paragraph 1.&lt;/s:p&gt;
&lt;s:p&gt;This is paragraph 2.&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Insert New Text" click="insertNewText()"/&gt;
&lt;s:Button label="Append New Text" click="appendNewText()"/&gt;
&lt;/s:HGroup&gt;
&lt;s:Label text="New text to add: '{newText}'"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The contents of a RichEditableText control can be exported to
XML using the <samp class="codeph">export()</samp> method, which produces XML. </p>
<p>
<strong>Making content selectable and editable</strong>
</p>
<p>You can make the content of the RichEditableText control selectable
by setting the <samp class="codeph">selectable</samp> property to <samp class="codeph">true</samp>.
You can make the content of the RichEditableText control editable
by setting the <samp class="codeph">editable</samp> property to <samp class="codeph">true</samp>.</p>
<div class="p">The following example makes the RichEditableText content both
selectable and editable:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/RETEditableAndSelectable.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;s:RichEditableText height="100" width="200"
editable="true"
selectable="true"&gt;
&lt;s:text&gt;
This text is editable and selectable!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can read the selection range with the read-only <samp class="codeph">selectionAnchorPosition</samp> and <samp class="codeph">selectionActivePosition</samp> properties.
You can set the selection with the <samp class="codeph">selectRange()</samp> method.
For examples of using the <samp class="codeph">selectRange()</samp> method,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fe4_verapache">Selecting
text</a>.</p>
<p>
<strong>Using the getFormatOfRange() and setFormatOfRange() methods</strong>
</p>
<p>To determine the text formatting on the selection, use the <samp class="codeph">getFormatOfRange()</samp> method.
This method returns a TextLayoutFormat object. This returns the
computed value of every property on the control, including defaults.</p>
<div class="p">You can set the format of the selection with the <samp class="codeph">setFormatOfRange()</samp> method.
In general, you should not use <samp class="codeph">getFormatOfRange()</samp> method
to get the TextLayoutFormat and then set properties on that. This
overwrites custom properties you might have already set on the text
control with the default values. The following example is not a
best practice, as it overwrites any custom properties:<pre class="codeblock">var tf:TextLayoutFormat = myTextControl.getFormatOfRange(null,0,0);
tf.fontSize = 16;
tf.fontWeight = FontWeight.BOLD;
myTextControl.setFormatOfRange(tf,0,0);</pre>
</div>
<div class="p">The following example uses the <samp class="codeph">setFormatOfRange()</samp> method
to apply properties without overwriting other custom properties
with the defaults:<pre class="codeblock">var tf:TextLayoutFormat = new TextLayoutFormat();
tf.fontSize = 16;
tf.fontWeight = FontWeight.BOLD;
myTextControl.setFormatOfRange(tf,0,0);</pre>
</div>
<p>
<strong>Clipping content</strong>
</p>
<div class="p">You can clip contents of the RichEditableText control and let
users scroll it by setting the <samp class="codeph">clipAndEnableScrolling</samp> property
to <samp class="codeph">true</samp>, as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/RETClipAndScroll.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;s:RichEditableText height="100" width="200" clipAndEnableScrolling="true"&gt;
&lt;s:text&gt;
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>
<strong>Adding scrollbars </strong>
</p>
<div class="p">The RichEditableText control does not add scroll bars for you,
even when scrolling and clipping is enabled. To add scroll bars
to a RichEditableText control, you can wrap the RichEditableText
control in a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/components/Scroller.html" target="_blank">Scroller</a> class,
as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/ScrollableRET.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;s:Scroller&gt;
&lt;s:RichEditableText height="100" width="200"
editable="true"
selectable="true"&gt;
&lt;s:text&gt;
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
This text scrolls vertically!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Scroller&gt;
&lt;s:Label text="To enable horizontal scrolling, set lineBreak to explicit:"/&gt;
&lt;s:Scroller&gt;
&lt;s:RichEditableText height="100" width="200"
editable="true"
selectable="true"
lineBreak="explicit"&gt;
&lt;s:text&gt;
This text scrolls horizontally! This text scrolls horizontally! This text scrolls horizontally!
This text scrolls horizontally! This text scrolls horizontally! This text scrolls horizontally!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Scroller&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The RichEditableText control supports programmatic scrolling
with its IViewport interface; it scrolls in response to the mousewheel;
and it automatically scrolls as you drag-select or type more text
than fits in the control’s bounds. The Scroller class lets you put
anything that implements the IViewport interface, such as the RichEditableText
control, in it to be scrolled.</p>
<p>
<strong>Selecting ranges</strong>
</p>
<div class="p">If you select a range of text that is not in the current viewport,
you can programmatically scroll to that range by using the <samp class="codeph">scrollToRange()</samp> method.
The following example selects the 10th line and then scrolls to
that line when you click the button:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SelectScrollableRET.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[
private function scrollToLine():void {
myRET.selectRange(440, 471);
myRET.scrollToRange(440, 471);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Scroller&gt;
&lt;s:RichEditableText id="myRET"
selectionHighlighting="always"
selectable="true"
height="100" width="200"&gt;
&lt;s:text&gt;
This text scrolls vertically1!
This text scrolls vertically2!
This text scrolls vertically3!
This text scrolls vertically4!
This text scrolls vertically5!
This text scrolls vertically6!
This text scrolls vertically7!
This text scrolls vertically8!
This text scrolls vertically9!
This text scrolls vertically10!
This text scrolls vertically11!
This text scrolls vertically12!
This text scrolls vertically13!
This text scrolls vertically14!
&lt;/s:text&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Scroller&gt;
&lt;s:Button label="Select and Scroll to Line 10" click="scrollToLine()"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>For more information about using TLF with Spark text controls,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache">Using
Text Layout Framework</a>.</p>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fec_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fec_verapache"><!-- --></a>
<h2 class="topictitle2">Adding content to text controls</h2>
<div>
<p>The Spark 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. All text based
controls support this property. For information on using the <samp class="codeph">text</samp> property,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fea_verapache">Using
the text property </a>. </p>
</dd>
<dt class="dlterm">default</dt>
<dd>
<p>Setting the default property is the same as using the <samp class="codeph">textFlow</samp> property,
and is less verbose. Tags set in the default property are parsed
at compile time, just as any other MXML tag.</p>
</dd>
<dt class="dlterm">textFlow</dt>
<dd>
<p>A rich set of tags and TLF formatting. Most Spark text-based
controls support this property. You typically use this property
if you do not know the contents of the rich text at compile time.
For information on using the <samp class="codeph">textFlow</samp> property,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffc_verapache">Creating
TextFlow objects</a>. </p>
</dd>
</dl>
<p>Typically, if your text does not contain any formatting, use
the <samp class="codeph">text</samp> property. If your text contains formatting,
use the <samp class="codeph">textFlow</samp> or default properties.</p>
<p>You can set formatted text by using the <samp class="codeph">textFlow</samp> or
default properties, and get it back as a plain text string by using
the <samp class="codeph">text</samp> property. </p>
<p>If you set more than one content-related property on a Spark
text control in ActionScript (such as <samp class="codeph">text</samp>
<em>and</em>
<samp class="codeph">textFlow</samp>),
the last one set wins. If you set more than one of these properties
as an attribute on an MXML tag, however, the winning setter cannot
be predicted. The compiler does not guarantee the order in which
MXML attributes get applied to a component.</p>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7feb_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7feb_verapache"><!-- --></a>
<h3 class="topictitle3">Using the default property</h3>
<div>
<p>You can use the default property (<samp class="codeph">content</samp>)
to add text to TLF-based text controls. These controls include the
RichText, RichEditableText, and TextArea controls. Text that is
added with the default property is parsed by the TLF and stored
as a TextFlow object.</p>
<p>The following example sets the default property:</p>
<pre class="codeblock">&lt;s:RichText id="myRT" width="450"&gt;
This is text.
&lt;/s:RichText&gt;</pre>
<p>If you are using TLF with your text controls, then you should
generally use the <samp class="codeph">textFlow</samp> property to set the
contents. The default property is set only, and it is less efficient
than the <samp class="codeph">textFlow</samp> property. If you set the contents
of a text control with the default property, you can then get it
with either the <samp class="codeph">textFlow</samp> property (gets a TextFlow
object) or the <samp class="codeph">text</samp> property (gets a plain text
String object). For more information about using the <samp class="codeph">textFlow</samp> property,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ffc_verapache">Creating TextFlow
objects</a>.</p>
<div class="p">Typically, you start the value of the <samp class="codeph">content</samp> property
with a paragraph tag. That tag then contains <samp class="codeph">&lt;span&gt;</samp> elements
or breaks or anchor tags. TLF renders text set by the default property
by putting it into a span, and that into a paragraph, and that into
a TextFlow, and then rendering the TextFlow. The resulting tree
uses the following structure:<pre class="codeblock">&lt;TextFlow&gt;
&lt;p&gt;
&lt;span&gt;
&lt;<em>contents</em> ... &gt;</pre>
</div>
<p>When using the default property to add text to a control, you
can use a subset of HTML in the content. This list matches the supported
tags of the <samp class="codeph">&lt;s:textFlow&gt;</samp> tag. For a list
of supported tags, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff6_verapache">Markup
tags supported in TextFlow objects</a>.</p>
<p>The content of the default property is typed as Object because
you can set it to a String, a FlowElement, or an Array of Strings
and FlowElement objects. </p>
<div class="p">In the following example, the <samp class="codeph">&lt;span&gt;</samp> tag
is one FlowElement, and the character data “<samp class="codeph">World</samp>”
is treated as if it were wrapped in a <samp class="codeph">&lt;String&gt;</samp> tag:<pre class="codeblock">&lt;s:RichText fontSize="12" xmlns="library://ns.adobe.com/flex/spark"&gt;
&lt;span fontWeight="bold"&gt;Hello&lt;/span&gt;World
&lt;/s:RichText&gt;</pre>
</div>
<div class="p">You can also set the content to a single FlowElement:<pre class="codeblock">&lt;s:RichText fontSize="12" xmlns="library://ns.adobe.com/flex/spark"&gt;
&lt;span fontWeight="bold"&gt;Hello World&lt;/span&gt;
&lt;/s:RichText&gt;</pre>
</div>
<div class="p">or to a single String:<pre class="codeblock">&lt;s:RichText fontSize="12" fontWeight="bold"&gt;Hello World&lt;/s:RichText&gt;</pre>
</div>
<p>Note that if you use a tag for the default property (such as <samp class="codeph">&lt;span&gt;</samp>),
you must specify the namespace in the opening tag of the text control.
Otherwise, the compiler will not recognize the tag in the text.</p>
<div class="p">Because there is only one format across all of the content, however,
it is more efficient to set the formatting on the RichText tag and
the content with the <samp class="codeph">text</samp> property, as the following
example shows:<pre class="codeblock">&lt;s:RichText fontSize="12" fontWeight="bold" text="Hello World"/&gt;</pre>
</div>
<p>There is no getter for the default property. Instead, you access
the host component’s <samp class="codeph">textFlow</samp> property to get the
parsed contents or the component’s <samp class="codeph">text</samp> property
to get a simple string.</p>
<p>You can add special characters such as ampersands and angle brackets
in the default property. To do this, use the same rules as described
in <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7fe9_verapache">Specifying
special characters in the text property</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fea_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fea_verapache"><!-- --></a>
<h3 class="topictitle3">Using the text property </h3>
<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. All text-based
Flex controls support a <samp class="codeph">text</samp> property. When you
set this property, any tags (such as HTML) in the text string appear
in the control as literal text. </p>
<p>The interpretation of \r, \n and \r\n as paragraph separators
is the only interpretation that occurs when setting the value of
the <samp class="codeph">text</samp> property.</p>
<div class="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, as the following example
shows:<pre class="codeblock">&lt;s:RichText fontSize="12" fontWeight="bold" text="Hello World"/&gt;</pre>
</div>
<p>For Spark controls that support TLF, you can set the text and
then manipulate it with the TLF API. You can access nodes of the
text object model and format parts of the content. </p>
<p>The following code line uses a <samp class="codeph">text</samp> property
to specify Label text:</p>
<pre class="codeblock"> &lt;s:Label text="This is a simple text label"/&gt;</pre>
<div class="p">You can also use a <samp class="codeph">&lt;s:text&gt;</samp> child tag
to specify text, as the following example shows:<pre class="codeblock">&lt;s:Label&gt;
&lt;s:text&gt;
This is a simple text label.
&lt;/s:text&gt;
&lt;/s:Label&gt;</pre>
</div>
<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="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe9_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe9_verapache"><!-- --></a>
<h4 class="topictitle4">Specifying special characters in
the text property</h4>
<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 a <samp class="codeph">&lt;s: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 a <samp class="codeph">&lt;s:text&gt;</samp> subtag.
To include line breaks, put the text in a CDATA section.</p>
</li>
</ul>
<div class="p">The
following code example uses the <samp class="codeph">text</samp> property with
standard text:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkStandardText.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;s:Label 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;s:Label 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;s:Label width="400"&gt;
&lt;s:text&gt;
This string contains a less than, &amp;lt;, greater than,
&amp;gt;, ampersand, &amp;amp;, apostrophe, ', and quotation mark, ".
&lt;/s:text&gt;
&lt;/s:Label&gt;
&lt;/s:Application&gt;</pre>
</div>
<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. The third one has leading and trailing newlines and converts
any tabs to newlines.</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 a <samp class="codeph">&lt;s: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>
<div class="p">The
following code example follows these CDATA section rules:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkTextCDATA.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:Label width="100%"&gt;
&lt;s:text&gt;
&lt;![CDATA[
This string contains a less than, &lt;, greater than, &gt;,
ampersand, &amp;, apostrophe, ', return,
tab. and quotation mark, ".
]]&gt;
&lt;/s:text&gt;
&lt;/s:Label&gt;
&lt;/s:Application&gt;</pre>
</div>
<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="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe8_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe8_verapache"><!-- --></a>
<h4 class="topictitle4">Specifying special characters in
ActionScript</h4>
<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>
<div class="p">The following example uses an initialization function to set
the <samp class="codeph">text</samp> property to a string that contains these
characters: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkInitText.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;s:RichText width="450" id="myText" tabStops="100 200 300 400"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="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: <pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkVarText.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;s:RichText width="450" text="{myText}" tabStops="100 200 300 400"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<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: When you specify a tab character, you
should be sure to create tab stops with the tabStops style property.
Otherwise, the tab will instead be rendered as a carriage return.
The RichText, RichEditableText, and Spark TextArea controls support
the tabStops property, but the Label control does not.)</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>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe4_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe4_verapache"><!-- --></a>
<h2 class="topictitle2">Selecting text</h2>
<div>
<p>
The
editable text controls provide properties and methods to select
text regions and get the contents of the selections. </p>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe2_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe2_verapache"><!-- --></a>
<h3 class="topictitle3">Creating a selection</h3>
<div>
<div class="p">The following controls let you select text:<ul>
<li>
<p>RichEditableText</p>
</li>
<li>
<p>TextInput</p>
</li>
<li>
<p>TextArea</p>
</li>
<li>
<p>All controls that use these controls as a subcomponent</p>
</li>
</ul>
</div>
<p>The selectable text controls provide the <samp class="codeph">selectRange()</samp> method,
which 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 you want to select.</p>
<div class="p">The following example shows how to select the first 10 characters
of various text controls:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SetSelectionTest.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[
private function selectText():void {
sparkTextArea.selectRange(0, 10);
sparkTextInput.selectRange(0, 10);
sparkRET.selectRange(0, 10);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextArea id="sparkTextArea"
selectionHighlighting="always"
selectable="true"
text="Spark TextArea control."/&gt;
&lt;s:TextInput id="sparkTextInput"
selectionHighlighting="always"
selectable="true"
text="Spark TextInput control."/&gt;
&lt;s:RichEditableText id="sparkRET"
selectionHighlighting="always"
selectable="true"
text="Spark RichEditableText control."/&gt;
&lt;s:Button click="selectText()" label="Select Text"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>To determine when the selection is highlighted, you can use the <samp class="codeph">selectionHighlighting</samp> property.
Possible values are <samp class="codeph">always</samp>, <samp class="codeph">whenFocused</samp>,
and <samp class="codeph">whenActive</samp>.</p>
<div class="p">To select all text in a text control, use the <samp class="codeph">selectAll()</samp> method,
as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SelectAllExample.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[
private function selectText(e:Event):void {
e.currentTarget.selectAll();
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextArea id="sparkTextArea"
text="Spark TextArea control." focusIn="selectText(event)"/&gt;
&lt;s:TextInput id="sparkTextInput" text="Spark TextInput control." focusIn="selectText(event)"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>TLF-based text controls have additional APIs that let you select
text in different ways. For example, you can programmatically select
a particular SpanElement object within a TextFlow, depending on
where the cursor is. To do this, you walk the text object model’s
tree of elements (or leaves) and compare the cursor’s position against
each leaf element’s character range.</p>
<div class="p">The following example selects only the SpanElement that is under
the mouse click:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkSelectionExample.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 flashx.textLayout.elements.TextRange;
import flashx.textLayout.elements.*;
private function selectSomeText(e:Event):void {
/* Get the location of the cursor. This is the character position of the
cursor in the RichEditableText control after the user clicks on it. */
var activePos:int = richTxt1.selectionActivePosition;
/* Get the first SpanElement in the TextFlow. */
var leaf:SpanElement = new SpanElement();
leaf = SpanElement(richTxt1.textFlow.getFirstLeaf());
/* Get the start and end index values for the first SpanElement. */
var spanStart:int = leaf.getParagraph().parentRelativeStart;
var spanEnd:int = leaf.getParagraph().parentRelativeEnd;
/* For the first SpanElement, if the cursor position falls within the
SpanElement's character range, then select the entire SpanElement. */
if (activePos &gt;= spanStart &amp;&amp; activePos &lt;= spanEnd) {
selectSpan(spanStart, spanEnd);
return;
}
/* Perform the same operations for each leaf in the TextFlow. */
while(leaf = SpanElement(leaf.getNextLeaf())) {
spanStart = leaf.getParagraph().parentRelativeStart;
spanEnd = leaf.getParagraph().parentRelativeEnd;
if (activePos &gt;= spanStart &amp;&amp; activePos &lt;= spanEnd) {
selectSpan(spanStart, spanEnd);
return;
}
}
}
private function selectSpan(i1:int, i2:int):void {
richTxt1.selectRange(i1, i2);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Panel&gt;
&lt;s:RichEditableText id="richTxt1" click="selectSomeText(event)" selectable="true" editable="true" textAlign="justify" percentWidth="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;&lt;s:span&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>Rather than iterating over all the leaf elements in the TextFlow
object, you can also use the TextFlow class’s <samp class="codeph">findLeaf()</samp> method.
This method lets you find an element based on a relative position.
For an example of using the <samp class="codeph">findLeaf()</samp> method,
see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff5_verapache">Navigating
TextFlow objects</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe1_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fe1_verapache"><!-- --></a>
<h3 class="topictitle3">Getting a selection</h3>
<div>
<p>You get the anchor and active positions of the selected
text to get a text control’s current selection. You then get the
value of the characters between those positions.</p>
<p>To get the selected text in a text control, you use the <samp class="codeph">selectionAnchorPosition</samp> and <samp class="codeph">selectionActivePosition</samp> properties
of the text control. These properties define the position at the
start of the selection and at the end of the selection, respectively.
You use the <samp class="codeph">substring()</samp> method on the contents
of the control, and pass these positions to identify the range of
characters to return.</p>
<div class="p">The following example displays the selections of the RichEditableText
control when you click the button:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SparkTraceSelectionRanges.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;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import mx.core.IUITextField;
import flashx.textLayout.elements.TextRange;
private function initApp():void {
sparkRET.selectRange(0, 10);
}
private function getTextSelection():void {
var anchorPos:int = sparkRET.selectionAnchorPosition;
var activePos:int = sparkRET.selectionActivePosition;
myLabel.text = "Current Selection: \"" + sparkRET.text.substring(anchorPos, activePos) + "\"";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="sparkRET"
selectionHighlighting="always"
selectable="true"
text="Spark RichEditableText control."/&gt;
&lt;s:Button click="getTextSelection()" label="Show Current Selection"/&gt;
&lt;s:Label id="myLabel"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested1" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffe_verapache"><!-- --></a>
<h2 class="topictitle2">Using Text Layout Framework</h2>
<div>
<p>The Text Layout Framework (TLF) is a class library built
on top of the Flash Text Engine (FTE). The FTE, available in Flash
Player 10 and Adobe AIR™ 1.5, adds advanced text capabilities to
Flash Player. FTE provides a set of low-level APIs for libraries
that leverage these capabilities. The FTE classes are in the flash.text.engine
package. In most cases, you will not use these classes directly.</p>
<p>The TLF classes are in the flashx.textLayout.* package. You are
likely to use the TLF classes when you apply styles with HTML markup
to text in text controls that support TLF. These controls include
the RichText and RichEditableText controls, as well as the Spark
TextArea control. </p>
<p>The primary difference between most Spark and MX text-based controls
is the control over the formatting. For Spark controls, the formatting
is provided by either FTE or TLF. This gives you a great deal of
control over the text formatting, including support for HTML tags,
columns, and bi-directional text. </p>
<p>TLF is not used by Flex text controls in mobile applications.
When you create a mobile application, the mobile theme is automatically
applied. As a result, text-based controls use the mobile skins,
which do not support TLF. You can still use some of the same text
controls, but be aware that TLF is not used when the mobile theme
is applied. </p>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffd_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffd_verapache"><!-- --></a>
<h3 class="topictitle3">Features of TLF</h3>
<div>
<p>Text Layout Framework (TLF) is a class library built on
top of FTE. It provides high level text functionality, including:</p>
<div class="p">
<ul>
<li>
<p>Bi-directional text, vertical text, and over 30 writing
systems, including Arabic, Hebrew, Chinese, Japanese, Korean, Thai,
Lao, and the major writing systems of India</p>
</li>
<li>
<p>Selecting, editing, and flowing text across multiple columns
and linked containers, as well as around inline images</p>
</li>
<li>
<p>Vertical text, Tate-Chu-Yoko (horizontal within vertical
text), and justifiers for East Asian typography</p>
</li>
<li>
<p>Rich typographical controls, including kerning, ligatures,
typographic case, digit case, digit width, and discretionary hyphens</p>
</li>
<li>
<p>Cut, copy, paste, undo, and standard keyboard and mouse controls
for editing</p>
</li>
<li>
<p>Rich developer APIs to manipulate text content, layout, and
markup and to create custom text components </p>
</li>
<li>
<p>Robust list support including custom markers and numbering
formats</p>
</li>
<li>
<p>Inline images and positioning rules</p>
</li>
</ul>
</div>
<p>When you add text to a control that uses TLF, the text is stored
as a hierarchical tree of objects. The root element of this tree
is the TextFlow class. Each node in the tree is an instance of a
class defined in the flashx.textLayout.elements package. This tree
is known as the text object model. The text object model is a subset
of the FXG specification.</p>
<p>In the text object model, concepts such as paragraphs, spans,
and hyperlinks are not represented as formats that affect the appearance
of character runs in a single, central text string. Instead they
are represented by runtime-accessible ActionScript objects, with
their own properties, methods, and events (in some cases). </p>
<div class="p">The following lists the objects you can have in a TextFlow object:<ul>
<li>
<p>Paragraphs (ParagraphElement)</p>
</li>
<li>
<p>Images (InlineGraphicElement)</p>
</li>
<li>
<p>Hyperlinks (LinkElement)</p>
</li>
<li>
<p>Spans (SpanElement)</p>
</li>
<li>
<p>TCY blocks (TCYElement)</p>
</li>
<li>
<p>Tabs (TabElement) and line breaks (BreakElement)</p>
</li>
<li>
<p>Lists (ListElement)</p>
</li>
</ul>
</div>
<p>If a Spark text control supports the <samp class="codeph">textFlow</samp> property,
then you can use TLF to format and programmatically interact with
the contents of that text control. If the control supports only
the <samp class="codeph">text</samp> property for its content, then you can
only use a simple string for the text. The text does not get parsed
into the text object model. If an MX control supports the <samp class="codeph">htmlText</samp> property,
then you can use a subset of HTML tags to format the text, but its
content is still a simple string that does not support the formal
text object model.</p>
<p>You use the <samp class="codeph">textFlow</samp> property when you set the
value of the text at run time. The content of the <samp class="codeph">textFlow</samp> property
is strongly typed as a TextFlow object rather than an Object.</p>
<p>You use the default property when you set the value of the property
at compile time. This property takes a generic Object and converts
it to a TextFlow. In general, you should avoid using the default
property when the <samp class="codeph">textFlow</samp> property is available. </p>
<p>The Spark versions of the TextArea and TextInput classes support
TLF, as do the RichText and RichEditableText controls. The Spark
Label control supports FTE. The default MX controls do not support
TLF. However, it is possible to use TLF with some MX controls. For
more informations, see <a href="flx_fonts_ft.html#WSda78ed3a750d6b8f-26a13bbf123c441239d-8000_verapache">Using
FTE in MX controls</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffc_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffc_verapache"><!-- --></a>
<h3 class="topictitle3">Creating TextFlow objects</h3>
<div>
<p>The text object model is the tree that is created when
you add content to a text-based control that supports TLF. This
tree is defined by the TextFlow class.</p>
<p>When creating a <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/TextFlow.html" target="_blank">TextFlow</a> object,
you can use the classes in the flashx.textLayout.elements.* package
to provide formatting and additional functionality. These classes
include <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/DivElement.html" target="_blank">DivElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/ParagraphElement.html" target="_blank">ParagraphElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/InlineGraphicElement.html" target="_blank">InlineGraphicElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/LinkElement.html" target="_blank">LinkElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/SpanElement.html" target="_blank">SpanElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/TabElement.html" target="_blank">TabElement</a>, <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/BreakElement.html" target="_blank">BreakElement</a>,
and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/TCYElement.html" target="_blank">TCYElement</a>.</p>
<div class="p">You can create a TextFlow object in the following ways:<ul>
<li>
<p>Using the default property</p>
</li>
<li>
<p>Using the <samp class="codeph">&lt;s:textFlow&gt;</samp> child tag</p>
</li>
<li>
<p>Importing content with the TextFlowUtil class</p>
</li>
<li>
<p>Using ActionScript</p>
</li>
</ul>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffb_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffb_verapache"><!-- --></a>
<h4 class="topictitle4">Using the default property</h4>
<div>
<p>You can create a TextFlow object by adding content to a
text-based’s default property. When you do this, Flex creates a
TextFlow object that defines the text object model for you. For
more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7feb_verapache">Using
the default property</a>.</p>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffa_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ffa_verapache"><!-- --></a>
<h4 class="topictitle4">Creating a TextFlow object with
child tags</h4>
<div>
<p>You can also use the text control’s <samp class="codeph">&lt;s:textFlow&gt;</samp> child
tag to explicitly create a TextFlow object. This lets you structure
the contents of the text control by using the supported TLF tags
such as <samp class="codeph">&lt;p&gt;</samp>, <samp class="codeph">&lt;div&gt;</samp> and <samp class="codeph">&lt;span&gt;</samp>.</p>
<div class="p">When using the <samp class="codeph">&lt;s:textFlow&gt;</samp> child tag,
you must be sure to also include a <samp class="codeph">&lt;s:TextFlow&gt;</samp> tag
within that, so that the structure of the control’s uses the following
structure:<pre class="codeblock">&lt;s:<em>text_control</em>&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;.../&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:<em>text_control</em>&gt;</pre>
</div>
<div class="p">You should keep in mind that the default property can also create
a TextFlow object, so you could write the previous example as follows:<pre class="codeblock">&lt;s:<em>text_control</em>&gt;
&lt;.../&gt;
&lt;/s:<em>text_control</em>&gt;</pre>
</div>
<div class="p">The following example creates two text controls; one text control
defines a TextFlow object with the <samp class="codeph">&lt;s:textFlow&gt;</samp> child
tag, and the other with the default property.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/CreateTextFlowChildTags.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;s:RichEditableText id="richTxt1" textAlign="justify" percentWidth="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p fontSize="24"&gt;TextFlow Child Tag&lt;/s:p&gt;
&lt;s:p&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:p&gt;
&lt;s:p&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:p&gt;
&lt;s:p&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;s:RichEditableText id="richTxt2" textAlign="justify" percentWidth="100"&gt;
&lt;s:p fontSize="24"&gt;Default Property&lt;/s:p&gt;
&lt;s:p&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:p&gt;
&lt;s:p&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:p&gt;
&lt;s:p&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:p&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">It is also convenient to drop the prefix on the markup tags by
making the Spark library namespace the default namespace on the
text control’s tag, as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextFlowNamespace.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;s:RichEditableText id="richTxt1" textAlign="justify" percentWidth="100" xmlns="library://ns.adobe.com/flex/spark"&gt;
&lt;textFlow&gt;
&lt;TextFlow&gt;
&lt;p fontSize="24"&gt;TextFlow Child Tag&lt;/p&gt;
&lt;p&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/p&gt;
&lt;p&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/p&gt;
&lt;p&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/p&gt;
&lt;/TextFlow&gt;
&lt;/textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff9_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff9_verapache"><!-- --></a>
<h4 class="topictitle4">Creating a TextFlow object with
the TextFlowUtil class</h4>
<div>
<div class="p">If you don’t know the rich text that you want to display
until run-time, you can import HTML or XML to a TextFlow object.
The <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/spark/utils/TextFlowUtil.html" target="_blank">TextFlowUtil</a> class
has the following methods that let you add XML and strings as the
contents of a TextFlow object:<ul>
<li>
<p>
<samp class="codeph">importFromString()</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">importFromXML()</samp>
</p>
</li>
</ul>
</div>
<div class="p">The following example uses the <samp class="codeph">importFromString()</samp> method
to load a String object into the TextFlow:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextFlowMarkup.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="doSomething()"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;&lt;![CDATA[
import flashx.textLayout.elements.TextFlow;
import spark.utils.TextFlowUtil;
private function doSomething():void {
var markup:String = "&lt;p&gt;This is paragraph 1.&lt;/p&gt;&lt;p&gt;This is paragraph 2.&lt;/p&gt;";
var flow:TextFlow = TextFlowUtil.importFromString(markup);
myST.textFlow = flow;
}
]]&gt;&lt;/fx:Script&gt;
&lt;s:RichText id="myST" width="175"/&gt;
&lt;/s:Application&gt;</pre>
You can add also import XML by
using the TextFlowUtil class’s <samp class="codeph">importFromXML()</samp> method.
Any XML that uses valid TLF markup can be passed into a TextFlow.
This includes content returned by an HTTPService call, XML defined
in the application file itself, or XML defined in an external file. </div>
<div class="p">The following example uses an external file that defines a TextFlow
object for a text control: <pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparktextcontrols/ExternalXMLFile.mxml --&gt;
&lt;s:Application name="Spark_RichText_text_test"
xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import spark.utils.TextFlowUtil;
XML.ignoreWhitespace = false;
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Declarations&gt;
&lt;fx:XML id="textFlowAsXML" source="externalTextFlow1.xml" /&gt;
&lt;/fx:Declarations&gt;
&lt;s:RichText id="richTxt"
textFlow="{TextFlowUtil.importFromXML(textFlowAsXML)}"
horizontalCenter="0" verticalCenter="0" /&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The previous example uses the following file:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- http://blog.flexexamples.com/2009/08/11/setting-text-in-a-spark-richtext-control-in-flex-4/ --&gt;
&lt;TextFlow xmlns="http://ns.adobe.com/textLayout/2008" whiteSpaceCollapse="preserve"&gt;
&lt;p&gt;&lt;span&gt;The quick brown &lt;/span&gt; &lt;span fontWeight="bold"&gt;fox jumps over&lt;/span&gt; &lt;span&gt; the lazy dogg.&lt;/span&gt;&lt;/p&gt;
&lt;/TextFlow&gt;</pre>
</div>
<p>If the first tag in an imported XML object is not a <samp class="codeph">&lt;s:TextFlow&gt;</samp> tag,
then the parser inserts one for you. If the first tag is a <samp class="codeph">&lt;s:TextFlow&gt;</samp> tag,
then you must also define the <samp class="codeph">"http://ns.adobe.com/textLayout/2008"</samp> namespace
in that tag. </p>
<p>The parser converts the TLF tags to TLF classes (such as SpanElement
or DivElement) in the new TextFlow object.</p>
<p>This example used with permission from <a href="http://blog.flexexamples.com" target="_blank">http://blog.flexexamples.com</a>.</p>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff8_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff8_verapache"><!-- --></a>
<h4 class="topictitle4">Creating a TextFlow object with
the TextConverter class</h4>
<div>
<p>You can use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/conversion/TextConverter.html" target="_blank">TextConverter</a> class
to import content into a TextFlow. This is a little more advanced
than using the TextFlowUtil methods to create a TextFlow object.
Those methods act as wrappers around the TextConverter class. When you
import text with the TextConverter class’s <samp class="codeph">importToFlow()</samp> method, however,
you can specify the format of the text. This determines how the
content is stored. </p>
<div class="p">The following are the types of formats you can specify when using
the <samp class="codeph">importToFlow()</samp> method:<ul>
<li>
<p>HTML</p>
</li>
<li>
<p>Plain text</p>
</li>
<li>
<p>TLF</p>
</li>
</ul>
</div>
<p>If you specify the TLF format, then the imported text is used
to generate a text object model. If you specify plain text, then
the text is not interpreted, but instead stored as a simple text
string. If you specify HTML format, then the HTML tags in the text
are mapped to TLF classes (for example, <samp class="codeph">&lt;p&gt;</samp> is
mapped to a ParagraphElement object in the text object model).</p>
<div class="p">The following example imports an XML object into a TextFlow when
you click the Button control:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/AddingContentAsXML.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 spark.utils.TextFlowUtil;
import flashx.textLayout.elements.*;
import flashx.textLayout.conversion.*;
import mx.utils.*;
private var xml:XML = &lt;TextFlow xmlns='http://ns.adobe.com/textLayout/2008'&gt;&lt;p&gt;&lt;span&gt;This is a span&lt;/span&gt;&lt;/p&gt;&lt;/TextFlow&gt;;
private function addContent():void {
myRET.textFlow= TextConverter.importToFlow(xml, TextConverter.TEXT_LAYOUT_FORMAT);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"/&gt;
&lt;s:Button click="addContent()" label="Add Content"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The following example uses a variety of formats when importing
a String into the TextFlow with the <samp class="codeph">importToFlow()</samp> method:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparksparktextcontrols/ImportToFlowExample.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flashx.textLayout.conversion.TextConverter;
XML.ignoreWhitespace = false;
]]&gt;
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Declarations&gt;
&lt;!-- Define a String to use with HTML and plain text format. --&gt;
&lt;fx:String id="htmlTextAsHTML"&gt;&lt;![CDATA[&lt;p&gt;Hello &lt;b&gt;world!&lt;/b&gt;&lt;/p&gt;]]&gt;&lt;/fx:String&gt;
&lt;!-- Define an XML object to use with TLF format. --&gt;
&lt;fx:XML id="tfTextAsTextFlow"&gt;
&lt;TextFlow xmlns="http://ns.adobe.com/textLayout/2008"&gt;
&lt;p&gt;Hello &lt;span fontWeight="bold"&gt;world!&lt;/span&gt;&lt;/p&gt;
&lt;/TextFlow&gt;
&lt;/fx:XML&gt;
&lt;/fx:Declarations&gt;
&lt;s:RichText id="richTxt"
textFlow="{TextConverter.importToFlow(htmlTextAsHTML, TextConverter.TEXT_FIELD_HTML_FORMAT)}"
horizontalCenter="0" verticalCenter="0" /&gt;
&lt;s:RichText id="richTxt2"
textFlow="{TextConverter.importToFlow(htmlTextAsHTML, TextConverter.PLAIN_TEXT_FORMAT)}"
horizontalCenter="0" verticalCenter="0" /&gt;
&lt;s:RichText id="richTxt3"
textFlow="{TextConverter.importToFlow(tfTextAsTextFlow, TextConverter.TEXT_LAYOUT_FORMAT)}"
horizontalCenter="0" verticalCenter="0" /&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">When you use the <samp class="codeph">TEXT_LAYOUT_FORMAT</samp> type for
the TextConverter, the imported text must observe the following
rules:<ol>
<li>
<p>The first tag must be a <samp class="codeph">&lt;s:TextFlow&gt;</samp> tag.
The parser will not insert one for you as it does with the <samp class="codeph">TextFlowUtil.importFromXML()</samp> or <samp class="codeph">TextFlowUtil.importFromString()</samp> methods.</p>
</li>
<li>
<p>The first tag must specify a namespace for the imported text.
The namespace is <samp class="codeph">"http://ns.adobe.com/textLayout/2008"</samp>.</p>
</li>
<li>
<p>Subsequent tags must be supported by the TextFlow class.
For a list of supported tags, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff6_verapache">Markup
tags supported in TextFlow objects</a>.</p>
</li>
</ol>
</div>
<p>The TextConverter class also lets you export a TextFlow object’s
content in a variety of formats. </p>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff7_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff7_verapache"><!-- --></a>
<h4 class="topictitle4">Creating a TextFlow object in ActionScript</h4>
<div>
<p>You can create TextFlow objects that are used by TLF-based
text controls in ActionScript. </p>
<div class="p">If you create a TextFlow object in ActionScript, the TextFlow
object requires that either the ParagraphElement or DivElement be
at the top level. The following example creates two ParagraphElement
objects and wraps them in SpanElement objects. It then adds these
objects as children of a TextFlow object, and adds them to a RichEditableText
control’s content:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleTextModelExample.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;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
import flashx.textLayout.elements.*;
private var textFlow:TextFlow = new TextFlow();
private var paragraph1:ParagraphElement = new ParagraphElement();
private var paragraph2:ParagraphElement = new ParagraphElement();
private var span1:SpanElement = new SpanElement();
private var span2:SpanElement = new SpanElement();
private function initApp():void {
span1.text = "This is paragraph one in myRET.";
span2.text = "This is paragraph two in myRET.";
paragraph1.addChild(span1);
paragraph2.addChild(span2);
textFlow.addChild(paragraph1);
textFlow.addChild(paragraph2);
myRET.textFlow = textFlow;
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"/&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff6_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff6_verapache"><!-- --></a>
<h3 class="topictitle3">Markup tags supported in TextFlow
objects</h3>
<div>
<p>The TLF parser converts supported markup elements to TLF
classes so that they can be used in the text object model. These
markup elements are similar to the HTML tags of the same names.
For example, if you specify a <samp class="codeph">&lt;p&gt;</samp> tag in
your text control’s content, then the parser converts it to a ParagraphElement
in the control’s TextFlow.</p>
<div class="p">The following table describes the supported elements of the text
object model:
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="rows">
<thead align="left">
<tr>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e3312">
<p>Element</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e3318">
<p>Class</p>
</th>
<th class="cellrowborder" valign="top" width="NaN%" id="d891776e3324">
<p>Description</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>div</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>DivElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A division of text; can contain only div,
list, or p elements.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>p</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>ParagraphElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A paragraph; can contain any element except
div, list, or li.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>a</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>LinkElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A hypertext link, also known as an anchor;
can contain the tcy, span, img, tab, g, and br elements. This is
the only class in the text object model that supports Flex events.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>tcy</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>TCYElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A run of horizontal text, used in vertical
text such as Japanese; can contain the a, span, img, tab, g, or
br elements.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>span</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>SpanElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A run of text in a paragraph; cannot contain
other elements.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>img</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>InlineGraphicElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>An image in a paragraph element.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>tab</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>TabElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A tab character.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>br</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>BreakElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>A break character; text continues on the
next line, but does not start a new paragraph.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>list</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>ListElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>An ordered or unordered list. Can be simple
list or nested. You can customize the bullets. Can contain li elements
(ListItemElement) or other list elements.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>li</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>ListItemElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p>List items within a list element. Can be
ordered or unordered, nested or flat lists. You can customize the
markers as well as other settings of each list item.</p>
</td>
</tr>
<tr>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3312 ">
<p>g</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3318 ">
<p>SubParagraphGroupElement</p>
</td>
<td class="cellrowborder" valign="top" width="NaN%" headers="d891776e3324 ">
<p> A group element. Used for grouping elements
in a paragraph. This lets you nest elements below the paragraph
level.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff5_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff5_verapache"><!-- --></a>
<h3 class="topictitle3">Navigating TextFlow objects</h3>
<div>
<p>The TLF API provides methods and properties that let you
navigate the text object model after it is created. You can use
this API to perform actions on a individual leaves or the entire
tree.</p>
<div class="p">The following example iterates over the RichEditableText control’s
TextFlow and copies the contents of each SpanElement, one at a time,
into another RichEditableText control:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/IterateOverLeaves.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 flashx.textLayout.elements.*;
private function copyContents():void {
/* Get the first leaf in the TextFlow. */
var leaf:SpanElement = new SpanElement();
leaf = SpanElement(richTxt1.textFlow.getFirstLeaf());
/* Write the contents of the first leaf to the second RET control. */
richTxt2.text = "LEAF:" + leaf.text + "\n";
/* Iterate over the remaining leaves and write their contents
to the second RET control. */
while(leaf = SpanElement(leaf.getNextLeaf())) {
richTxt2.text += "LEAF:" + leaf.text + "\n";
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Panel&gt;
&lt;s:RichEditableText id="richTxt1" selectable="true" editable="true" textAlign="justify" percentWidth="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;&lt;s:span&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Panel&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Copy Contents" click="copyContents()"/&gt;
&lt;s:Button label="Clear" click="richTxt2.text=''"/&gt;
&lt;/s:HGroup&gt;
&lt;s:Panel&gt;
&lt;s:RichEditableText id="richTxt2" textAlign="justify" percentWidth="100"/&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The <samp class="codeph">TextFlow.findLeaf()</samp> method lets you specify
a character position and returns the entire flow element where that
character position occurs. The following example changes the color
of the entire SpanElement whenever the user clicks on any location
within that SpanElement’s paragraph:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/FindLeafExample.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 flashx.textLayout.elements.TextRange;
import flashx.textLayout.elements.*;
private function selectEntireLeaf(e:Event):void {
/* Get the location of the cursor. This is the character position of the
cursor in the RichEditableText control after the user clicks on it. */
var activePos:int = richTxt1.selectionActivePosition;
/* Change the color of the entire leaf under the cursor position. */
var leaf:SpanElement = richTxt1.textFlow.findLeaf(activePos) as SpanElement;
leaf.color = 0x00FF33;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Panel&gt;
&lt;s:RichEditableText id="richTxt1" click="selectEntireLeaf(event)" selectable="true" editable="true" textAlign="justify" percentWidth="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;&lt;s:span&gt;1) Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;2) Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;3) Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">You can access the objects in a TextFlow by their object names
and set the values of properties such as <samp class="codeph">color</samp> or <samp class="codeph">direction</samp> on
them in ActionScript. The text in the controls update accordingly,
as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/ManipulateTextModelExample.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;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
import flashx.textLayout.elements.*;
private var textFlow:TextFlow = new TextFlow();
private var paragraph1:ParagraphElement = new ParagraphElement();
private var paragraph2:ParagraphElement = new ParagraphElement();
private var span1:SpanElement = new SpanElement();
private var span2:SpanElement = new SpanElement();
private function initApp():void {
span1.text = "This is paragraph one.";
span2.text = "This is paragraph two.";
paragraph1.addChild(span1);
paragraph2.addChild(span2);
textFlow.addChild(paragraph1);
textFlow.addChild(paragraph2);
myRET.textFlow = textFlow;
}
private function changeColors():void {
// Change color of first paragraph.
paragraph1.color = 0xFF00FF;
// Change color of second paragraph.
paragraph2.setStyle("color", 0x00FF00);
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"&gt;
&lt;/s:RichEditableText&gt;
&lt;s:Button label="Change Colors" click="changeColors()"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>This example shows that you can set styles by using either the <samp class="codeph">setStyle()</samp> method
or the property accessors. For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff2_verapache">Styling
TLF-based text controls</a>.</p>
<div class="p">You can also access the objects in the text object model by using
their ids. You do this with the TextFlow class’s <samp class="codeph">getElementById()</samp> method.
This requires that you set the <samp class="codeph">id</samp> property of the
flow elements, as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/AccessTextFlowMethods.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;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
import flashx.textLayout.elements.*;
private var textFlow:TextFlow = new TextFlow();
private var paragraph1:ParagraphElement = new ParagraphElement();
private var paragraph2:ParagraphElement = new ParagraphElement();
private var span1:SpanElement = new SpanElement();
private var span2:SpanElement = new SpanElement();
private function initApp():void {
span1.id = "span1";
span2.id = "span2";
paragraph1.id = "paragraph1";
paragraph2.id = "paragraph2";
span1.text = "This is paragraph one.";
span2.text = "This is paragraph two.";
paragraph1.addChild(span1);
paragraph2.addChild(span2);
textFlow.addChild(paragraph1);
textFlow.addChild(paragraph2);
myRET.textFlow = textFlow;
}
private function changeColors():void {
// Set color of paragraph one.
textFlow.getElementByID("paragraph1").setStyle("color", 0xFF0000);
// Set color of paragraph two.
textFlow.getElementByID("paragraph2").setStyle("color", 0xFF0000);
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"&gt;
&lt;/s:RichEditableText&gt;
&lt;s:Button label="Change Colors" click="changeColors()"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>In the previous example, because the text flow elements are created
programmatically, their <samp class="codeph">id</samp> properties are also
set explicitly on the objects that represent the span and paragraph
elements. If you were creating the text flow with HTML markup, you
would specify the value of the <samp class="codeph">id</samp> property in the
HTML tag (for example, <samp class="codeph">&lt;span id="span1"&gt;</samp>).</p>
<p>Another way to “walk the tree” of a TextFlow object is to use
the methods of the ParagraphElement class. This class helps you
access low-level items such as atoms and words. For example, you
can use the <samp class="codeph">findNextWordBoundary()</samp> and <samp class="codeph">findPreviousWordBoundary()</samp> methods
to navigate the word boundaries in the flow element’s text.</p>
<div class="p">The following example uses methods of the ParagraphElement class
to count the words and determine the average length of them in the
TextFlow:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/FindWords.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 flashx.textLayout.elements.*;
private function countWords():void {
var leaf:SpanElement = new SpanElement();
leaf = SpanElement(richTxt1.textFlow.getFirstLeaf());
var p:ParagraphElement = new ParagraphElement();
p = leaf.getParagraph();
doSomething(p);
while (leaf = SpanElement(leaf.getNextLeaf())) {
p = leaf.getParagraph();
doSomething(p);
}
wcLabel.text += "# Words: " + wordCount;
lenLabel.text += "Avg length of each word: " + lenTotal/wordCount + " chars";
}
private var wordCount:int = 0;
private var lenTotal:int = 0;
private function doSomething(p:ParagraphElement):void {
var wordBoundary:int = 0;
var prevBoundary:int = 0;
// If these are equal, then there are no more words.
while (wordBoundary != p.findNextWordBoundary(wordBoundary)) {
if (p.findNextWordBoundary(wordBoundary) - wordBoundary &gt; 1) {
wordCount += 1;
}
prevBoundary = wordBoundary;
wordBoundary = p.findNextWordBoundary(wordBoundary);
// If the value is greater than 1, then it's a word, otherwise it's a space.
if (wordBoundary - prevBoundary &gt; 1) {
var s:String = p.getText().substring(prevBoundary, wordBoundary);
lenTotal += s.length;
}
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:Panel&gt;
&lt;s:RichEditableText id="richTxt1" selectable="true" editable="true" textAlign="justify" percentWidth="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;&lt;s:span&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;Cras posuere posuere sem, eu congue orci mattis quis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;s:p&gt;&lt;s:span&gt;Curabitur pulvinar tellus venenatis ipsum tempus lobortis.&lt;/s:span&gt;&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Panel&gt;
&lt;s:VGroup&gt;
&lt;s:Button label="Count" click="countWords()"/&gt;
&lt;s:Label id="wcLabel"/&gt;
&lt;s:Label id="lenLabel"/&gt;
&lt;/s:VGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff4_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff4_verapache"><!-- --></a>
<h3 class="topictitle3">Adding images with TLF</h3>
<div>
<p>TLF supports embedding images in text controls by using
the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/InlineGraphicElement.html" target="_blank">InlineGraphicElement</a> class.
To add an image to the text object model, use the <samp class="codeph">&lt;img&gt;</samp> tag
in a <samp class="codeph">&lt;s:textFlow&gt;</samp> tag or the default property,
or create an instance of the InlineGraphicElement class.</p>
<p>The InlineGraphicElement class can point to an image file, such
as a GIF, JPG, or PNG file. </p>
<p>You specify the location of the image by using the <samp class="codeph">source</samp> property.
The location can be relative to the deployed location of the application
(for example, “images/butterfly.gif”) or it can be a full path to
the image (for example, “http://yourserver.com/images/butterfly.gif”).</p>
<div class="p">The following example loads a simple image from a local location:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleInlineGraphic.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="doSomething()"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flashx.textLayout.elements.*;
import flashx.textLayout.*;
[Bindable]
private var textFlow:TextFlow;
private var img:InlineGraphicElement;
private function doSomething():void {
textFlow = new TextFlow();
var p:ParagraphElement = new ParagraphElement();
img = new InlineGraphicElement();
img.source = "assets/butterfly.gif";
img.height = 100;
img.width = 100;
p.addChild(img);
textFlow.addChild(p);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:Panel title="Simple Inline Graphic Image"
width="90%" height="90%"
horizontalCenter="0" verticalCenter="0"&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"
textFlow="{textFlow}" /&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">As with text-based examples, you can use a variety of techniques
to load the image with an InlineGraphicElement object. The following
example uses child tags:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleInlineGraphicTags.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;s:Panel title="Simple Inline Graphic Image"
width="90%" height="90%"
horizontalCenter="0" verticalCenter="0"&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
&lt;s:img source="@Embed(source='../assets/butterfly.gif')" height="100" width="100"/&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">Rather than load the image at run time, you can also use an embedded
image for the InlineGraphicImage object’s source, as the following
example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleEmbed.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;
[Embed(source="../assets/butterfly.gif")]
[Bindable]
public var imgCls:Class;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
&lt;s:img id="myImage" source="{imgCls}" height="100" width="100"/&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The InlineGraphicElement class can also display a drawn element,
such as a Sprite or an FXG component. The following example loads
an FXG component into the InlineGraphicElement:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/FXGInlineGraphic.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"
xmlns:comps="comps.*"
creationComplete="doSomething()"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flashx.textLayout.elements.*;
import flashx.textLayout.*;
import comps.*;
[Bindable]
private var textFlow:TextFlow;
private var img:InlineGraphicElement;
private function doSomething():void {
textFlow = new TextFlow();
var p:ParagraphElement = new ParagraphElement();
img = new InlineGraphicElement();
img.source = new ArrowAbsolute();
img.height = 100;
img.width = 100;
p.addChild(img);
textFlow.addChild(p);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:Panel title="FXG Inline Graphic Image"
width="90%" height="90%"
horizontalCenter="0" verticalCenter="0"&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"
textFlow="{textFlow}" /&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The FXG component used in this example is as follows:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- textcontrols/comps/ArrowAbsolute.fxg --&gt;
&lt;fxg:Graphic xmlns:fxg="http://ns.adobe.com/fxg/2008" version="1"&gt;
&lt;!-- Use Use compact syntax with absolute coordinates. --&gt;
&lt;fxg:Path data="
M 20 0
C 50 0 50 35 20 35
L 15 35
L 15 45
L 0 32
L 15 19
L 15 29
L 20 29
C 44 29 44 6 20 6
"&gt;
&lt;!-- Define the border color of the arrow. --&gt;
&lt;fxg:stroke&gt;
&lt;fxg:SolidColorStroke color="#888888"/&gt;
&lt;/fxg:stroke&gt;
&lt;!-- Define the fill for the arrow. --&gt;
&lt;fxg:fill&gt;
&lt;fxg:LinearGradient rotation="90"&gt;
&lt;fxg:GradientEntry color="#000000" alpha="0.8"/&gt;
&lt;fxg:GradientEntry color="#FFFFFF" alpha="0.8"/&gt;
&lt;/fxg:LinearGradient&gt;
&lt;/fxg:fill&gt;
&lt;/fxg:Path&gt;
&lt;/fxg:Graphic&gt; </pre>
</div>
<p>For more information about using FXG, see <a href="flx_fxg_fx.html#WS145DAB0B-A958-423f-8A01-12B679BA0CC7_verapache">FXG
and MXML graphics</a>.</p>
<div class="p">If you do not know the image’s dimensions, you can use the InlineGraphicElement
class’s <samp class="codeph">measuredHeight</samp> and <samp class="codeph">measuredWidth</samp> properties
to define the size of the image. You can only use these properties
after the image loads. To do this, you can trigger a function that
sizes the image off of the TextFlow object’s <samp class="codeph">StatusChangeEvent</samp> event,
as the following example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/LoadImageEvent.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 flashx.textLayout.events.StatusChangeEvent;
import flashx.textLayout.elements.*;
import flashx.textLayout.*;
[Bindable]
private var textFlow:TextFlow;
private var img:InlineGraphicElement;
private function initApp():void {
textFlow = new TextFlow();
textFlow.addEventListener(StatusChangeEvent.INLINE_GRAPHIC_STATUS_CHANGE, sizeGraphic);
var p:ParagraphElement = new ParagraphElement();
img = new InlineGraphicElement();
img.source = "assets/butterfly.gif";
p.addChild(img);
textFlow.addChild(p);
}
private function sizeGraphic(e:StatusChangeEvent):void {
if (e.status == "ready" || e.status == "sizePending") {
img.height = img.measuredHeight;
img.width = img.measuredWidth;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:Panel title="Sizing Inline Graphic Image"
width="90%" height="90%"
horizontalCenter="0" verticalCenter="0"&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"
textFlow="{textFlow}" /&gt;
&lt;/s:Panel&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can get a reference to the InlineGraphicElement’s graphic
by using the <samp class="codeph">graphic</samp> property. This property points
to the embedded DisplayObject. This lets you interact with the InlineGraphicElement
in the same ways that you can interact with any DisplayObject. For
example, you can apply blend modes, change the alpha, rotate, and
scale the image.</p>
<div class="p">The following example changes the <samp class="codeph">alpha</samp> of the
DisplayObject when you move the slider:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/DisplayObjectImageElement.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;
private function changeAlpha():void {
myImage.graphic.alpha = .5;
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="richTxt" textAlign="justify" width="100%"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
&lt;s:img id="myImage"
source="@Embed(source='../assets/butterfly.gif')"
height="100" width="100"/&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;s:HSlider id="hSlider"
minimum="0" maximum="1"
value="1"
stepSize="0.1"
snapInterval="0.1"
liveDragging="true"
valueCommit="myImage.graphic.alpha=hSlider.value;"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>Note that the previous example uses a RichEditableText control
and not a RichText control. The RichEditableText control supports
user interaction, while the RichText control does not.</p>
</div>
<div class="nested3" id="WS19f279b149e7481c2028ff4112df207af8b-8000_verapache"><a name="WS19f279b149e7481c2028ff4112df207af8b-8000_verapache"><!-- --></a>
<h4 class="topictitle4">Positioning images inline</h4>
<div>
<div class="p">To position the InlineGraphicElement within a text element,
you use the following properties:<ul>
<li>
<p>
<samp class="codeph">float</samp> property
of the InlineGraphicElement class</p>
</li>
<li>
<p>
<samp class="codeph">clearFloats</samp> property of the FlowElement
(or the <samp class="codeph">clearFloats</samp> style property of the text
container)</p>
</li>
<li>
<p>
<samp class="codeph">paddingTop/paddingBottom/paddingLeft/paddingRight</samp> properties
on the FlowElement class</p>
</li>
</ul>
</div>
<div class="p">The <samp class="codeph">float</samp> property controls the placement of
the inline graphic within the text. The following example shows
a simple image surrounded by text. By changing the value of the <samp class="codeph">float</samp> property,
you can change the way text flows around the image, as the following
example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFFloat.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[
private function changeSelection(event:Event):void {
image1.float = event.currentTarget.selectedItem;
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:HGroup&gt;
&lt;s:Label text="float for the image (default:none):"/&gt;
&lt;s:ComboBox id="cb1"
change="changeSelection(event)"
creationComplete="cb1.selectedIndex=0"&gt;
&lt;s:ArrayCollection&gt;
&lt;fx:String&gt;none&lt;/fx:String&gt;
&lt;fx:String&gt;left&lt;/fx:String&gt;
&lt;fx:String&gt;right&lt;/fx:String&gt;
&lt;fx:String&gt;start&lt;/fx:String&gt;
&lt;fx:String&gt;end&lt;/fx:String&gt;
&lt;/s:ArrayCollection&gt;
&lt;/s:ComboBox&gt;
&lt;/s:HGroup&gt;
&lt;s:RichEditableText id="myRET1" width="300"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow columnWidth="290"&gt;
&lt;s:p id="p1"&gt;Images in a flow are a good thing. For example, here is a float. &lt;s:img id="image1" float="none" source="@Embed(source='../assets/bulldog.jpg')" paddingRight="10" paddingTop="10" paddingBottom="10" paddingLeft="10"&gt;&lt;/s:img&gt;Don't you agree?
It should show on the left. If it doesn't show up on the left, then it is a bug. You can submit bugs at http://bugs.adobe.com/jira/. You can set how the float is positioned within
the paragraph by using the ComboBox below. You can select left, right, start, end, or none. This example does not use the clearFloats property. That is in a different example.&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You use the constants defined by the flashx.textLayout.formats.Float
class to set the value of the <samp class="codeph">float</samp> property. The
values “left” and “right” indicate that the image should be left-aligned
or right-aligned within the text. The values of “start” and “end”
are similar, in that they left- and right-align the image, but the meanings
of them depend on the direction of the text (RTL or LTR). For RTL
text, for example, “end” means the end of the line, which is typically
the left side and “start” means the start of the line, which is
typically the right side. The value of “none” means that no text
should flow around the image. The default value is “none”.</p>
<div class="p">The <samp class="codeph">clearFloats</samp> property controls the placement
of the paragraph elements relative to the <samp class="codeph">float</samp>.
For example, if you want to ensure that a second paragraph after
a floating image starts below the image, you might set <samp class="codeph">clearFloats</samp> on
the second paragraph to “both” or “left”, as the following example
shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFClearFloats.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;s:HGroup&gt;
&lt;s:Label text="clearFloats for second paragraph (default:none):"/&gt;
&lt;s:ComboBox id="cb1"
change="p2.clearFloats = cb1.selectedItem"
creationComplete="cb1.selectedIndex=0"&gt;
&lt;s:ArrayCollection&gt;
&lt;fx:String&gt;none&lt;/fx:String&gt;
&lt;fx:String&gt;left&lt;/fx:String&gt;
&lt;fx:String&gt;right&lt;/fx:String&gt;
&lt;fx:String&gt;start&lt;/fx:String&gt;
&lt;fx:String&gt;end&lt;/fx:String&gt;
&lt;fx:String&gt;both&lt;/fx:String&gt;
&lt;/s:ArrayCollection&gt;
&lt;/s:ComboBox&gt;
&lt;/s:HGroup&gt;
&lt;s:RichEditableText id="myRET1" width="300" height="400"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow columnWidth="275"&gt;
&lt;s:p id="p0" fontWeight="bold"&gt;Heading 1&lt;/s:p&gt;
&lt;s:p id="p1"&gt;Images in a flow are a good thing. &lt;s:img id="image1" float="left" source="@Embed(source='../assets/bulldog.jpg')" paddingRight="10" paddingTop="10" paddingBottom="10" paddingLeft="10"&gt;&lt;/s:img&gt; You can use the ComboBox to change the clearFloats value on the second paragraph ("Heading 2"). This should ensure that Heading 2 starts on a new line after the image.&lt;/s:p&gt;
&lt;s:p id="p2" fontWeight="bold"&gt;Heading 2&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You use the constants defined by the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/ClearFloats.html" target="_blank">flashx.textLayout.formats.ClearFloats</a> class to
set the value of the <samp class="codeph">clearFloats</samp> property. The
values “left” and “right” indicate that the new paragraph should
be placed after any float that appears on the left or right. As
with the <samp class="codeph">float</samp> property, the “start” and “end”
values are dependent on the direction of the text in the paragraph.
A value of “both” causes text to appear after all floats. A value
of “none” lets the text appear next to the float. The default value
is “none”.</p>
<p>Note that you can also set the <samp class="codeph">clearFloats</samp> property
as a style on the TLF-based text controls such as RichEditableText
and Spark TextArea. This style property is inheritable, which means
that all child flow elements will inherit the value you set on the
control.</p>
<p>To further customize the location of images within text blocks,
you can apply the padding properties (<samp class="codeph">paddingTop</samp>, <samp class="codeph">paddingBottom</samp>, <samp class="codeph">paddingRight</samp>,
and <samp class="codeph">paddingLeft</samp>) to any FlowElement object, including
an InlineGraphicElement object such as an image. This lets you control
the offset of the image from the margin as well as the offset between
the image and the text that wraps around it. </p>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff3_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff3_verapache"><!-- --></a>
<h3 class="topictitle3">Adding hyperlinks with TLF</h3>
<div>
<p>TLF-based text controls support hyperlinks with the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/LinkElement.html" target="_blank">LinkElement</a> class.
To insert a hyperlink into the TextFlow, you use the <samp class="codeph">&lt;a&gt;</samp> tag
in a <samp class="codeph">&lt;s:textFlow&gt;</samp> tag or the default property,
or create an instance of the LinkElement class. </p>
<p>You can only use hyperlinks in a TextFlow object in the TextArea
and RichEditableText controls. The Spark Label, TextInput, and RichText
controls do not support hyperlinks.</p>
<div class="p">The default behavior of a LinkElement object in the text object
model is to launch a new browser window and navigate to the location
specified in the <samp class="codeph">href</samp> property of the LinkElement
object. The following example shows a basic navigation link:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimpleLinkElement.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;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
The following link takes you to: &lt;s:a href="http://www.adobe.com"&gt;Adobe.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;s:RichEditableText id="richTxt2"
editable="true"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
Hold CTRL key down when using the following link: &lt;s:a href="http://www.adobe.com"&gt;Adobe.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>To ensure that your links use the hand cursor when the user mouses
over them, set the <samp class="codeph">editable</samp> property to <samp class="codeph">false</samp> on
the RichEditableText object. If you do not, then your user must
hold the Control key down while moving the cursor over the link
to be able to click on that link.</p>
<p>The LinkElement is the only flow element that supports Flex events.
Supported events include <samp class="codeph">click</samp>, <samp class="codeph">mouseDown</samp>,
and <samp class="codeph">rollOut</samp>.</p>
<p>While the default behavior of the LinkElement object is to launch
a new browser window and open the specified link as a new page,
you can also define a custom event handler for the <samp class="codeph">click</samp> event.
The easiest way to do this is to exclude the <samp class="codeph">href</samp> attribute
from the anchor tag. </p>
<div class="p">The following example defines custom behavior for the <samp class="codeph">click</samp> event
of the LinkElement object. It does not specify a destination link
in the LinkElement, but instead builds one in the <samp class="codeph">click</samp> event
handler:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/CustomLinkElement.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 flashx.textLayout.events.FlowElementMouseEvent;
import mx.collections.ArrayCollection;
[Bindable]
public var myArray:ArrayCollection = new ArrayCollection(["Flex", "Flash", "ActionScript"]);
private function handleClickEvent(e:FlowElementMouseEvent):void {
var url:String = "http://www.google.com/search?q=" + productList.selectedItem;
navigateToURL(new URLRequest(url), '_blank');
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
Search for product info on &lt;s:a click="handleClickEvent(event)"&gt;Google&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;s:ComboBox id="productList" dataProvider="{myArray}" prompt="Select one"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can also suppress the click event in the event handler by
calling the <samp class="codeph">stopPropagation()</samp> and <samp class="codeph">preventDefault()</samp> methods
in the <samp class="codeph">click</samp> event’s handler. </p>
<p>The <samp class="codeph">stopPropagation()</samp> method prevents processing
of any event listeners in nodes subsequent to the current node in
the event flow. The <samp class="codeph">preventDefault()</samp> method cancels
the event’s default behavior.</p>
<div class="p">You can then access properties of the LinkElement object to carry
out additional actions. The following example presents the user
with an option of navigating to the target location or cancelling
the action:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/CustomLinkElementHandling.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;
import flashx.textLayout.events.FlowElementMouseEvent;
import flashx.textLayout.elements.LinkElement;
import mx.controls.Alert;
import mx.events.CloseEvent;
private var linkTarget:String;
private function doSomething(e:FlowElementMouseEvent):void {
e.stopImmediatePropagation();
e.preventDefault();
var le:LinkElement = e.flowElement as LinkElement;
linkTarget = le.href;
Alert.show("You are about to navigate away from this page.","Alert",Alert.OK | Alert.CANCEL, this, alertListener, null, Alert.OK);
}
private function alertListener(e:CloseEvent):void {
if (e.detail == Alert.OK) {
navigateToURL(new URLRequest(linkTarget), '_self')
}
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
The following link takes you to: &lt;s:a href="http://www.adobe.com" target="_blank" click="doSomething(event)"&gt;Adobe.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The default styling for a LinkElement is underlined, blue text.
To style the links in TLF, you can use a SpanElement object and
set style properties on that. The following example removes the
underline, and makes the link color red rather than blue:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/StyledLinkElement.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;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
The following link takes you to: &lt;s:a href="http://www.adobe.com"&gt;&lt;s:span color="0xFF0066" textDecoration="none"&gt;Adobe.com&lt;/s:span&gt;&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can also use the TextLayoutFormat class to style hyperlinks.
For more information, see <a href="flx_sparktextcontrols_stc.html#WS02f7d8d4857b1677-165a04e1126951a2d98-7ff0_verapache">Applying
styles with the TextLayoutFormat class</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff2_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff2_verapache"><!-- --></a>
<h3 class="topictitle3">Styling TLF-based text controls</h3>
<div>
<p>The Spark text controls TextInput, TextArea, Label, RichText,
and RichEditableText support specifying default text formatting
with CSS styles. The complete set of styles supports all of TLF’s
formatting capabilities, including kerning and bidirectionality.</p>
<p>The names and descriptions of the styles supported by the TLF
text controls are the described in the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/TextLayoutFormat.html" target="_blank">TextLayoutFormat</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/edit/SelectionFormat.html" target="_blank">SelectionFormat</a> classes.</p>
<div class="p">The default values for these styles is defined by the <samp class="codeph">global</samp> selector
in the defaults.css file. This file is compiled into the framework.swc
file. To change the values of the defaults, you can create your
own global selector; for example:<pre class="codeblock">&lt;fx:Styles&gt;
global {
fontFamily: "Verdana"
}
&lt;/fx:Style&gt;</pre>
</div>
<p>TLF’s FlowElement tags such as <samp class="codeph">&lt;p&gt;</samp> and <samp class="codeph">&lt;span&gt;</samp>,
which are supported in the content of the RichText or RichEditableText
controls, support formatting only with properties, not using CSS.
As a result, to set styles on individual flow elements, you must
set them as you would set a style property, but not in CSS. </p>
<div class="p">The following example shows setting style properties on the paragraphs.
It shows you that you can set the style properties either with the <samp class="codeph">setStyle()</samp> method
or as a property assignment.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFStylesProperties.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;
import flashx.textLayout.elements.*;
private function initApp():void {
// You cannot set these properties in CSS.
// Set color of first paragraph to red with the setStyle() method.
myRET.textFlow.getChildAt(0).setStyle("color", 0xFF0000);
// Set color of second paragraph to green with a property assignment.
myRET.textFlow.getChildAt(1).color = 0x00FF00;
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="myRET" height="100" width="200"&gt;
&lt;s:p id="p1"&gt;This is paragraph 1.&lt;/s:p&gt;
&lt;s:p id="p2"&gt;This is paragraph 2.&lt;/s:p&gt;
&lt;/s:RichEditableText&gt;
&lt;s:Button click="initApp()" label="Apply Styles"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The RichText and RichEditableText controls support additional
style properties that Label does not. These properties include properties
related to columns and paragraphs, including <samp class="codeph">columnCount</samp>, <samp class="codeph">columnGap</samp>, <samp class="codeph">paragraphSpaceAfter</samp>, <samp class="codeph">paragraphStartIndent</samp>,
and <samp class="codeph">whiteSpaceCollapse</samp>.</p>
<p>The RichEditableText control supports style properties that are
not supported by the Label and RichText controls. These properties
include <samp class="codeph">selectionColor</samp>, <samp class="codeph">inactiveSelectionColor</samp>,
and <samp class="codeph">unfocusedSelectionColor</samp>. </p>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff1_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff1_verapache"><!-- --></a>
<h4 class="topictitle4">Style inheritance</h4>
<div>
<p>Some styles are inheriting, meaning that if you set them
on a container they affect the children of that container. Generally,
the choice of whether a CSS style is inheriting or non-inheriting
is made based on whether the corresponding TLF format inherits from
the parent FlowElement to the child FlowElement.</p>
<div class="p">The following example shows an inheriting style and a non-inheriting
style set on the Button control. The inheriting style, <samp class="codeph">color</samp>,
is applied to the text, but the non-inheriting style, <samp class="codeph">backgroundColor</samp>,
is not.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFStyles.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|Button {
color: red;
backgroundColor: #33CC99;
}
&lt;/fx:Style&gt;
&lt;s:Button label="Click Me"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>Because a skinnable component is a type of Spark container, inheriting
styles are inherited by children of the container. If you set an
inheriting style such as <samp class="codeph">fontSize</samp> on a Spark Button,
for example, the style is applied to the Label class that renders
the Button’s label. The Label control is defined in the ButtonSkin class.
The parts that make up a larger component are known as subcomponents. If
you set a non-inheriting style such as <samp class="codeph">backgroundColor</samp> it
will not affect the Label subcomponent of a Button; instead you
can create a custom type selector for Label, or you can reskin the
Button and set the value of the <samp class="codeph">backgroundColor</samp> property
directly on the Label. </p>
<div class="p">To set the value of a non-inheriting style property on the Button’s
label, you can set the value of the <samp class="codeph">backgroundColor</samp> property
in a Label type selector. The following example sets the <samp class="codeph">backgroundColor</samp> style
to #33CC99 for the Label type, which affects the way the Button
control’s label is rendered because the Label class is a subcomponent
of Button:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFStylesSubComps.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|Button {
color: red;
}
s|Label {
backgroundColor: #33CC99;
}
&lt;/fx:Style&gt;
&lt;s:Button label="Click Me"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>For the TextArea and TextInput controls, the text is rendered
by a RichEditableText subcomponent. You can access the RichEditableText
subcomponent by casting the result of the <samp class="codeph">textDisplay</samp> property
to a type that supports the <samp class="codeph">setStyle()</samp> method.
You can then call the <samp class="codeph">setStyle()</samp> method on this object,
which applies non-inheritable style properties to the subcomponent. </p>
<p>Note that this technique does not work for mobile versions of
the TextArea and TextInput controls because the mobile skins do
not include support for the RichEditableText subcomponent. </p>
<div class="p">The following example illustrates the difference between correctly
and incorrectly applying a non-inheriting style property to a pair
of TextArea controls:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextAreaStyling.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="doSomething()"&gt;
&lt;fx:Script&gt;
import spark.components.RichEditableText;
private function doSomething():void {
/* To set a non-inheritable style on a TextArea, you must actually
apply it to the underlying RichEditableText subcomponent, which is
accessed through the textDisplay property: */
RichEditableText(text1.textDisplay).setStyle("columnCount", 2);
/* Setting a non-inheritable style directly on the TextArea does
not apply the style properly. */
text2.setStyle("columnCount", 2);
}
&lt;/fx:Script&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;s:TextArea id="text1" width="200" height="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;This is TextArea #1. This is enough text to ensure that there will be more than one column if the columnCount property is properly applied.&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:TextArea&gt;
&lt;s:TextArea id="text2" width="200" height="100"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;This is TextArea #2. This is enough text to ensure that there will be more than one column if the columnCount property is properly applied.&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:TextArea&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">You can also change the number of columns in a TextFlow object
by setting the <samp class="codeph">columnCount</samp> property on the <samp class="codeph">&lt;s:TextFlow&gt;</samp> tag,
as the following example shows:<pre class="codeblock">&lt;s:TextFlow columnCount="2"&gt;</pre>
</div>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff0_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7ff0_verapache"><!-- --></a>
<h4 class="topictitle4">Applying styles with the TextLayoutFormat
class</h4>
<div>
<p>To style TLF-based text controls, you can also use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/TextLayoutFormat.html" target="_blank">TextLayoutFormat</a> class.
You begin by creating an instance of the TextLayoutFormat class.
You can then set any formatting properties on that object, including
paragraph indentation, leading, justification, and typographic case.
Finally, you specify the custom TextLayoutFormat with the TextFlow
object’s <samp class="codeph">hostFormat</samp> property.</p>
<div class="p">The following example sets various styles on the text:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TextLayoutFormatExample.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;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Script&gt;
import flashx.textLayout.formats.*;
private function initApp():void {
var textLayoutFormat:TextLayoutFormat = new TextLayoutFormat();
textLayoutFormat.color = 0x336633;
textLayoutFormat.fontFamily = "Arial, Helvetica, _sans";
textLayoutFormat.fontSize = 14;
textLayoutFormat.paragraphSpaceBefore = 15;
textLayoutFormat.paragraphSpaceAfter = 15;
textLayoutFormat.typographicCase = TLFTypographicCase.LOWERCASE_TO_SMALL_CAPS;
textFlow.hostFormat = textLayoutFormat;
}
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow id="textFlow"&gt;
&lt;s:p&gt;
The following link takes you to &lt;s:a href="http://www.adobe.com"&gt;Adobe.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;s:p&gt;
The following link takes you to &lt;s:a href="http://www.omniture.com"&gt;Omniture.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">You can define a TextLayoutFormat object inline, rather than
in ActionScript. The following example defines TextLayoutFormat
objects that style the hyperlink, based on its state:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/StyledLinkElement2.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;s:RichEditableText id="richTxt"
editable="false"
focusEnabled="false"&gt;
&lt;s:textFlow&gt;
&lt;s:TextFlow&gt;
&lt;s:p&gt;
&lt;s:linkHoverFormat&gt;
&lt;s:TextLayoutFormat color="#33CC00" textDecoration="underline"/&gt;
&lt;/s:linkHoverFormat&gt;
&lt;s:linkNormalFormat&gt;
&lt;s:TextLayoutFormat color="#009900"/&gt;
&lt;/s:linkNormalFormat&gt;
&lt;s:a href="http://www.adobe.com"&gt;Adobe.com&lt;/s:a&gt;
&lt;/s:p&gt;
&lt;/s:TextFlow&gt;
&lt;/s:textFlow&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested3" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fef_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fef_verapache"><!-- --></a>
<h4 class="topictitle4">Applying styles with the Configuration
class</h4>
<div>
<p>Another approach to styling TLF is to use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/Configuration.html" target="_blank">Configuration</a> class.
This class provides access to some properties of text, such as its
state. For example, you can use this class to define the appearance
of a hyperlink when it is active or when it is hovered over. You
can also use this class to define the appearance of text when it
is selected.</p>
<p>To use a Configuration object with TLF, you define the styles
on the TextLayoutFormat or SelectionFormat objects and assign them
to the Configuration object’s format properties. </p>
<div class="p">The format properties include the following:<ul>
<li>
<p>
<samp class="codeph">defaultLinkActiveFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">defaultLinkHoverFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">defaultLinkNormalFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">focusedSelectionFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">inactiveSelectionFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">textFlowInitialFormat</samp>
</p>
</li>
<li>
<p>
<samp class="codeph">unfocusedSelectionFormat</samp>
</p>
</li>
</ul>
</div>
<div class="p">The following example defines the appearance of the hyperlink
by using custom TextLayoutFormat objects attached to a Configuration
object:<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparktextcontrols/StylingWithConfig.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
creationComplete="initApp()"&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
import flashx.textLayout.conversion.TextConverter;
import flashx.textLayout.elements.Configuration;
import flashx.textLayout.elements.IConfiguration;
import flashx.textLayout.formats.ITextLayoutFormat;
import flashx.textLayout.formats.TextDecoration;
import flashx.textLayout.formats.TextLayoutFormat;
private function initApp():void {
var txt:String = "Check out our website at &lt;a href='http://www.adobe.com/'&gt;adobe.com&lt;/a&gt;.";
var cfg:Configuration = new Configuration(true);
var normalFmt:TextLayoutFormat = new TextLayoutFormat(cfg.defaultLinkNormalFormat);
normalFmt.color = 0xFF0000; // red
normalFmt.textDecoration = TextDecoration.NONE;
var hoverFmt:TextLayoutFormat = new TextLayoutFormat(cfg.defaultLinkHoverFormat);
hoverFmt.color = 0xFF00FF; // purple
hoverFmt.textDecoration = TextDecoration.UNDERLINE;
cfg.defaultLinkNormalFormat = normalFmt;
cfg.defaultLinkHoverFormat = hoverFmt;
rt.textFlow = TextConverter.importToFlow(txt, TextConverter.TEXT_FIELD_HTML_FORMAT, cfg);
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:RichEditableText id="rt" x="20" y="20" editable="false"/&gt;
&lt;/s:Application&gt; </pre>
</div>
</div>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fee_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fee_verapache"><!-- --></a>
<h3 class="topictitle3">Skinning TLF-based text controls</h3>
<div>
<p>You do not typically add skins or chrome to the Spark text
controls. </p>
<p>The Label, RichText, and RichEditableText Spark text controls
are used in the skins of skinnable components. Because each has
a different set of features, you can use the lightest weight text
control that meets your needs.</p>
<p>For example, the default skin of a Spark Button uses the Label
class to render the label of the Button. If you have a Button that
requires rich text, you can sometimes replace the Label control
in its skin with a RichText control. </p>
<p>The default skins of the Spark TextInput and TextArea controls
use a RichEditableText control to provide an area in which text
can be edited. The border and background are provided by a Rect
class, and the scrollbars by a Scroller class.</p>
<p>For more information on skinning Spark controls, see <a href="flx_gumboskinning_gs.html#WS53116913-F952-4b21-831F-9DE85B647C8A_verapache">Spark
Skinning</a>.</p>
</div>
</div>
<div class="nested2" id="WS02f7d8d4857b1677-165a04e1126951a2d98-7fed_verapache"><a name="WS02f7d8d4857b1677-165a04e1126951a2d98-7fed_verapache"><!-- --></a>
<h3 class="topictitle3">Mirroring and bidirectional text</h3>
<div>
<p>Some languages, such as Hebrew and Arabic, read from right
to left. However, those languages often include text from other
languages that read from left to right. Most of a sentence in Hebrew,
for example, might read from right to left, but it might include
English words that are read from left to right. This makes it necessary
for Flex controls to support bidirectional text. </p>
<p>To use bidirectional text in a TLF text-based control, use the <samp class="codeph">direction</samp> style. </p>
<p>Bidirectional text lets you render text from left-to-right (LTR)
or right-to-left (RTL). You can embed RTL text inside an LTR block
so that portions of a paragraph render LTR and portions render RTL.
There is a dominant direction for the entire paragraph, but parts
of the paragraph can be read in the opposite direction, and this
can be nested.</p>
<div class="p">The following simple example embeds a small amount of Hebrew
text in a text control, and sets the <samp class="codeph">direction</samp> style
to <samp class="codeph">rtl</samp>. The text is written and stored using the
UTF-8 encoding.<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparktextcontrols/RTLHebrewExample.mxml --&gt;
&lt;s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx"&gt;
&lt;s:layout&gt;&lt;s:VerticalLayout/&gt;&lt;/s:layout&gt;
&lt;s:Graphic&gt;
&lt;s:Label direction="rtl" text="???? ??????? ????? ????? ?????? This is a Hebrew test" width="100" height="100"/&gt;
&lt;/s:Graphic&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The following example includes English and two examples of RTL
text (Hebrew and Arabic). The text is defined as Unicode characters,
which makes it easier to follow. You can click the button to toggle
the RichEditableText control from RTL to LTR.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/RTLTest.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="addText()"&gt;
&lt;s:layout&gt;
&lt;s:VerticalLayout/&gt;
&lt;/s:layout&gt;
&lt;fx:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
@font-face {
src:url("../assets/MyriadWebPro.ttf");
fontFamily: myFontFamily;
advancedAntiAliasing: true;
embedAsCFF: true;
unicodeRange:
U+0041-005A, /* Latin upper-case [A..Z] */
U+0061-007A, /* Latin lower-case a-z */
U+002E-002E, /* Latin period [.] */
U+05E1, /* The necessary Hebrew letters */
U+05B5,
U+05E4,
U+05B6,
U+05E8,
U+0645, /* The necessary Arabic letters */
U+062F,
U+0631,
U+0633,
U+0629;
}
s|RichText {
fontFamily: myFontFamily;
fontSize: 32;
paddingTop: 10;
}
&lt;/fx:Style&gt;
&lt;fx:Script&gt;
import flashx.textLayout.formats.*;
import spark.utils.TextFlowUtil;
private function addText():void {
myRT.textFlow = TextFlowUtil.importFromString("school is written " +
String.fromCharCode(0x0645, 0x062f, 0x0631, 0x0633, 0x0629) +
" in Arabic and " + String.fromCharCode(0x05E1, 0x05B5, 0x05E4, 0x05B6, 0x05E8) +
" in Hebrew.");
}
private function mirrorText():void {
if (myRT.getStyle("direction")=="ltr") {
myRT.setStyle("direction", flashx.textLayout.formats.Direction.RTL);
} else {
myRT.setStyle("direction", flashx.textLayout.formats.Direction.LTR);
}
}
&lt;/fx:Script&gt;
&lt;s:Panel title="RTL and LTR with embedded font"&gt;
&lt;s:RichText id="myRT" width="400" height="150"/&gt;
&lt;/s:Panel&gt;
&lt;s:Button click="mirrorText()" label="Toggle Direction"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>Mirroring refers to laying the chrome of a component, or an entire
application, out in one direction and then display in the opposite
direction. For example, a mirrored TextArea would have its vertical
scrollbar on the left. A mirrored Tree would have its disclosure
triangles on the right. A mirrored HGroup would have its first child
on the right, and a mirrored TabBar would have its first tab on
the right. Mirroring can apply to subcomponents as well as chrome.
For example, a mirrored RadioButton would have its label on the
left side instead of the right side (the default).</p>
<p>Mirroring of components complement bidirectional text by having
the application and components reflect the text direction.</p>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481c7fdc883d12de39353f1-8000_verapache"><a name="WS19f279b149e7481c7fdc883d12de39353f1-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Using numbered and bulleted lists
with TLF-based text controls</h3>
<div>
<p>You can use the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/ListElement.html" target="_blank">ListElement</a> and <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/elements/ListItemElement.html" target="_blank">ListItemElement</a> classes
to add bulleted lists to your text controls. The bulleted lists
can be nested and can be customized to use different bullets (or
markers) and auto-numbering.</p>
<p>To create lists in your applications, use the <samp class="codeph">&lt;s:list&gt;</samp> tag
inside a text control that uses TLF. You then use<samp class="codeph"> &lt;s:li&gt;</samp> tags
within the <samp class="codeph">&lt;s:list&gt;</samp> tag for each list item
in the list. You can customize the appearance of the bullets by
using the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/ListMarkerFormat.html" target="_blank">ListMarkerFormat</a> class.</p>
<div class="p">The following example creates simple lists:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFLists.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;!-- Simple bulleted list. --&gt;
&lt;s:RichEditableText id="myRET1" width="200"&gt;
&lt;s:p&gt;Simple bulleted list:&lt;/s:p&gt;
&lt;s:list id="list1" listStylePosition="outside"&gt;
&lt;s:li&gt;Item 1&lt;/s:li&gt;
&lt;s:li&gt;Item 2&lt;/s:li&gt;
&lt;s:li&gt;Item 3&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;!-- Nested bulleted list. --&gt;
&lt;s:RichEditableText id="myRET2" width="200"&gt;
&lt;s:p&gt;Nested bulleted list:&lt;/s:p&gt;
&lt;s:list id="list2"&gt;
&lt;s:li&gt;Dry cleaning&lt;/s:li&gt;
&lt;s:li&gt;Groceries
&lt;s:list id="list1a"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;s:li&gt;Stick of butter&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:li&gt;
&lt;s:li&gt;Oil change
&lt;s:list id="list1b"&gt;
&lt;s:li&gt;Item 1b&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;!-- Custom spacing list. --&gt;
&lt;s:RichEditableText id="myRET3" width="200"&gt;
&lt;s:p&gt;List with custom indents:&lt;/s:p&gt;
&lt;s:list id="list3" paddingLeft="20"&gt;
&lt;s:li&gt;Dry cleaning&lt;/s:li&gt;
&lt;s:li&gt;Groceries
&lt;s:list id="list31" paddingLeft="20"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;s:li&gt;Stick of butter&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:li&gt;
&lt;s:li&gt;Item 3&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;!-- Custom styled list. --&gt;
&lt;s:RichEditableText id="myRET4" width="200"&gt;
&lt;s:p&gt;Styled bulleted list:&lt;/s:p&gt;
&lt;s:list id="list4" listStylePosition="inside"&gt;
&lt;s:listMarkerFormat&gt;
&lt;s:ListMarkerFormat fontSize="14" fontWeight="bold" color="0xFF0066" afterContent=" "/&gt;
&lt;/s:listMarkerFormat&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;s:li&gt;Stick of butter&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">To change the type of marker or use numbering in the list, use
the <samp class="codeph">listStyleType</samp> property of the ListElement.
This property can be any value defined by the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/ListStyleType.html" target="_blank">ListStyleType</a> class
(such as <samp class="codeph">check</samp>, <samp class="codeph">circle</samp>, <samp class="codeph">decimal</samp>,
and <samp class="codeph">box</samp>). The following example creates lists with
various marker types and a custom increment:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFListsCustomBullets.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;!-- Custom bullets lists. --&gt;
&lt;s:RichEditableText id="myRET1" width="200"&gt;
&lt;s:p&gt;Lists with custom bullets:&lt;/s:p&gt;
&lt;s:p&gt;Box:&lt;/s:p&gt;
&lt;s:list id="list1" listStyleType="box"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;s:p&gt;Decimal:&lt;/s:p&gt;
&lt;s:list id="list2" listStyleType="decimal"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;s:p&gt;Check:&lt;/s:p&gt;
&lt;s:list id="list3" listStyleType="check"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;s:p&gt;Nested Roman:&lt;/s:p&gt;
&lt;s:list id="list4" listStyleType="upperRoman"&gt;
&lt;s:li&gt;Item 1
&lt;s:list id="list41" listStyleType="lowerRoman"&gt;
&lt;s:li&gt;Quart of milk&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:li&gt;
&lt;s:li&gt;Item 2&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;!-- List with custom increment. --&gt;
&lt;s:RichEditableText id="myRET2" width="200"&gt;
&lt;s:p&gt;List with countdown:&lt;/s:p&gt;
&lt;s:list id="list5" listStyleType="decimal"&gt;
&lt;s:listMarkerFormat&gt;
&lt;!-- Increments the list by 2s rather than 1s. --&gt;
&lt;s:ListMarkerFormat counterIncrement="ordered 2"/&gt;
&lt;/s:listMarkerFormat&gt;
&lt;s:li&gt;Quart of milk
&lt;s:listMarkerFormat&gt;
&lt;!-- Causes counter to start at 10. --&gt;
&lt;s:ListMarkerFormat counterReset="ordered 9"/&gt;
&lt;/s:listMarkerFormat&gt;
&lt;/s:li&gt;
&lt;s:li&gt;Loaf of bread&lt;/s:li&gt;
&lt;s:li&gt;Stick of butter&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>You can further customize the appearance of the markers in your
lists by using the <a href="http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flashx/textLayout/formats/ListMarkerFormat.html" target="_blank">ListMarkerFormat</a> class
to define “before” and “after” content. This is content that appears
before and after the content of the marker.</p>
<div class="p">The following example adds the word “Chapter” before the marker,
and a colon after the marker. The marker, or content, is ordered
upper-case Roman numerals.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/TLFListsBeforeAfter.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;!-- Before/After content. --&gt;
&lt;s:RichEditableText id="myRET" width="500"&gt;
&lt;s:p&gt;List with Before/After content:&lt;/s:p&gt;
&lt;s:list id="myList" paddingLeft="10" listStylePosition="inside"&gt;
&lt;s:listMarkerFormat&gt;
&lt;!-- Note that this example inserts an empty string with &amp;quote; HTML entities. --&gt;
&lt;s:ListMarkerFormat
beforeContent="Chapter "
content="counters(ordered,&amp;quot;&amp;quot;,upperRoman)"
afterContent=": "/&gt;
&lt;/s:listMarkerFormat&gt;
&lt;s:li&gt;Beginning&lt;/s:li&gt;
&lt;s:li&gt;Middle&lt;/s:li&gt;
&lt;s:li&gt;End&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;s:list id="myList2" paddingLeft="10" listStylePosition="inside"&gt;
&lt;s:listMarkerFormat&gt;
&lt;s:ListMarkerFormat
beforeContent="*BEFORE*"
content="counters(ordered,&amp;quot;*SUFFIX*&amp;quot;,upperRoman)"
afterContent="*AFTER*"/&gt;
&lt;/s:listMarkerFormat&gt;
&lt;s:li&gt;Beginning&lt;/s:li&gt;
&lt;s:li&gt;Middle&lt;/s:li&gt;
&lt;s:li&gt;End&lt;/s:li&gt;
&lt;/s:list&gt;
&lt;/s:RichEditableText&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>As the previous example shows, you can use the <samp class="codeph">content</samp> property
to insert a suffix: a string that appears after the marker, but
before the <samp class="codeph">afterContent</samp>. To insert this string
when providing XML content to the flow, wrap the string in <samp class="codeph">&amp;quote;</samp> HTML
entities rather than quotation marks (<samp class="codeph">“&lt;<em>string</em>&gt;”</samp>).
The previous example inserted an empty string.</p>
</div>
</div>
</div>
<div class="nested1" id="WS19f279b149e7481c-177b1c712d80a315e7-8000_verapache"><a name="WS19f279b149e7481c-177b1c712d80a315e7-8000_verapache"><!-- --></a>
<h2 class="topictitle2">Using prompts with text controls</h2>
<div>
<p>The Spark TextInput and TextArea controls support a <samp class="codeph">prompt</samp> property
that lets you specify text that helps users know what to enter.
For example, an input field might include prompt text that says
“Search”.</p>
<p>Prompt text appears when the text control is first created. Prompt
text disappears when the control gets focus or when the control’s <samp class="codeph">text</samp> property
is non-null. Prompt text reappears when the control loses focus,
but only if no text was entered (if the value of the text field
is the empty string). </p>
<p>For text controls, if the user enters text, but later deletes
it, the prompt text reappears when the control loses focus. You
can also cause the prompt text to reappear programmatically by setting
the text control’s text property to <samp class="codeph">null</samp> or the
empty string.</p>
<div class="p">The following example creates a TextInput and TextArea control
with prompt text. You can focus on the text controls and enter text,
which causes the prompt text to disappear. If you click the Reset
button, the prompt text reappears.<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/BasicPromptExample.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[
/* If you reset the text properties of the TextInput and TextArea controls to null
or the empty string, the prompt text reappears. */
private function resetPrompts():void {
myTextInput.text = "";
myTextArea.text = "";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextInput id="myTextInput" prompt="Enter name..."/&gt;
&lt;s:TextArea id="myTextArea" prompt="Enter details..."/&gt;
&lt;s:Button label="Reset" click="resetPrompts()"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>The Spark ComboBox control also supports the <samp class="codeph">prompt</samp> property
because it uses the Spark TextInput control as a subcontrol. For
more information, see <a href="flx_spark_dpcontrols_sdp.html#WS19f279b149e7481c3ae73812d80da7397-8000_verapache">Use prompt
text with the Spark ComboBox control</a>.</p>
</div>
<div class="nested2" id="WS19f279b149e7481ccb9899c12d861ca08a-8000_verapache"><a name="WS19f279b149e7481ccb9899c12d861ca08a-8000_verapache"><!-- --></a>
<h3 class="topictitle3">Text prompt styles</h3>
<div>
<p>The default prompt styles are defined in the current theme’s
default style sheet. By default, the prompt text is gray and italicised.
The style of the prompt text is defined by the text control’s pseudo
selectors. </p>
<p>Pseudo selectors let you apply styles to a component based on
its current state. For example, if your TextInput control has prompt
text and is not disabled, the style is defined by the <samp class="codeph">normalWithPrompt</samp> pseudo
selector because it is in the <samp class="codeph">normalWithPrompt</samp> state.
If the control is disabled, then the styles defined by the <samp class="codeph">disabledWithPrompt</samp> pseudo
selector are used.</p>
<div class="p">You can change the prompt text styles by overriding the default
CSS. The following example changes the prompt text styles by defining
different behavior for the <samp class="codeph">normalWithPrompt</samp> and <samp class="codeph">disabledWithPrompt</samp> pseudo
selectors for the TextInput and TextArea controls:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/StylingPrompts.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|TextInput:normalWithPrompt {
color: #CCCCFF;
fontStyle: italic;
}
s|TextArea:normalWithPrompt {
color: #CCCCFF;
fontStyle: italic;
}
s|TextInput:disabledWithPrompt {
color: #CCFFFF;
fontStyle: italic;
}
s|TextArea:disabledWithPrompt {
color: #CCFFFF;
fontStyle: italic;
}
&lt;/fx:Style&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function resetPrompts():void {
myTextInput.text = "";
myTextArea.text = "";
}
/* Disabling the controls causes the disabledWithPrompt pseudo selector to be used
instead of the normalWithPrompt pseudo selector. */
private function disableControls():void {
if (myTextInput.enabled) {
myTextInput.enabled = false;
myTextArea.enabled = false;
} else {
myTextInput.enabled = true;
myTextArea.enabled = true;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextInput id="myTextInput" prompt="Enter name..."/&gt;
&lt;s:TextArea id="myTextArea" prompt="Enter details..."/&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Reset" click="resetPrompts()"/&gt;
&lt;s:Button label="Toggle Enabled/Disabled" click="disableControls()"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
<p>In general, you should avoid setting the prompt text to be larger
or smaller than the regular text in the text control. Unless you
explicitly define the height and width of the control, the text
control’s size will grow or shrink as the size of the text or prompt
text grows and shrinks.</p>
<div class="p">To simplify your CSS you can also define text prompt styles on
the SkinnableTextBase type selector. Styles set on this selector
will apply to the TextArea and TextInput controls, as the following
example shows:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/SimplerStylingPrompts.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:Style&gt;
@namespace s "library://ns.adobe.com/flex/spark";
s|SkinnableTextBase:normalWithPrompt {
color: #CCCCFF;
fontStyle: italic;
}
s|SkinnableTextBase:disabledWithPrompt {
color: #CCFFFF;
fontStyle: italic;
}
&lt;/fx:Style&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private function resetPrompts():void {
myTextInput.text = "";
myTextArea.text = "";
}
/* Disabling the controls causes the disabledWithPrompt pseudo selector to be used
instead of the normalWithPrompt pseudo selector. */
private function disableControls():void {
if (myTextInput.enabled) {
myTextInput.enabled = false;
myTextArea.enabled = false;
} else {
myTextInput.enabled = true;
myTextArea.enabled = true;
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextInput id="myTextInput" prompt="Enter name..."/&gt;
&lt;s:TextArea id="myTextArea" prompt="Enter details..."/&gt;
&lt;s:HGroup&gt;
&lt;s:Button label="Reset" click="resetPrompts()"/&gt;
&lt;s:Button label="Toggle Enabled/Disabled" click="disableControls()"/&gt;
&lt;/s:HGroup&gt;
&lt;/s:Application&gt;</pre>
</div>
</div>
</div>
<div class="nested2" id="WS19f279b149e7481ccb9899c12d861ca08a-7fff_verapache"><a name="WS19f279b149e7481ccb9899c12d861ca08a-7fff_verapache"><!-- --></a>
<h3 class="topictitle3">Text prompt skins and transitions</h3>
<div>
<p>The prompt text of the TextArea and TextInput controls
is implemented as a Label control on the skins. The prompt text
is defined in the skin as a skin part named <samp class="codeph">promptDisplay</samp>.
You can change the behavior and appearance of the prompt text by
creating custom skins for those controls.</p>
<p>Typically, you copy the text control’s skin class (for example,
the TextInputSkin class) and customize it. You then apply the new
skin class by pointing the <samp class="codeph">skinClass</samp> property on
the text control to your new skin.</p>
<div class="p">The following example uses a custom skin called CustomTextInputSkin:<pre class="codeblock">&lt;?xml version="1.0"?&gt;
&lt;!-- sparktextcontrols/CustomPromptExample.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[
private function resetPrompts():void {
myTextInput.text = "";
}
]]&gt;
&lt;/fx:Script&gt;
&lt;s:TextInput id="myTextInput" prompt="Enter name..."
skinClass="mySkins.CustomTextInputSkin"/&gt;
&lt;s:Button label="Reset" click="resetPrompts()"/&gt;
&lt;/s:Application&gt;</pre>
</div>
<div class="p">The following custom skin adds a transition to the prompt text
when the state changes to <samp class="codeph">normalWithPrompt</samp>. Most
of the skin is directly copied from the original TextInputSkin class.
The only new code is the <samp class="codeph">&lt;s:transitions&gt;</samp> block
near the bottom of the example. When you enter some text, and then
click the Reset button, you should notice that the prompt text fades
in.<pre class="codeblock">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- sparktextcontrols\mySkins\CustomTextInputSkin.mxml --&gt;
&lt;s:SparkSkin xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:fb="http://ns.adobe.com/flashbuilder/2009"
alpha.disabledStates="0.5" blendMode="normal"&gt;
&lt;fx:Metadata&gt;
&lt;![CDATA[
[HostComponent("spark.components.TextInput")]
]]&gt;
&lt;/fx:Metadata&gt;
&lt;fx:Script fb:purpose="styling"&gt;
&lt;![CDATA[
import mx.core.FlexVersion;
private var paddingChanged:Boolean;
static private const exclusions:Array = ["background", "textDisplay", "promptDisplay", "border"];
static private const exclusions_4_0:Array = ["background", "textDisplay", "promptDisplay"];
override public function get colorizeExclusions():Array {
if (FlexVersion.compatibilityVersion &lt; FlexVersion.VERSION_4_5) {
return exclusions_4_0;
}
return exclusions;
}
static private const contentFill:Array = ["bgFill"];
override public function get contentItems():Array {return contentFill};
override protected function commitProperties():void {
super.commitProperties();
if (paddingChanged) {
updatePadding();
paddingChanged = false;
}
}
override protected function initializationComplete():void {
useChromeColor = true;
super.initializationComplete();
}
override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void {
if (getStyle("borderVisible") == true) {
border.visible = true;
shadow.visible = true;
background.left = background.top = background.right = background.bottom = 1;
textDisplay.left = textDisplay.top = textDisplay.right = textDisplay.bottom = 1;
if (promptDisplay)
{
promptDisplay.setLayoutBoundsSize(unscaledWidth - 2, unscaledHeight - 2);
promptDisplay.setLayoutBoundsPosition(1, 1);
}
}
else
{
border.visible = false;
shadow.visible = false;
background.left = background.top = background.right = background.bottom = 0;
textDisplay.left = textDisplay.top = textDisplay.right = textDisplay.bottom = 0;
if (promptDisplay)
{
promptDisplay.setLayoutBoundsSize(unscaledWidth, unscaledHeight);
promptDisplay.setLayoutBoundsPosition(0, 0);
}
}
borderStroke.color = getStyle("borderColor");
borderStroke.alpha = getStyle("borderAlpha");
super.updateDisplayList(unscaledWidth, unscaledHeight);
}
private function updatePadding():void {
if (!textDisplay)
return;
var padding:Number;
padding = getStyle("paddingLeft");
if (textDisplay.getStyle("paddingLeft") != padding)
textDisplay.setStyle("paddingLeft", padding);
padding = getStyle("paddingTop");
if (textDisplay.getStyle("paddingTop") != padding)
textDisplay.setStyle("paddingTop", padding);
padding = getStyle("paddingRight");
if (textDisplay.getStyle("paddingRight") != padding)
textDisplay.setStyle("paddingRight", padding);
padding = getStyle("paddingBottom");
if (textDisplay.getStyle("paddingBottom") != padding)
textDisplay.setStyle("paddingBottom", padding);
if (!promptDisplay)
return;
padding = getStyle("paddingLeft");
if (promptDisplay.getStyle("paddingLeft") != padding)
promptDisplay.setStyle("paddingLeft", padding);
padding = getStyle("paddingTop");
if (promptDisplay.getStyle("paddingTop") != padding)
promptDisplay.setStyle("paddingTop", padding);
padding = getStyle("paddingRight");
if (promptDisplay.getStyle("paddingRight") != padding)
promptDisplay.setStyle("paddingRight", padding);
padding = getStyle("paddingBottom");
if (promptDisplay.getStyle("paddingBottom") != padding)
promptDisplay.setStyle("paddingBottom", padding);
}
override public function styleChanged(styleProp:String):void {
var allStyles:Boolean = !styleProp || styleProp == "styleName";
super.styleChanged(styleProp);
if (allStyles || styleProp.indexOf("padding") == 0)
{
paddingChanged = true;
invalidateProperties();
}
}
]]&gt;
&lt;/fx:Script&gt;
&lt;fx:Script&gt;
&lt;![CDATA[
private static const focusExclusions:Array = ["textDisplay"];
override public function get focusSkinExclusions():Array { return focusExclusions;};
]]&gt;
&lt;/fx:Script&gt;
&lt;s:states&gt;
&lt;s:State name="normal"/&gt;
&lt;s:State name="disabled" stateGroups="disabledStates"/&gt;
&lt;s:State name="normalWithPrompt"/&gt;
&lt;s:State name="disabledWithPrompt" stateGroups="disabledStates"/&gt;
&lt;/s:states&gt;
&lt;!-- border --&gt;
&lt;s:Rect left="0" right="0" top="0" bottom="0" id="border"&gt;
&lt;s:stroke&gt;
&lt;!--- @private --&gt;
&lt;s:SolidColorStroke id="borderStroke" weight="1" /&gt;
&lt;/s:stroke&gt;
&lt;/s:Rect&gt;
&lt;!-- fill --&gt;
&lt;s:Rect id="background" left="1" right="1" top="1" bottom="1"&gt;
&lt;s:fill&gt;
&lt;!--- @private Defines the background fill color. --&gt;
&lt;s:SolidColor id="bgFill" color="0xFFFFFF" /&gt;
&lt;/s:fill&gt;
&lt;/s:Rect&gt;
&lt;!-- shadow --&gt;
&lt;s:Rect left="1" top="1" right="1" height="1" id="shadow"&gt;
&lt;s:fill&gt;
&lt;s:SolidColor color="0x000000" alpha="0.12" /&gt;
&lt;/s:fill&gt;
&lt;/s:Rect&gt;
&lt;!-- text --&gt;
&lt;s:RichEditableText id="textDisplay"
verticalAlign="middle"
widthInChars="10"
left="1" right="1" top="1" bottom="1" /&gt;
&lt;s:Label id="promptDisplay" maxDisplayedLines="1"
verticalAlign="middle"
mouseEnabled="false" mouseChildren="false"
includeIn="normalWithPrompt,disabledWithPrompt"
includeInLayout="false"/&gt;
&lt;!-- Added to custom skin to cause prompt text to fade in. --&gt;
&lt;s:transitions&gt;
&lt;s:Transition toState="normalWithPrompt"&gt;
&lt;s:Fade targets="{promptDisplay}" duration="500"/&gt;
&lt;/s:Transition&gt;
&lt;/s:transitions&gt;
&lt;/s:SparkSkin&gt; </pre>
</div>
</div>
</div>
<p>Adobe, Adobe AIR, Adobe Flash, Adobe Flash Platform 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>