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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

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.

See also

The width of the text.

The value of the textWidth property is correct only after the component has been validated. If you set text and then immediately ask for the textWidth, 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.

See also

Whether the vertical scroll bar is always on (ScrollPolicy.ON), always off (ScrollPolicy.OFF), or turns on when needed (ScrollPolicy.AUTO).

The default value is ScrollPolicy.AUTO.

Line number of the top row of characters that is currently displayed. 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.

Indicates whether the text automatically wraps at the end of a line. If true, the text wraps to occupy multiple lines, if necessary.

The default value is true.

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

Constructor.

Returns a TextLineMetrics object with information about the text position and measurements for a line of text in the control. The component must be validated to get a correct number. If you set the text or htmlText property and then immediately call getLineMetrics() you may receive an incorrect value. You should either wait for the component to validate or call validateNow(). This is behavior differs from that of the flash.text.TextField class, which updates the value immediately.

Parameters

See also

Selects the text in the range specified by the parameters. If the control is not in focus, the selection highlight will not show until the control gains focus. Also, if the focus is gained by clicking on the control, any previous selection would be lost. If the two parameter values are the same, the new selection is an insertion point.

Parameters

Dispatched when text in the TextArea control changes through user input. This event does not occur if you use data binding or ActionScript code to change the text.

Even though the default value of the Event.bubbles property is true, this control dispatches the event with the Event.bubbles property set to false.

This event has the following properties:

Dispatched when the data property changes.

When you use a component as an item renderer, the data property contains the data to display. You can listen for this event and update the component when the data property changes.

The properties of the event object have the following values:

Dispatched when a user clicks a hyperlink in text defined by the htmlText property, where the URL begins with "event:". The remainder of the URL after "event:" is placed in the text property of the link event object.

When you handle the link event, the hyperlink is not automatically executed; you need to execute the hyperlink from within your event handler. You typically use the navigateToURL() method to execute the hyperlink. This allows you to modify the hyperlink, or even prohibit it from occurring, in your application.

This event has the following properties: