Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.text 
TextFormat 
Packageflash.text
Classpublic class TextFormat
InheritanceTextFormat Inheritance Object
Subclasses UITextFormat

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9, Flash Lite 4

The TextFormat class represents character formatting information. Use the TextFormat class to create specific text formatting for text fields. You can apply text formatting to both static and dynamic text fields. The properties of the TextFormat class apply to device and embedded fonts. However, for embedded fonts, bold and italic text actually require specific fonts. If you want to display bold or italic text with an embedded font, you need to embed the bold and italic variations of that font.

You must use the constructor new TextFormat() to create a TextFormat object before setting its properties. When you apply a TextFormat object to a text field using the TextField.defaultTextFormat property or the TextField.setTextFormat() method, only its defined properties are applied. Use the TextField.defaultTextFormat property to apply formatting BEFORE you add text to the TextField, and the setTextFormat() method to add formatting AFTER you add text to the TextField. The TextFormat properties are null by default because if you don't provide values for the properties, Flash Player uses its own default formatting. The default formatting that Flash Player uses for each property (if property's value is null) is as follows:

align = "left"
blockIndent = 0
bold = false
bullet = false
color = 0x000000
font = "Times New Roman" (default font is Times on Mac OS X)
indent = 0
italic = false
kerning = false
leading = 0
leftMargin = 0
letterSpacing = 0
rightMargin = 0
size = 12
tabStops = [] (empty array)
target = "" (empty string)
underline = false
url = "" (empty string)

The default formatting for each property is also described in each property description.

View the examples

See also



Public Properties
 PropertyDefined By
  align : String
Indicates the alignment of the paragraph.
TextFormat
  blockIndent : Object
Indicates the block indentation in pixels.
TextFormat
  bold : Object
Specifies whether the text is boldface.
TextFormat
  bullet : Object
Indicates that the text is part of a bulleted list.
TextFormat
  color : Object
Indicates the color of the text.
TextFormat
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  font : String
The name of the font for text in this text format, as a string.
TextFormat
  indent : Object
Indicates the indentation from the left margin to the first character in the paragraph.
TextFormat
  italic : Object
Indicates whether text in this text format is italicized.
TextFormat
  kerning : Object
A Boolean value that indicates whether kerning is enabled (true) or disabled (false).
TextFormat
  leading : Object
An integer representing the amount of vertical space (called leading) between lines.
TextFormat
  leftMargin : Object
The left margin of the paragraph, in pixels.
TextFormat
  letterSpacing : Object
A number representing the amount of space that is uniformly distributed between all characters.
TextFormat
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  rightMargin : Object
The right margin of the paragraph, in pixels.
TextFormat
  size : Object
The size in pixels of text in this text format.
TextFormat
  tabStops : Array
Specifies custom tab stops as an array of non-negative integers.
TextFormat
  target : String
Indicates the target window where the hyperlink is displayed.
TextFormat
  underline : Object
Indicates whether the text that uses this text format is underlined (true) or not (false).
TextFormat
  url : String
Indicates the target URL for the text in this text format.
TextFormat
Public Methods
 MethodDefined By
  
TextFormat(font:String = null, size:Object = null, color:Object = null, bold:Object = null, italic:Object = null, underline:Object = null, url:String = null, target:String = null, align:String = null, leftMargin:Object = null, rightMargin:Object = null, indent:Object = null, leading:Object = null)
Creates a TextFormat object with the specified properties.
TextFormat
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
Property Detail

align

property
align:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the alignment of the paragraph. Valid values are TextFormatAlign constants.

The default value is TextFormatAlign.LEFT.



Implementation
    public function get align():String
    public function set align(value:String):void

Throws
ArgumentError — The align specified is not a member of flash.text.TextFormatAlign.

See also


Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

blockIndent

property 
blockIndent:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the block indentation in pixels. Block indentation is applied to an entire block of text; that is, to all lines of the text. In contrast, normal indentation (TextFormat.indent) affects only the first line of each paragraph. If this property is null, the TextFormat object does not specify block indentation (block indentation is 0).



