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

The condenseWhite property affects only 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

The module factory that provides the font context for this component.

Specifies the text displayed by the Label 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 Label 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 Label 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:Label 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:Label id="myLabel" initialize="myLabel_initialize()"/>
        

  where the myLabel_initialize method is in a script CDATA section:

        <fx:Script>
        <![CDATA[
        private function myLabel_initialize():void {
            myLabel.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 label 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:Label>
            <mx:htmlText><![CDATA[This is an example of <b>bold</b> markup]]></mx:htmlText>
        <mx:Label/>
        

  You must write the htmlText property as a child tag rather than as an attribute on the <mx:Label> 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 as the XML "entities" < and >:

        <mx:Label 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 Label 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 Label. 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

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

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

When a link event is specified in the Label control, the selectable property must be set to true to execute the link event.

The default value is false;.

A flash.text.StyleSheet object that can perform rendering on the Label control's text. Use this property 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

Specifies the plain text displayed by this control. Its appearance is determined by the CSS styles of this Label control.

When you set this property, any characters that might look like HTML markup in the string have no special meaning and appear as entered.

To display text formatted by using HTML tags, use the htmlText property instead. If you set the htmlText property, the HTML replaces any text that you set using this property, and the text property returns a plain-text version of the HTML text, with all HTML tags stripped out.

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 the text is wider than the Label control, the text is truncated and terminated by an ellipsis (...). The full text displays as a tooltip when you move the mouse over the Label control. If you also set a tooltip by using the tooltip property, the tooltip is displayed rather than the text.

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 valueCommit event.

The internal UITextField that renders the text of this Label.

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

If this propery is true, and the Label control size is smaller than its text, the text of the Label control is truncated using a localizable string, such as "...". If this property is false, text that does not fit is clipped.

The default value is true.

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 text 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

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 an HTML-enabled text field, 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.

The Label control must have the selectable property set to true to generate the link event.

This event has the following properties: