RichEditableText  - AS3 Flex

Package	spark.components
Class	public class RichEditableText
Inheritance	RichEditableText UIComponent FlexSprite Sprite DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object
Implements	IFocusManagerComponent, IIMESupport, ISystemCursorClient, IViewport, IEditableText

Adobe recommends that you not use this component in an application that uses the mobileDevice profile.

The rich text can contain clickable hyperlinks and inline graphics that are either embedded or loaded from URLs.

RichEditableText does not have scrollbars, but it implements the IViewport interface for programmatic scrolling so that it can be controlled by a Scroller, which does provide scrollbars. It also supports vertical scrolling with the mouse wheel.

It does not include any user interface for changing the formatting of the text. But it offers APIs which can do this programmatically; these make it possible, for example, for you to create a Bold button that makes the selected text bold.

This class is used in the skins of the Spark versions of TextInput and TextArea. (TextInput does not expose its ability to handle rich text, but TextArea does.) By default, RichEditableText has a transparent background, and it does not support drawing a border.

RichEditableText uses the Text Layout Framework (TLF) library, which in turn builds on the new Flash Text Engine (FTE) in Flash Player 10. In combination, these layers provide text editing with high-quality international typography and layout.

The Spark architecture provides three text "primitives" -- Label, RichText, and RichEditableText. Label is the fastest and most lightweight because it uses only FTE, not TLF, but it is limited in its capabilities: no rich text, no scrolling, no selection, and no editing. RichText adds the ability to display rich text with complex layout, but is still completely non-interactive. RichEditableText is the heaviest-weight, but offers most of what TLF can do. In general, use the fastest text primitive that meets your needs.

RichEditableText is similar to the UITextField class used in MX components. This class did not use FTE or TLF but rather extended the older TextField class.

The most important differences between UITextField and RichEditableText are:

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

RichEditableText uses TLF's 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 which can be programmatically accessed and manipulated. The central object in TLF for representing rich text is a TextFlow, so you specify rich text for a RichEditableText control to display by setting its textFlow property to a TextFlow instance. See the description of the textFlow property for information about how to create one, such as by importing TLF markup. If you don't need to display text that has multiple formats, you can use the text property to set a "plain text" String. See the description 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 RichEditableText tag, as the following example shows:

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

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

You can control the spacing between lines with the lineHeight style and the spacing between paragraphs with the paragraphSpaceBefore and paragraphSpaceAfter styles. You can align or justify the text using the textAlign and textAlignLast styles. You can inset the text from the component's edges using the paddingLeft, paddingTop, paddingRight, and paddingBottom styles.

By default, a RichEditableText "autosizes": it starts out very small if it has no text, and grows in width up to maxWidth as you type. It grows in height when you press the Enter key to start a new line.

The widthInChars and heightInLines properties provide a convenient way to specify the width and height in a way that scales with the font size. You can use the typicalText property as well. Note that if you use typicalText, the widthInChars and heightInLines are ignored. You can also specify an explicit width or height in pixels, or use a percent width and height, or use constraints such as left and right or top and bottom.

When you specify some kind of width -- whether an explicit or percent width, a maxWidth or left and right constraints -- the text wraps at the right edge of the component and the text becomes vertically scrollable when there is more text than fits. If you set the lineBreak style to explicit, new lines will start only at explicit lines breaks, such 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 that case, the text becomes horizontally scrollable if any lines are wider than the control.

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.

The multiline property determines what happens when you press the Enter key. If it is true, the Enter key starts a new paragraph. If it is false, it causes a FlexEvent.ENTER event to be dispatched.

If you don't want the text to be editable, set the editable property to false. If you don't even want the text to be selectable, set the selectable property to false.

Because RichEditableText uses TLF, it supports displaying 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.

As a result of using TLF, the RichEditableText supports unlimited undo/redo within one editing session. An editing session starts when the component gets keyboard focus and ends when it loses focus.

RichEditableText uses TLF's TextContainerManager class to handle its text display, scrolling, selection, editing and context menu.

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.

Show MXML Syntax

Hide MXML Syntax

      <s:RichEditableText
        Properties
        clipAndEnableScrolling="false|true"
        contentHeight="Calculated default"
        contentWidth="Calculated default"
        displayAsPassword="false"
        editable="true"
        heightInLines="NaN"
        horizontalScrollPosition="0"
        imeMode="null"
        maxChars="0"
        multiline="true"
        restrict="null"
        selectable="true"
        selectionActivePosition="-1"
        selectionAnchorPosition="-1"
        selectionHighlighting="TextSelectionHighlighting.WHEN_FOCUSED"
        text=""
        textFlow="TextFlow"
        typicalText=null
        verticalScrollPosition="0"
        widthInChars="NaN"
      
        Events
        change="No default"
        changing="No default"
        enter="No default"
        selectionChange="No default"
      />
      

Default MXML Propertycontent

View the examples

More examples

Related API Elements