Implementation
    public function get blockIndent():Object
    public function set blockIndent(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

bold

property 
bold:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Specifies whether the text is boldface. The default value is null, which means no boldface is used. If the value is true, then the text is boldface.



Implementation
    public function get bold():Object
    public function set bold(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

bullet

property 
bullet:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates that the text is part of a bulleted list. In a bulleted list, each paragraph of text is indented. To the left of the first line of each paragraph, a bullet symbol is displayed. The default value is null, which means no bulleted list is used.



Implementation
    public function get bullet():Object
    public function set bullet(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

color

property 
color:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the color of the text. A number containing three 8-bit RGB components; for example, 0xFF0000 is red, and 0x00FF00 is green. The default value is null, which means that Flash Player uses the color black (0x000000).



Implementation
    public function get color():Object
    public function set color(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

font

property 
font:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

The name of the font for text in this text format, as a string. The default value is null, which means that Flash Player uses Times New Roman font for the text.



Implementation
    public function get font():String
    public function set font(value:String):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

indent

property 
indent:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the indentation from the left margin to the first character in the paragraph. The default value is null, which indicates that no indentation is used.



Implementation
    public function get indent():Object
    public function set indent(value:Object):void

See also


Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

italic

property 
italic:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates whether text in this text format is italicized. The default value is null, which means no italics are used.



Implementation
    public function get italic():Object
    public function set italic(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

kerning

property 
kerning:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

A Boolean value that indicates whether kerning is enabled (true) or disabled (false). Kerning adjusts the pixels between certain character pairs to improve readability, and should be used only when necessary, such as with headings in large fonts. Kerning is supported for embedded fonts only.

Certain fonts such as Verdana and monospaced fonts, such as Courier New, do not support kerning.

The default value is null, which means that kerning is not enabled.



Implementation
    public function get kerning():Object
    public function set kerning(value:Object):void

leading

property 
leading:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

An integer representing the amount of vertical space (called leading) between lines. The default value is null, which indicates that the amount of leading used is 0.



Implementation
    public function get leading():Object
    public function set leading(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

leftMargin

property 
leftMargin:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

The left margin of the paragraph, in pixels. The default value is null, which indicates that the left margin is 0 pixels.



Implementation
    public function get leftMargin():Object
    public function set leftMargin(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

letterSpacing

property 
letterSpacing:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.

A number representing the amount of space that is uniformly distributed between all characters. The value specifies the number of pixels that are added to the advance after each character. The default value is null, which means that 0 pixels of letter spacing is used. You can use decimal values such as 1.75.



Implementation
    public function get letterSpacing():Object
    public function set letterSpacing(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

rightMargin

property 
rightMargin:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

The right margin of the paragraph, in pixels. The default value is null, which indicates that the right margin is 0 pixels.



Implementation
    public function get rightMargin():Object
    public function set rightMargin(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

size

property 
size:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

The size in pixels of text in this text format. The default value is null, which means that a size of 12 is used.



Implementation
    public function get size():Object
    public function set size(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

tabStops

property 
tabStops:Array

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Specifies custom tab stops as an array of non-negative integers. Each tab stop is specified in pixels. If custom tab stops are not specified (null), the default tab stop is 4 (average character width).



Implementation
    public function get tabStops():Array
    public function set tabStops(value:Array):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

target

property 
target:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the target window where the hyperlink is displayed. If the target window is an empty string, the text is displayed in the default target window _self. You can choose a custom name or one of the following four names: _self specifies the current frame in the current window, _blank specifies a new window, _parent specifies the parent of the current frame, and _top specifies the top-level frame in the current window. If the TextFormat.url property is an empty string or null, you can get or set this property, but the property will have no effect.



Implementation
    public function get target():String
    public function set target(value:String):void

See also


Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

underline

property 
underline:Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates whether the text that uses this text format is underlined (true) or not (false). This underlining is similar to that produced by the <U> tag, but the latter is not true underlining, because it does not skip descenders correctly. The default value is null, which indicates that underlining is not used.



Implementation
    public function get underline():Object
    public function set underline(value:Object):void

Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.

url

property 
url:String

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Indicates the target URL for the text in this text format. If the url property is an empty string, the text does not have a hyperlink. The default value is null, which indicates that the text does not have a hyperlink.

Note: The text with the assigned text format must be set with the htmlText property for the hyperlink to work.



Implementation
    public function get url():String
    public function set url(value:String):void

See also


Example
How to use this example
Please see the TextFormat() constructor example for an illustration of how to use this property.
Constructor Detail

TextFormat

()Constructor
public function TextFormat(font:String = null, size:Object = null, color:Object = null, bold:Object = null, italic:Object = null, underline:Object = null, url:String = null, target:String = null, align:String = null, leftMargin:Object = null, rightMargin:Object = null, indent:Object = null, leading:Object = null)

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9., Flash Lite 4

Creates a TextFormat object with the specified properties. You can then change the properties of the TextFormat object to change the formatting of text fields.

Any parameter may be set to null to indicate that it is not defined. All of the parameters are optional; any omitted parameters are treated as null.

Parameters
font:String (default = null) — The name of a font for text as a string.
 
size:Object (default = null) — An integer that indicates the size in pixels.
 
color:Object (default = null) — The color of text using this text format. A number containing three 8-bit RGB components; for example, 0xFF0000 is red, and 0x00FF00 is green.
 
bold:Object (default = null) — A Boolean value that indicates whether the text is boldface.
 
italic:Object (default = null) — A Boolean value that indicates whether the text is italicized.
 
underline:Object (default = null) — A Boolean value that indicates whether the text is underlined.
 
url:String (default = null) — The URL to which the text in this text format hyperlinks. If url is an empty string, the text does not have a hyperlink.
 
target:String (default = null) — The target window where the hyperlink is displayed. If the target window is an empty string, the text is displayed in the default target window _self. If the url parameter is set to an empty string or to the value null, you can get or set this property, but the property will have no effect.
 
align:String (default = null) — The alignment of the paragraph, as a TextFormatAlign value.
 
leftMargin:Object (default = null) — Indicates the left margin of the paragraph, in pixels.
 
rightMargin:Object (default = null) — Indicates the right margin of the paragraph, in pixels.
 
indent:Object (default = null) — An integer that indicates the indentation from the left margin to the first character in the paragraph.
 
leading:Object (default = null) — A number that indicates the amount of leading vertical space between lines.

Example  ( How to use this example )

In the following example, a user can select different text formatting options from a list that is applied to the content of another text field. If the user clicks on the text field's content, the formatting reverts to the default (original) format.

The formatTextField text field lists all the TextField class property options (with the exception of kerning) in a separate line. When a user clicks a line in the formatTextField text field, the formatTextFieldClickHandler() method is triggered.

The formatTextFieldClickHandler() method calls the TextField.getLineIndexAtPoint() method to get the index of the line that was clicked, and then calls the TextField.getLineText() method to get the content of the line. The switch statement checks the content of the line and sets a property of the newformat TextFormat object accordingly. The setTextFormat() method then sets the text format of the contentTextField text field to the new format. By clicking different formatTextField lines, a user can apply a different formatting to the contentTextField text field. (The tab setting is an array that defines a separate tab stop for each tab in the line.) If the url or target line is selected, the user must click the contentTextField text field to activate the link and display the content of the target URL (Flex home page). The default value of the target property is "_self", which means that the content is displayed in the current window if the user selects the url line. For the target property to work, a URL must be set already in the url property.

If a user clicks the contentTextField text field, the contentTextFieldClickHandler() method is triggered, which sets the field's format and the newFormat TextFormat object to the default (original) format of the text field. This clears all the formatting changes that the user made.

package {
    import flash.display.Sprite;
    import flash.text.TextField;
    import flash.text.TextFormat;
    import flash.text.TextFieldAutoSize;
    import flash.events.MouseEvent;
    import flash.text.TextFormatAlign;
    
    public class TextFormat_constructorExample extends Sprite {
        private var contentTextField:TextField = new TextField();
        private var formatTextField:TextField = new TextField();
        private var newFormat:TextFormat = new TextFormat();
        
        public function TextFormat_constructorExample() {
            contentTextField.x = 10;
            contentTextField.y = 10;
            contentTextField.background = true;
            contentTextField.border = true;
            contentTextField.multiline = true;
            contentTextField.wordWrap = true;
            contentTextField.selectable = false;
            contentTextField.width = 250;
            contentTextField.height = 120; 
  
            contentTextField.htmlText = "<p>The TextFormat class represents character formatting "
                + "information. Use the TextFormat class to create specific text formatting "
                + "for text fields." + 
                " </p><br>" + "\tTab One" + "\tTab Two<br>";
              
            formatTextField.x = 10;
            formatTextField.y = 140;
            formatTextField.background = true;
            formatTextField.border = true;
            formatTextField.autoSize = TextFieldAutoSize.LEFT;
            
            formatTextField.text = "align: right\n" + "blockIndent: 10 pixels\n" + "bold:\n" + "bullet:\n" + "color: red\n"
                                + "font: Arial\n" + "indent: 20 pixels\n" + "italic:\n" + "leading: 5 spaces\n" 
                                + "leftMargin: 20 pixels\n" + "letterSpacing: 4 pixels\n" + "rightMargin: 20 pixels\n" 
                                + "size: 16 point\n" + "target: new window\n" + "tabStops: 50 and 150 pixel\n" 
                                + "underline:\n" + "url: Adobe Flex page\n";

            formatTextField.addEventListener(MouseEvent.CLICK, formatTextFieldClickHandler);
            
            contentTextField.addEventListener(MouseEvent.CLICK, contentTextFieldClickHandler);
            
            this.addChild(contentTextField);
            this.addChild(formatTextField);
        }

        private function formatTextFieldClickHandler(e:MouseEvent):void {
                var value:String= "";
                var i:uint = 0;
                var index:int = formatTextField.getLineIndexAtPoint(e.localX, e.localY);
                var line:String = formatTextField.getLineText(index);;

                line = line.substr(0, (line.indexOf(":")));

                switch(line) {
                    case "align":
                        newFormat.align = TextFormatAlign.RIGHT;
                        break;
                    case "blockIndent":
                        newFormat.blockIndent = 10;
                        break;
                    case "bold":
                        newFormat.bold = true;
                        break;
                    case "bullet":
                        newFormat.bullet = true;
                        break;
                    case "color":
                        newFormat.color = 0xFF0000;        
                        break;
                    case "font":
                        newFormat.font = "Arial";
                        break;
                    case "indent":
                        newFormat.indent = 20;
                        break;
                    case "italic":
                        newFormat.italic = true;
                        break;
                    case "leading":
                        newFormat.leading = 5;
                        break;
                    case "leftMargin":
                        newFormat.leftMargin = 20;
                        break;
                    case "letterSpacing":
                        newFormat.letterSpacing = 4;
                        break;
                    case "rightMargin":
                        newFormat.rightMargin = 20;
                        break;
                    case "size":
                        newFormat.size = 16;
                        break;
                    case "tabStops":                
                        newFormat.tabStops = [50, 150];
                        break;
                    case "target":
                        newFormat.url = "http://www.adobe.com/products/flex/";    
                        newFormat.target = "_blank";
                        break;    
                    case "underline":
                        newFormat.underline = true;
                        break;
                    case "url":
                        newFormat.url = "http://www.adobe.com/products/flex/";    
                        break;
                }    

                contentTextField.setTextFormat(newFormat);
        }

        private function contentTextFieldClickHandler(e:MouseEvent):void {
            contentTextField.setTextFormat(contentTextField.defaultTextFormat);
            newFormat = contentTextField.defaultTextFormat;
        }
    }
}
TextFormatExample.as

The following example creates the TextFieldExample class to display a text message with the default location (x = 0, y = 0). This is accomplished using the following steps:
  1. A property label of type TextField is created.
  2. The class constructor calls the function configureLabel()
  3. The configureLabel() function first creates a new TextField object and assigns it to label then sets its parameters to
    • Left-justify the text field
    • Enable the background fill
    • Enable the border.
  4. Next, configureLabel() creates the local variable, format, and assigns it to a new TextFormat instance with its parameters set to:
    • Font type = Verdana
    • Font Color = solid red
    • Font size = 10
    • Font underline = true.
  5. The label's defaultTextFormat property is set to format, and the label instance is added to the display list, which initially displays a text field with no text (as tiny box with a white background) on the stage.
  6. Finally (back in the constructor), the label's text is then set to display "Hello World and welcome to the show", at coordinates x = 0, y = 0 by calling setLabel().
 package {
    import flash.display.Sprite;
    import flash.text.TextField;
    import flash.text.TextFieldAutoSize;
    import flash.text.TextFormat;


    public class TextFormatExample extends Sprite {
        private var label:TextField;

        public function TextFormatExample() {
            configureLabel();
            setLabel("Hello World and welcome to the show");
        }

        public function setLabel(str:String):void {
            label.text = str;
        }

        private function configureLabel():void {
            label = new TextField();
            label.autoSize = TextFieldAutoSize.LEFT;
            label.background = true;
            label.border = true;

            var format:TextFormat = new TextFormat();
            format.font = "Verdana";
            format.color = 0xFF0000;
            format.size = 10;
            format.underline = true;

            label.defaultTextFormat = format;
            addChild(label);
        }
    }
}