TextArea  - AS3 Flex

Specifies whether extra white space (spaces, line breaks, and so on) should be removed in a TextArea control with HTML text.

The condenseWhite property only affects text set with the htmlText property, not the text property. If you set text with the text property, condenseWhite is ignored.

If you set the condenseWhite property to true, you must use standard HTML commands such as <br> and <p> to place line breaks in the text field.

The default value is false.

This property can be used as the source for data binding. When this property is modified, it dispatches the condenseWhiteChanged event.

Lets you pass a value to the component when you use it in an item renderer or item editor. You typically use data binding to bind a field of the data property to a property of this component.

When you use the control as a drop-in item renderer or drop-in item editor, Flex automatically writes the current value of the item to the text property of this control.

You do not set this property in MXML.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the dataChange event.

Related API Elements

Indicates whether this control is used for entering passwords. If true, the field does not display entered text, instead, each text character entered into the control appears as the character "*".

The default value is false.

This property can be used as the source for data binding. When this property is modified, it dispatches the displayAsPasswordChanged event.

Indicates whether the user is allowed to edit the text in this control. If true, the user can edit the text.

The default value is true;.

This property can be used as the source for data binding. When this property is modified, it dispatches the editableChanged event.

A flag that indicates whether the IME should be enabled when the component receives focus.

Specifies whether the horizontal scroll bar is always on (ScrollPolicy.ON), always off (ScrollPolicy.OFF), or turns on when needed (ScrollPolicy.AUTO).

The default value is ScrollPolicy.AUTO.

Pixel position in the content area of the leftmost pixel that is currently displayed. (The content area includes all contents of a control, not just the portion that is currently displayed.) This property is always set to 0, and ignores changes, if wordWrap is set to true.

The default value is 0.

This property can be used as the source for data binding. When this property is modified, it dispatches the viewChanged event.

Specifies the text displayed by the TextArea control, including HTML markup that expresses the styles of that text. When you specify HTML text in this property, you can use the subset of HTML tags that is supported by the Flash TextField control.

When you set this property, the HTML markup is applied after the CSS styles for the TextArea instance are applied. When you get this property, the HTML markup includes the CSS styles.

For example, if you set this to be a string such as, "This is an example of <b>bold</b> markup", the text "This is an example of bold markup" appears in the TextArea with whatever CSS styles normally apply. Also, the word "bold" appears in boldface font because of the <b> markup.

HTML markup uses characters such as < and >, which have special meaning in XML (and therefore in MXML). So, code such as the following does not compile:

      <mx:TextArea htmlText="This is an example of <b>bold</b> markup"/>
      

There are three ways around this problem.

• Set the htmlText property in an ActionScript method called as an initialize handler:

        <mx:TextArea id="myTextArea" initialize="myTextArea_initialize()"/>
        

  where the myTextArea_initialize method is in a script CDATA section:

        <fx:Script>
        <![CDATA[
        private function myTextArea_initialize():void {
            myTextArea.htmlText = "This is an example of <b>bold</b> markup";
        }
        ]]>
        </fx:Script>
        
        

  This is the simplest approach because the HTML markup remains easily readable. Notice that you must assign an id to the TextArea so you can refer to it in the initialize handler.

• Specify the htmlText property by using a child tag with a CDATA section. A CDATA section in XML contains character data where characters like < and > aren't given a special meaning.

        <mx:TextArea>
            <mx:htmlText><![CDATA[This is an example of <b>bold</b> markup]]></mx:htmlText>
        <mx:TextArea/>
        

  You must write the htmlText property as a child tag rather than as an attribute on the <mx:TextArea> tag because XML doesn't allow CDATA for the value of an attribute. Notice that the markup is readable, but the CDATA section makes this approach more complicated.

• Use an hmtlText attribute where any occurences of the HTML markup characters < and > in the attribute value are written instead of the XML "entities" < and >:

        <mx:TextArea htmlText="This is an example of <b>bold</b> markup"/>
        

  Adobe does not recommend this approach because the HTML markup becomes nearly impossible to read.

If the condenseWhite property is true when you set the htmlText property, multiple white-space characters are condensed, as in HTML-based browsers; for example, three consecutive spaces are displayed as a single space. The default value for condenseWhite is false, so you must set condenseWhite to true to collapse the white space.

If you read back the htmlText property quickly after setting it, you get the same string that you set. However, after the LayoutManager runs, the value changes to include additional markup that includes the CSS styles.

Setting the htmlText property affects the text property in several ways. If you read the text property quickly after setting the htmlText property, you get null, which indicates that the text corresponding to the new htmlText has not yet been determined. However, after the LayoutManager runs, the text property value changes to the htmlText string with all the HTML markup removed; that is, the value is the characters that the TextArea actually displays.

Conversely, if you set the text property, any previously set htmlText is irrelevant. If you read the htmlText property quickly after setting the text property, you get null, which indicates that the htmlText that corresponds to the new text has not yet been determined. However, after the LayoutManager runs, the htmlText property value changes to the new text plus the HTML markup for the CSS styles.

