ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
TextFormat

Package | flash.text
Class | public class TextFormat
Inheritance | TextFormat Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

flash.text.TextField.setTextFormat()
flash.text.TextField.defaultTextFormat
flash.text.TextField.getTextFormat()

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined 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
|  | constructor : 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
|  | prototype : 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 point size 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined 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
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

align | property

`align:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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

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

blockIndent | property |

`blockIndent:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

bold | property |

`bold:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

bullet | property |

`bullet:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

color | property |

`color:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

font | property |

`font:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

indent | property |

`indent:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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

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

italic | property |

`italic:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

kerning | property |

`kerning:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

leftMargin | property |

`leftMargin:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

letterSpacing | property |

`letterSpacing:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | 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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

rightMargin | property |

`rightMargin:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

size | property |

`size:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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

Implementation
`public function get size():Object`
`public function set size(value:Object):void`
Example
How to use examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

tabStops | property |

`tabStops:Array` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

target | property |

`target:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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

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

underline | property |

`underline:Object` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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 examples
Please see the TextFormat() constructor example for an illustration of how to use this property.

url | property |

`url:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.

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

flash.text.TextField.htmlText
Example
How to use examples
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

Player Version : | Flash Player 9.

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 point size.
| `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
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;
            }
        }
    }

Examples How to use examples
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, `configureLable()` 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);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00