| { "type": "class", | |
| "qname": "spark.components.RichText", | |
| "baseClassname": "spark.components.supportClasses.TextBase" | |
| , | |
| "description": "RichText is a low-level UIComponent that can display one or more lines of richly-formatted text and embedded images. <p>For performance reasons, it does not support scrolling, selection, editing, clickable hyperlinks, or images loaded from URLs. If you need those capabilities, please see the RichEditableText class.</p> <p>RichText uses the Text Layout Framework (TLF) library, which in turn builds on the Flash Text Engine (FTE) in Flash Player 10. In combination, they provide rich text layout using high-quality international typography.</p> <p>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. You should use the lightest-weight text primitive that meets your needs.</p> <p>RichText is similar to the MX control mx.controls.Text. The Text control uses the older TextField class, instead of TLF, to display text.</p> <p>The most important differences between RichText and Text are: <ul> <li>RichText offers better typography, better support for international languages, and better text layout than Text.</li> <li>RichText has an object-oriented model of what it displays, while Text does not.</li> <li>Text is selectable, while RichText does not support selection.</li> </ul></p> <p>RichText uses TLF's object-oriented model of rich text, in which text layout elements such as divisions, paragraphs, spans, 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, and you specify what RichText should display by setting its <code>textFlow</code> property to a TextFlow instance. (Please see the description of the <code>textFlow</code> property for information about how to create one.) You can also set the <code>text</code> property that is inherited from TextBase, but if you don't need the richness of a TextFlow, you should consider using Label instead.</p> <p>At compile time, you can put TLF markup tags inside the RichText tag, as the following example shows: <pre>\\n <s:RichText>Hello <s:span fontWeight="bold">World!</s:span></s:RichText>\\n </pre> In this case, the MXML compiler sets the <code>content</code> property, causing a TextFlow to be automatically created from the FlowElements that you specify.</p> <p>The default text formatting is determined by CSS styles such as <code>fontFamily</code>, <code>fontSize</code>. Any formatting information in the TextFlow overrides the default formatting provided by the CSS styles.</p> <p>You can control the spacing between lines with the <code>lineHeight</code> style and the spacing between paragraphs with the <code>paragraphSpaceBefore</code> and <code>paragraphSpaceAfter</code> styles. You can align or justify the text using the <code>textAlign</code> and <code>textAlignLast</code> styles. You can inset the text from the component's edges using the <code>paddingLeft</code>, <code>paddingTop</code>, <code>paddingRight</code>, and <code>paddingBottom</code> styles.</p> <p>If you don't specify any kind of width for a RichText, then the longest line, as determined by these explicit line breaks, determines the width of the Label.</p> <p>When you specify a width, the text wraps at the right edge of the component and the text is clipped when there is more text than fits. If you set the <code>lineBreak</code> style to <code>explicit</code>, new lines will start only at explicit lines breaks, such as if you use CR (<code>\\r</code>), LF (<code>\\n</code>), or CR+LF (<code>\\r\\n</code>) in <code>text</code> or if you use <code><p></code> and <code><br/></code> in TLF markup. In that case, lines that are wider than the control are clipped.</p> <p>If you have more text than you have room to display it, RichText can truncate the text for you. Truncating text means replacing excess text with a truncation indicator such as "...". See the inherited properties <code>maxDisplayedLines</code> and <code>isTruncated</code>.</p> <p>By default,RichText has no background, but you can draw one using the <code>backgroundColor</code> and <code>backgroundAlpha</code> styles. Borders are not supported. If you need a border, or a more complicated background, use a separate graphic element, such as a Rect, behind the RichText.</p> <p>Because RichText 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 <code>direction</code> style to <code>rtl</code>. The <code>textAlign</code> style defaults to <code>"start"</code>, which makes the text left-aligned when <code>direction</code> is <code>ltr</code> and right-aligned when <code>direction</code> is <code>rtl</code>. To get the opposite alignment, set <code>textAlign</code> to <code>end</code>.</p> <p>RichText uses TLF's StringTextFlowFactory and TextFlowTextLineFactory classes to create one or more TextLine objects to statically display its text. For performance, its TextLines do not contain information about individual glyphs; for more info, see the TextLineValidity class.</p> <p>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 <a href="http://help.adobe.com/en_US/flex/using/WS4bebcd66a74275c3-fc6548e124e49b51c4-8000.html"> Custom Spark item renderers</a>. </p> <p>The <code><s:RichText></code> tag inherits all of the tag attributes of its superclass and adds the following tag attributes:</p> <pre>\\n <s:RichText\\n <strong>Properties</strong>\\n luminosityClip="false"\\n luminosityInvert="false"\\n maskType="MaskType.CLIP"\\n textFlow="<i>TextFlow</i>"\\n />\\n </pre>", | |
| "tags": [ | |
| { "tagName": "includeExample", | |
| "values": ["examples/RichTextExample.mxml"]}, | |
| { "tagName": "see", | |
| "values": ["spark.components.RichEditableText", "spark.components.Label", "flash.text.engine.TextLineValidity"]}, | |
| { "tagName": "mxml", | |
| "values": []}, | |
| { "tagName": "playerversion", | |
| "values": ["Flash 10", "AIR 1.5"]}, | |
| { "tagName": "productversion", | |
| "values": ["Flex 4"]}, | |
| { "tagName": "langversion", | |
| "values": ["3.0"]} ], | |
| "members": [ | |
| { "type": "method", | |
| "qname": "spark.components.RichText", | |
| "namespace": "", | |
| "bindable": [], | |
| "details": [], | |
| "deprecated": {}, | |
| "description": "Constructor.", | |
| "tags": [ | |
| { "tagName": "playerversion", | |
| "values": ["Flash 10", "AIR 1.5"]}, | |
| { "tagName": "productversion", | |
| "values": ["Flex 4"]}, | |
| { "tagName": "langversion", | |
| "values": ["3.0"]} ], | |
| "return": "", | |
| "params": []} | |
| , | |
| { "type": "method", | |
| "qname": "createElement", | |
| "namespace": "protected", | |
| "bindable": [], | |
| "details": ["override"], | |
| "deprecated": {}, | |
| "return": "org.apache.royale.core.WrappedHTMLElement", | |
| "params": []} | |
| , | |
| { "type": "method", | |
| "qname": "addedToParent", | |
| "namespace": "public", | |
| "bindable": [], | |
| "details": ["override"], | |
| "deprecated": {}, | |
| "return": "void", | |
| "params": []} | |
| , | |
| { "type": "accessor", | |
| "access": "read-write", | |
| "return": "String", | |
| "qname": "text", | |
| "namespace": "public", | |
| "bindable": [], | |
| "details": ["override"], | |
| "deprecated": {}, | |
| "description": "This will create a TextFlow with a single paragraph with a single span with exactly the text specified. If there is whitespace and line breaks in the text, they will remain, regardless of the settings of the lineBreak and whiteSpaceCollapse styles.", | |
| "tags": [ | |
| { "tagName": "private", | |
| "values": []} ]}, | |
| { "type": "accessor", | |
| "access": "read-write", | |
| "return": "Object", | |
| "qname": "content", | |
| "namespace": "public", | |
| "bindable": [], | |
| "details": [], | |
| "deprecated": {}, | |
| "description": "This property is intended for use in MXML at compile time; to get or set rich text content at runtime, please use the <code>textFlow</code> property instead. <p>The <code>content</code> property is the default property for RichText, so that you can write MXML such as <pre>\\n <s:RichText>Hello <s:span fontWeight="bold"/>World</s:span></s:RichText>\\n </pre> and have the String and SpanElement that you specify as the content be used to create a TextFlow.</p> <p>This property is typed as Object because you can set it to to a String, a FlowElement, or an Array of Strings and FlowElements. In the example above, you are specifying the content to be a 2-element Array whose first element is the String "Hello" and whose second element is a SpanElement with the text "World" in boldface.</p> <p>No matter how you specify the content, it gets converted into a TextFlow, and when you get this property, you will get the resulting TextFlow.</p> <p>Adobe recommends using <code>textFlow</code> property to get and set rich text content at runtime, because it is strongly typed as a TextFlow rather than as an Object. A TextFlow is the canonical representation for rich text content in the Text Layout Framework.</p>", | |
| "tags": [ | |
| { "tagName": "playerversion", | |
| "values": ["Flash 10", "AIR 1.5"]}, | |
| { "tagName": "productversion", | |
| "values": ["Flex 4"]}, | |
| { "tagName": "langversion", | |
| "values": ["3.0"]} ]}, | |
| { "type": "accessor", | |
| "access": "read-write", | |
| "return": "org.apache.royale.textLayout.elements.TextFlow", | |
| "qname": "textFlow", | |
| "namespace": "public", | |
| "bindable": [], | |
| "details": [], | |
| "deprecated": {}, | |
| "description": "The TextFlow representing the rich text displayed by this component. <p>A TextFlow is the most important class in the Text Layout Framework (TLF). It is the root of a tree of FlowElements representing rich text content.</p> <p>You normally create a TextFlow from TLF markup using the <code>TextFlowUtil.importFromString()</code> or <code>TextFlowUtil.importFromXML()</code> methods. Alternately, you can use TLF's TextConverter class (which can import a subset of HTML) or build a TextFlow using methods like <code>addChild()</code> on TextFlow.</p> <p>Setting this property affects the <code>text</code> property and vice versa.</p> <p>If you set the <code>textFlow</code> and get the <code>text</code>, the text in each paragraph will be separated by a single LF (<code>\\n</code>).</p> <p>If you set the <code>text</code> to a String such as <code>"Hello World"</code> and get the <code>textFlow</code>, it will be a TextFlow containing a single ParagraphElement with a single SpanElement.</p> <p>If the text contains explicit line breaks -- CR (<code>\\r</code>), LF (<code>\\n</code>), or CR+LF (<code>\\r\\n</code>) -- then the content will be set to a TextFlow which contains multiple paragraphs, each with one span.</p> <p>To turn a TextFlow object into TLF markup, use the markup returned from the <code>TextFlowUtil.export()</code> method.</p>", | |
| "tags": [ | |
| { "tagName": "see", | |
| "values": ["spark.utils.TextFlowUtil#importFromString()", "spark.utils.TextFlowUtil#importFromXML()", "spark.components.RichEditableText#text"]}, | |
| { "tagName": "playerversion", | |
| "values": ["Flash 10", "AIR 2.5"]}, | |
| { "tagName": "productversion", | |
| "values": ["Flex 4.5"]}, | |
| { "tagName": "langversion", | |
| "values": ["3.0"]} ]}] | |
| } |