To make the LayoutManager run immediately, you can call the validateNow() method on the TextArea. For example, you could set some htmlText, call the validateNow() method, and immediately obtain the corresponding text that doesn't have the HTML markup.

If you set both text and htmlText properties in ActionScript, whichever is set last takes effect. Do not set both in MXML, because MXML does not guarantee that the properties of an instance get set in any particular order.

Setting either text or htmlText property inside a loop is a fast operation, because the underlying TextField that actually renders the text is not updated until the LayoutManager runs.

If you try to set this property to null, it is set, instead, to the empty string. If the property temporarily has the value null, it indicates that the text has been recently set and the corresponding htmlText has not yet been determined.

The default value is "".

This property can be used as the source for data binding. When this property is modified, it dispatches the htmlTextChanged event.

Related API Elements

Specifies the IME (input method editor) mode. The IME enables users to enter text in Chinese, Japanese, and Korean. Flex sets the specified IME mode when the control gets the focus, and sets it back to the previous value when the control loses the focus.

The flash.system.IMEConversionMode class defines constants for the valid values for this property. You can also specify null to specify no IME.

The default value is null.

Related API Elements

The number of characters of text displayed in the TextArea.

The default value is 0.

When a component is used as a drop-in item renderer or drop-in item editor, Flex initializes the listData property of the component with the appropriate data from the list control. The component can then use the listData property to initialize the data property of the drop-in item renderer or drop-in item editor.

You do not set this property in MXML or ActionScript; Flex sets it when the component is used as a drop-in item renderer or drop-in item editor.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the dataChange event.

Related API Elements

Maximum number of characters that users can enter in the text field. This property does not limit the length of text specified by the setting the control's text or htmlTextproperty.

The default value of 0, which indicates no limit.

This property can be used as the source for data binding. When this property is modified, it dispatches the maxCharsChanged event.

Indicates the set of characters that a user can enter into the control. If the value of the restrict property is null, you can enter any character. If the value of the restrict property is an empty string, you cannot enter any character. This property only restricts user interaction; a script can put any text into the text field. If the value of the restrict property is a string of characters, you may enter only characters in that string into the text field.

Flex scans the string from left to right. You can specify a range by using the hyphen (-) character. If the string begins with a caret (^) character, all characters are initially accepted and succeeding characters in the string are excluded from the set of accepted characters. If the string does not begin with a caret (^) character, no characters are initially accepted and succeeding characters in the string are included in the set of accepted characters.

Because some characters have a special meaning when used in the restrict property, you must use backslash characters to specify the literal characters -, ^, and \. When you use the restrict property as an attribute in an MXML tag, use single backslashes, as in the following example: \^\-\\. When you set the restrict In and ActionScript expression, use double backslashes, as in the following example: \\^\\-\\\.

The default value is null.

This property can be used as the source for data binding. When this property is modified, it dispatches the restrictChanged event.

Related API Elements

Specifies whether the text can be selected. Making the text selectable lets you copy text from the control.

The default value is true.

The zero-based character index value of the first character in the current selection. For example, the first character is 0, the second character is 1, and so on. When the control gets the focus, the selection is visible if the selectionBeginIndex and selectionEndIndex properties are both set.

The default value is 0.

The zero-based index of the position afterthe last character in the current selection (equivalent to the one-based index of the last character). If the last character in the selection, for example, is the fifth character, this property has the value 5. When the control gets the focus, the selection is visible if the selectionBeginIndex and selectionEndIndex properties are both set.

The default value is 0.

A flash.text.StyleSheet object that can perform rendering on the TextArea control's text. Used for detailed control of HTML styles for the text. For more information, see the flash.text.StyleSheet class documentation.

The default value is null.

Related API Elements

Plain text that appears in the control. Its appearance is determined by the CSS styles of this Label control.

Any HTML tags in the text string are ignored, and appear as entered in the string. To display text formatted using HTML tags, use the htmlText property instead. If you set the htmlText property, the HTML replaces any text you had set using this propety, and the text property returns a plain-text version of the HTML text, with all HTML tags stripped out. For more information see the htmlText property.

To include the special characters left angle bracket (<), right angle bracket (>), or ampersand (&) in the text, wrap the text string in the CDATA tag. Alternatively, you can use HTML character entities for the special characters, for example, <.

If you try to set this property to null, it is set, instead, to the empty string. The text property can temporarily have the value null, which indicates that the htmlText has been recently set and the corresponding text value has not yet been determined.

The default value is "".

This property can be used as the source for data binding. When this property is modified, it dispatches the textChanged event.

The internal UITextField that renders the text of this TextArea.

The height of the text.

The value of the textHeight property is correct only after the component has been validated. If you set text and then immediately ask for the textHeight, you might receive an incorrect value. You should wait for the component to validate or call the validateNow() method before you get the value. This behavior differs from that of the flash.text.TextField control, which updates the value immediately.