TextArea  - AS3 Flex

Package	spark.components
Class	public class TextArea
Inheritance	TextArea SkinnableTextBase SkinnableComponent UIComponent FlexSprite Sprite DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object

The skin for the Spark theme uses the RichEditableText class. This means that the Spark TextArea control supports the Text Layout Framework (TLF) library, which builds on the Flash Text Engine (FTE). In combination, these layers provide text editing with high-quality international typography and layout. The skin includes a scroller that can display horizontal and vertical scrollbars for scrolling through the text and supports vertical scrolling with the mouse wheel. The RichEditableText can be accessed as textDisplay and the Scroller as scroller.

The skin for the mobile theme uses the StyleableStageText class. Since StyleableStageText uses native text fields it allows for better text entry and manipulation experiences on mobile devices however there are some limitations and differences that you should consider. Because StageText is not capable of measuring text, the TextArea must be given explicit, percent-based, or constraint-based width and height. The StyleableStageText can be accessed as textDisplay. If you wish to use the TextField-based skin, rather than the StageText-based skin, set the skinClass property to "spark.skins.mobile.TextAreaSkin".

You can set the text to be displayed, or get the text that the user has entered, using the text property.

The text is formatted using CSS styles such as fontFamily and fontSize.

For the Spark theme, the widthInChars and heightInLines properties let you specify the width and height of the TextArea in a way that scales with the font size or you can use the typicalText property. Note that if you use typicalText, the widthInChars and heightInLines properties are ignored. For all themes, you can also specify an explicit width or height in pixels, or use a percent width and height or constraints such as left and right or top and bottom.

You can use the maxChars property to limit the number of character that the user can enter, and the restrict to limit which characters the user can enter. To use this control for password input, set the displayAsPassword property to true.

For the mobile theme, the soft-keyboard-specific properties, autoCapitalize, autoCorrect, returnKeyLabel and softKeyboardType properties specify keyboard hints. If a soft-keyboard is present but does not support a feature represented by the hint, the hint is ignored. In mobile environments with only hardware keyboards, these hints are ignored.

Text Area for the Spark Theme

The most important differences between Spark TextArea and the MX TextArea control are as follows:

• Spark TextArea offers better typography, better support for international languages, and better text layout.
• Spark TextArea has an object-oriented model of rich text, while the MX version does not.
• Spark TextArea has better support for displaying large amounts of text.
• Spark TextArea requires that fonts be embedded differently than the MX version. To learn how to use the embedAsCFF attribute when you embed a font, see the font documentation.

The Spark TextArea control uses the TLF object-oriented model of rich text, in which text layout elements such as divisions, paragraphs, spans, hyperlinks, and images are represented at runtime by ActionScript objects. You can programmatically access and manipulate these objects. The central object in TLF for representing rich text is a TextFlow. Specify rich text for a TextArea control by setting its textFlow property to a TextFlow instance.

If you don't need to display text that has multiple formats, set the TextArea text property to a plain text string. See the descriptions of the text and textFlow properties for information about how they interact; for example, you can set one and get the other.

At compile time, you can put TLF markup tags inside the TextArea tag, as the following example shows:

  <s:TextArea>Hello <s:span fontWeight="bold">World!</s:span></s:TextArea>
  

The TextArea control does not include any user interface for changing the formatting of the text but contains APIs that you can use to programmatically format text. For example, you can create a a button that, when clicked, makes the selected text bold.

The default text formatting is determined by CSS styles such as fontFamily and fontSize. Any formatting information in the TextFlow object overrides the default formatting provided by the CSS styles.

You can control many characteristics of TextArea content with styles. Here are a few popular ones:

• Control spacing between lines with the lineHeight style.
• Control the spacing between paragraphs with the paragraphSpaceBefore and paragraphSpaceAfter styles.
• Align or justify text using the textAlign and textAlignLast styles.
• Inset text from the border of the control using the paddingLeft, paddingTop, paddingRight, and paddingBottom styles.

By default, the text wraps at the right edge of the control. A vertical scrollbar automatically appears when there is more text than fits in the TextArea. If you set the lineBreak style to explicit, new lines start only at explicit line breaks. This has the same effect as if you use CR (\r), LF (\n), or CR+LF (\r\n) in text, or if you use <p> and <br/> in TLF markup. In those cases, a horizontal scrollbar automatically appears if any lines of text are wider than the control.

The Spark TextArea can display left-to-right (LTR) text, such as French, right-to-left (RTL) text, such as Arabic, and bidirectional text, such as a French phrase inside of an Arabic one. If the predominant text direction is right-to-left, set the direction style to rtl. The textAlign style defaults to start, which makes the text left-aligned when direction is ltr and right-aligned when direction is rtl. To get the opposite alignment, set textAlign to end.

The Spark TextArea also supports unlimited undo/redo within one editing session. An editing session starts when the control gets keyboard focus and ends when the control loses focus.

To use this component in a list-based component, such as a List or DataGrid, create an item renderer. For information about creating an item renderer, see Custom Spark item renderers.

For the Spark theme, the TextArea control has the following default characteristics:

For the Mobile theme, the TextArea control has the following default characteristics:

Show MXML Syntax

Hide MXML Syntax

  <s:TextArea
    Properties
    heightInLines="Calculated default"  [Spark theme only]
    textFlow="TextFlow"  [Spark theme only]
    typicalText=null  [Spark theme only]
    widthInChars="Calculated default"  [Spark theme only]
  
    Styles
    horizontalScrollPolicy="auto"  [Spark theme only]
    symbolColor=""
    verticalScrollPolicy="auto"  [Spark theme only]
  />
  

Default MXML Propertycontent

View the examples

More examples

Related API Elements