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

Package | flash.text.engine
Class | public final class TextBlock
Inheritance | TextBlock Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The TextBlock class is a factory for the creation of TextLine objects, which you can render by placing them on the display list.

The TextBlock class is intended to contain a single paragraph because the Unicode bidirectional and line-break algorithms operate on one paragraph at a time. For applications that compose multiple paragraphs of text, use a markup language, or text analysis, to divide the text into paragraphs and create one TextBlock per paragraph.

The TextBlock object stores its content in the `content` property, which is an instance of the ContentElement class. Because you can't create an instance of the ContentElement class, set `content` to an instance of one of its subclasses: TextElement, GraphicElement, or GroupElement. Use TextElement for purely text content, GraphicElement for an image or graphic content, and GroupElement for content that contains a combination of TextElement, GraphicElement, and other GroupElement objects. Refer to the ContentElement class and its subclasses for details on managing formatted runs of text, embedded sub runs, and graphic elements.

After you create the TextBlock instance and set the `content` property, call the `createTextLine()` method to create lines of text, which are instances of the `TextLine` class.

View the examples

See also

ContentElement
GraphicElement
GroupElement
TextBaseline
TextElement
TextJustifier
TextLine
TextRotation
TabStop

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | applyNonLinearFontScaling : Boolean Specifies that you want to enhance screen appearance at the expense of what-you-see-is-what-you-get (WYSIWYG) print fidelity. | TextBlock
|  | baselineFontDescription : FontDescription The font used to determine the baselines for all the lines broken from the block, independent of their content. | TextBlock
|  | baselineFontSize : Number The font size used to calculate the baselines for the lines broken from the block. | TextBlock
|  | baselineZero : String Specifies which baseline is at y=0 for lines broken from this block. | TextBlock
|  | bidiLevel : int Specifies the default bidirectional embedding level of the text in the text block. | TextBlock
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | content : ContentElement Holds the contents of the text block. | TextBlock
|  | firstInvalidLine : TextLine [read-only] Identifies the first line in the text block in which TextLine.validity is not equal to TextLineValidity.VALID. | TextBlock
|  | firstLine : TextLine [read-only] The first TextLine in the TextBlock, if any. | TextBlock
|  | glyphRotation : String Specifies automatic glyph rotation based on Unicode code point. | TextBlock
|  | lastLine : TextLine [read-only] The last TextLine in the TextBlock, if any. | TextBlock
|  | lineRotation : String Rotates the text lines in the text block as a unit. | TextBlock
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | tabStops : Vector Specifies the tab stops for the text in the text block, in the form of a Vector of TabStop objects. | TextBlock
|  | textJustifier : TextJustifier Specifies the TextJustifier to use during line breaking. | TextBlock
|  | textLineCreationResult : String [read-only] Indicates the result of a createTextLine operation. | TextBlock
|  | userData : * Provides a way for the author to associate arbitrary data with the text block. | TextBlock

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | TextBlock(content:ContentElement = null, tabStops:Vector = null, textJustifier:TextJustifier = null, glyphRotation:String = "none", lineRotation:String = "rotate0", baselineZero:String = "roman", bidiLevel:int = 0, applyNonLinearFontScaling:Boolean = true, baselineFontDescription:FontDescription = null, baselineFontSize:Number = 12.0) Creates a TextBlock object | TextBlock
|  | createTextLine(previousLine:TextLine = null, width:Number = 1000000, lineOffset:Number = 0.0, fitSomething:Boolean = false):TextLine Instructs the text block to create a line of text from its content, beginning at the point specified by the previousLine parameter and breaking at the point specified by the width parameter. | TextBlock
|  | dump():String Dumps the underlying contents of the TextBlock as an XML string. | TextBlock
|  | findNextAtomBoundary(afterCharIndex:int):int Finds the index of the next Atom boundary from the specified character index, not including the character at the specified index. | TextBlock
|  | findNextWordBoundary(afterCharIndex:int):int Finds the index of the next word boundary from the specified character index, not including the character at the specified index. | TextBlock
|  | findPreviousAtomBoundary(beforeCharIndex:int):int Finds the index of the previous atom boundary to the specified character index, not including the character at the specified index. | TextBlock
|  | findPreviousWordBoundary(beforeCharIndex:int):int Finds the index of the previous word boundary to the specified character index, not including the character at the specified index. | TextBlock
|  | getTextLineAtCharIndex(charIndex:int):TextLine Returns the TextLine containing the character specified by the charIndex parameter. | TextBlock
|  | 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
|  | releaseLines(firstLine:TextLine, lastLine:TextLine):* Removes a range of text lines from the list of lines maintained by the TextBlock. | TextBlock
|  | 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

applyNonLinearFontScaling | property

`applyNonLinearFontScaling:Boolean` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies that you want to enhance screen appearance at the expense of what-you-see-is-what-you-get (WYSIWYG) print fidelity. For platforms and fonts that support non linear scaling, setting this property to true enables use of those metrics at some cost to WYSIWYG print fidelity, particularly for small point sizes.

The default value is `true`.

Implementation
`public function get applyNonLinearFontScaling():Boolean`
`public function set applyNonLinearFontScaling(value:Boolean):void`

baselineFontDescription | property |

`baselineFontDescription:FontDescription` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The font used to determine the baselines for all the lines broken from the block, independent of their content. Baselines depend on font and font size.

The default value is `null`. When the baseline font is `null`, the baseline font size is ignored and the baselines for any given line is based on the font and size of the largest text in the line. When you specify both `baselineFontDescription` and `baselineFontSize`, they determine the baselines for all the lines in the text block, independent of their content. This combination is most often useful in Asian typography.

Implementation
`public function get baselineFontDescription():FontDescription`
`public function set baselineFontDescription(value:FontDescription):void`

See also

baselineFontSize
FontDescription

baselineFontSize | property |

`baselineFontSize:Number` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The font size used to calculate the baselines for the lines broken from the block. Baselines depend on font and font size.

The default value is `12`. When the baseline font is `null`, the baseline font size is ignored and the baselines for any given line is based on the font and size of the largest text in the line.

Implementation
`public function get baselineFontSize():Number`
`public function set baselineFontSize(value:Number):void`
Throws

| `ArgumentError` — The `baselineFontSize` specified is less than 0.

See also

baselineFontDescription
FontDescription

baselineZero | property |

`baselineZero:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies which baseline is at y=0 for lines broken from this block. Valid values for this property are found in the members of the `TextBaseline` class.

The default value is `TextBaseline.ROMAN`.

To set values for this property, use the following string values:

String value | Description
--- | ---
`TextBaseline.ROMAN` | The roman baseline of the lines is at y=0.
`TextBaseline.SUPERSCRIPT` | The superscript baseline of the lines is at y=0.
`TextBaseline.SUBSCRIPT` | The subscript baseline of the lines is at y=0.
`TextBaseline.ASCENT` | The ascent baseline of the lines is at y=0.
`TextBaseline.DESCENT` | The descent baseline of the lines is at y=0.
`TextBaseline.IDEOGRAPHIC_TOP` | The ideographic top baseline of the lines is at y=0.
`TextBaseline.IDEOGRAPHIC_CENTER` | The ideographic center baseline of the lines is at y=0.
`TextBaseline.IDEOGRAPHIC_BOTTOM` | The ideographic bottom baseline of the lines is at y=0.

Implementation
`public function get baselineZero():String`
`public function set baselineZero(value:String):void`
Throws

| `ArgumentError` — If set to any value which is not a member of `TextBaseline`.

See also

TextBaseline

bidiLevel | property |

`bidiLevel:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the default bidirectional embedding level of the text in the text block. An even value means left-to-right and an odd value means right-to-left. You can increment `bidiLevel` to indicate the number of levels by which particular text is embedded with respect to left-to-right and right-to-left.

The default value is 0.

Modifying `bidiLevel` changes the validity of all previously broken lines to TextLineValidity.INVALID. After changing `bidiLevel`, the `firstInvalidLine` property equals the `firstLine` property, and you must rebreak all the lines in the TextBlock.

Implementation
`public function get bidiLevel():int`
`public function set bidiLevel(value:int):void`
Throws

| `ArgumentError` — If set to a value which is less than 0.

Example
This example shows the same text string (logical order: a, b, c, alef, bet, gimel) rendered first with `bidiLevel` even and second with bidiLevel odd.

    package {

        import flash.display.Sprite;
        import flash.text.engine.TextBlock;
        import flash.text.engine.TextElement;
        import flash.text.engine.TextLine;
        import flash.text.engine.ElementFormat;
        import flash.text.engine.FontDescription;

        public class TextBlock_bidiLevelExample extends Sprite {

            public function TextBlock_bidiLevelExample():void {
                var fontSize:Number = 36;

                var format:ElementFormat = new ElementFormat();
                format.fontDescription = new FontDescription("Adobe Hebrew");
                format.fontSize = fontSize;
                var y:Number = 0;
                var leading:Number = fontSize * 0.2;
                var text:String = "abc" + String.fromCharCode(0x05D0, 0x05D1, 0x05D2);

                var textBlock:TextBlock = new TextBlock();
                textBlock.content = new TextElement(text, format);

                // bidi level even
                textBlock.bidiLevel = 0;
                var textLine = textBlock.createTextLine(null, 400);
                y += leading + textLine.ascent;
                textLine.y = y;
                y += textLine.descent;
                addChild(textLine);

                // bidi level odd
                textBlock.content = new TextElement(text, format);
                textBlock.bidiLevel = 1;
                textLine = textBlock.createTextLine(null, 400);
                y += leading + textLine.ascent;
                textLine.y = y;
                addChild(textLine);
            }
        }
    }

content | property |

`content:ContentElement` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Holds the contents of the text block. Because ContentElement is a base class, assign `content` an instance of a ContentElement subclass: TextElement, GraphicElement, or GroupElement. A TextElement object contains a String, a GraphicElement object contains a DisplayObject, and a GroupElement contains a Vector object that contains one or more TextElement, GraphicElement, or other GroupElement objects. Use a TextElement for a paragraph of homogenous text, a GraphicElement for a graphic, and a GroupElement for a combination of text and graphic elements or multiples instances of these elements, as well as other GroupElement objects.

The default value is `null`

Modifying the `content` property changes the validity of all previously broken lines to `TextLineValidity.INVALID`. After changing `content`, the `firstInvalidLine` property equals the `firstLine` property and you must rebreak all lines in the TextBlock.

Implementation
`public function get content():ContentElement`
`public function set content(value:ContentElement):void`
Throws

| `ArgumentError` — If set to a value which is not a known subclass of `ContentElement`.
| `ArgumentError` — The `value` specified is already a member of a group.

firstInvalidLine | property |

`firstInvalidLine:TextLine` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Identifies the first line in the text block in which `TextLine.validity` is not equal to `TextLineValidity.VALID`.

The default value is null.

Implementation
`public function get firstInvalidLine():TextLine`

See also

TextLine

firstLine | property |

`firstLine:TextLine` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The first TextLine in the TextBlock, if any.

The default value is null.

Implementation
`public function get firstLine():TextLine`

See also

TextLine

glyphRotation | property |

`glyphRotation:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies automatic glyph rotation based on Unicode code point. When this property is set to true, individual glyphs that need to be rotated to display properly in vertical text are rotated. This is equivalent to setting `ElementFormat.textRotation` by hand, but the automatic system is easier and more reliable.

This property works in conjunction with `lineRotation`

The default value is false.

The final rotation of any glyph is the sum of TextBlock.glyphRotation, ElementFormat.textRotation, ContentElement.textRotation, and TextBlock.lineRotation.

Implementation
`public function get glyphRotation():String`
`public function set glyphRotation(value:String):void`

See also

ContentElement.textRotation
ElementFormat.textRotation
lineRotation
TextRotation

lastLine | property |

`lastLine:TextLine` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The last TextLine in the TextBlock, if any.

The default value is null.

Implementation
`public function get lastLine():TextLine`

See also

TextLine

lineRotation | property |

`lineRotation:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Rotates the text lines in the text block as a unit. Call the `createTextLine()` method after setting `lineRotation` for it to take effect. The default value is `TextRotation.ROTATE_0`.

This property works in conjunction with `glyphRotation`. The final rotation of any glyph depends on the values of `TextBlock.glyphRotation`, `ElementFormat.textRotation`, `ContentElement.textRotation`, and `TextBlock.lineRotation`.

`TextBlock.lineRotation` is usually used for Asian text. To create a paragraph of vertical Japanese text, do the following:

1. Set the `TextBlock.glyphRotation` property to `GlyphRotation.FULL_AND_WIDE`.
2. Set the `TextBlock.lineRotation` property to `TextRotation.ROTATE_90`.

Use the following constants, which are defined in the `TextRotation` class, to set the value for this property:

String value | Description
--- | ---
`TextRotation.ROTATE_0` | Lines are not rotated.
`TextRotation.ROTATE_90` | Lines are rotated 90 degrees clockwise.
`TextRotation.ROTATE_180` | Lines are rotated 180 degrees.
`TextRotation.ROTATE_270` | Lines are rotated 270 degrees clockwise.

Implementation
`public function get lineRotation():String`
`public function set lineRotation(value:String):void`
Throws

| `ArgumentError` — If set to any value which is not a member of `TextRotation`.

See also

ContentElement.textRotation
ElementFormat.textRotation
glyphRotation
TextLine
TextRotation
Example
This example adds a line of text to a TextBlock and sets the `lineRotation()` property to TextRotation.ROTATE_90 to display the line vertically.

    package {
        import flash.display.Sprite;
        import flash.text.engine.FontDescription;
        import flash.text.engine.GlyphRotation;
        import flash.text.engine.TextBlock;
        import flash.text.engine.TextElement;
        import flash.text.engine.TextLine;
        import flash.text.engine.TextRotation;
        import flash.text.engine.ElementFormat;

        public class TextBlock_lineRotationExample extends Sprite {

            public function TextBlock_lineRotationExample():void {
                var str:String = "lineRotation = flash.text.TextRotation.ROTATE_90";
                var fontDescription:FontDescription = new FontDescription("MS Mincho");
                var format:ElementFormat = new ElementFormat();
                format.fontSize = 15;
                format.fontDescription = fontDescription;

                var textElement:TextElement = new TextElement(str, format);
                var textBlock:TextBlock = new TextBlock();
                textBlock.content = textElement;
                textBlock.glyphRotation = GlyphRotation.FULL_AND_WIDE;
                textBlock.lineRotation = TextRotation.ROTATE_90;

                var textLine:TextLine = textBlock.createTextLine(null,500);
                addChild(textLine);
                textLine.y = 10;
                textLine.x = 60;
            }
        }
    }

tabStops | property |

`tabStops:Vector` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the tab stops for the text in the text block, in the form of a Vector of `TabStop` objects.

The default value is `null`, which means no tab stops are enabled.

Modifying the contents of the tabStops Vector does not cause the text engine to mark the content of the text block invalid. Setting the tabStops Vector will.

Implementation
`public function get tabStops():Vector`
`public function set tabStops(value:Vector):void`
Throws

| `ArgumentError` — The `tabStops` specified contain `null` elements.
| `ArgumentError` — The `tabStops` specified are not sorted by increasing position.

See also

TabStop

textJustifier | property |

`textJustifier:TextJustifier` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the TextJustifier to use during line breaking.

The default value is a constructed default TextJustifier object.

Implementation
`public function get textJustifier():TextJustifier`
`public function set textJustifier(value:TextJustifier):void`
Throws

| `ArgumentError` — If set to a value which is not a known subclass of `TextJustifier`.

See also

TextJustifier

textLineCreationResult | property |

`textLineCreationResult:String` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Indicates the result of a `createTextLine` operation. Changing the content of the block invalidates previously broken lines and resets this property to `null`.

The default value is `null`.

Values for this property are found in `TextLineCreationResult`

String value | Description
--- | ---
`TextLineCreationResult.SUCCESS` | The line was successfully broken.
`TextLineCreationResult.COMPLETE` | Either the new line created aligned perfectly with following lines which have transitioned from POSSIBLY_INVALID to VALID, or no line was created because all text in the block had already been broken.
`TextLineCreationResult.INSUFFICIENT_WIDTH` | No line was created because no text could fit in the specified width.

Implementation
`public function get textLineCreationResult():String`

See also

TextLineCreationResult

userData | property |

`public var userData:*`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Provides a way for the author to associate arbitrary data with the text block. It could be information that refers to the content, for example, a revision date, or the author's name, or it could be cached data that is required during processing.

Constructor Detail

TextBlock | () | Constructor

`public function TextBlock(content:ContentElement = null, tabStops:Vector = null, textJustifier:TextJustifier = null, glyphRotation:String = "none", lineRotation:String = "rotate0", baselineZero:String = "roman", bidiLevel:int = 0, applyNonLinearFontScaling:Boolean = true, baselineFontDescription:FontDescription = null, baselineFontSize:Number = 12.0)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates a TextBlock object

Parameters

| `content:ContentElement` (default = `null`)`` — The contents of the text block.
| `tabStops:Vector` (default = `null`)`` — The tab stops for the text in the text block.
| `textJustifier:TextJustifier` (default = `null`)`` — The TextJustifier object to use during line breaking for this block. If no justifier is provided, a default justifier is constructed based on an English locale.
| `glyphRotation:String` (default = "`none`")`` — Specifies automatic glyph rotation based on Unicode code point.
| `lineRotation:String` (default = "`rotate0`")`` — The rotation applied to the text lines generated from the text block as units.
| `baselineZero:String` (default = "`roman`")`` — Specifies which baseline is at y=0 for all lines in the block.
| `bidiLevel:int` (default = `0`)`` — The default bidirectional embedding level of the text in the text block.
| `applyNonLinearFontScaling:Boolean` (default = `true`)`` — Specifies that you want to enhance screen appearance at the expense of WYSIWYG print fidelity.
| `baselineFontDescription:FontDescription` (default = `null`)`` — Specifies a font description from which to derive line baselines for all lines in the block.
| `baselineFontSize:Number` (default = `12.0`)`` — Specifies the size to use with the baselineFontDescription. This parameter is ignored if `baselineFontDescription` is `null`.

Throws

| `ArgumentError` — The `content` specified is not a known subclass of `ContentElement`.
| `ArgumentError` — The `content` specified is already a member of a group.
| `ArgumentError` — The `glyphRotation` specified is not a member of `GlyphRotation`.
| `ArgumentError` — The `lineRotation` specified is not a member of `TextRotation`.
| `ArgumentError` — The `baselineZero` specified is not a member of `TextBaseline`.
| `ArgumentError` — The `bidiLevel` specified is less than 0.
| `ArgumentError` — The `tabStops` specified contain `null` elements.
| `ArgumentError` — The `tabStops` specified are not sorted by increasing position.
| `ArgumentError` — The `baselineFontSize` specified is less than 0.

See also

applyNonLinearFontScaling
baselineFontDescription
baselineFontSize
baselineZero
bidiLevel
glyphRotation
lineRotation
tabStops
TextJustifier
Method Detail

createTextLine | () | method

`public function createTextLine(previousLine:TextLine = null, width:Number = 1000000, lineOffset:Number = 0.0, fitSomething:Boolean = false):TextLine`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Instructs the text block to create a line of text from its content, beginning at the point specified by the `previousLine` parameter and breaking at the point specified by the `width` parameter. The text line is a TextLine object, which you can add to the display list.

Breaking lines over a range of a text block that has already been broken can change the validity of lines in and beyond the area where breaking takes place. The status of lines can change from VALID to INVALID or POSSIBLY_INVALID. If a newly broken line aligns perfectly with a previously broken line which has a status of POSSIBLY_INVALID, that previously broken line and all following POSSIBLY_INVALID lines change back to a status of VALID. The validity of lines which have been set to values which are not members of `TextLineValidity` will not be changed to VALID, but might be changed to INVALID. Check the `firstInvalidLine` property after any change to the text block to see where to begin or continue re-breaking text lines.

You can create artificial word breaks by including the Unicode Zero Width Space (ZWSP) character in the text. This can be useful for languages such as Thai, which require a dictionary for correct line breaking. Flash Player does not include such a dictionary.

Parameters

| `previousLine:TextLine` (default = `null`)`` — Specifies the previously broken line after which breaking is to commence. Can be `null` when breaking the first line.
| `width:Number` (default = `1000000`)`` — Specifies the desired width of the line in pixels. The actual width might be less.
| `lineOffset:Number` (default = `0.0`)`` — An optional parameter which specifies the difference in pixels between the origin of the line and the origin of the tab stops. This can be used when lines are not aligned, but it is desirable for their tabs to be so. The default value for this parameter is `0.0`.
| `fitSomething:Boolean` (default = `false`)`` — An optional parameter which instructs Flash Player to fit at least one character into the text line, no matter what width has been specified (even if width is zero or negative, which would otherwise result in an exception being thrown).

Returns

| `TextLine` — A text line, or `null` if the text block is empty or the width specified is less than the width of the next element. To distinguish between these cases, check the `textLineCreationResult` property of the text block.

Throws

| `ArgumentError` — If the TextLine specified by `previousLine` is not valid.
| `ArgumentError` — If `width` is less than zero, unless `fitSomething` is true.
| `ArgumentError` — if `width` is greater than `TextLine.MAX_LINE_WIDTH`.
| `IllegalOperationError` — if one or more elements in the content of the text block has a `null ElementFormat`.

See also

TextBaseline
TextLine
TextLineValidity
Example
This example calls the `createTextLine()` method to create lines of text in a text block. It accomplishes this by performing the following tasks:

- Create a TextElement (`txt`) from a String and gives it a font size of 20
- Create a TextBlock and assigns the TextElement (`txt`) to it
- Call `createTextLine()` to create lines 300 pixels wide from the text block
- Place each line on Stage (`addChild()`) and set its position (`x` and `y`)

    package {
        import flash.display.Sprite;
        import flash.text.engine.TextBlock;
        import flash.text.engine.TextElement;
        import flash.text.engine.TextLine;
        import flash.text.engine.ElementFormat;
        import flash.text.engine.FontDescription;

        public class TextBlock_createTextLineExample extends Sprite {

            public function TextBlock_createTextLineExample():void {
                var str:String = "I am a TextElement, created from a String and assigned " +
                "to the content property of a TextBlock. The createTextLine() method " +
                "then created these lines, 300 pixels wide, for display." ;
                var fontDescription:FontDescription = new FontDescription("Arial");
                var format:ElementFormat = new ElementFormat(fontDescription);
                format.fontSize = 16;
                var textElement:TextElement = new TextElement(str, format);
                var textBlock:TextBlock = new TextBlock();
                textBlock.content = textElement;
                createLines(textBlock);
            }
            public function createLines(textBlock:TextBlock):void
            {
                var lineWidth:Number = 300;
                var xPos:Number = 15.0;
                var yPos:Number = 20.0;

                var textLine:TextLine = textBlock.createTextLine (null, lineWidth);
                while (textLine)
                {
                    textLine.x = xPos;
                    textLine.y = yPos;
                    yPos += textLine.height + 2;
                    addChild (textLine);
                    textLine = textBlock.createTextLine (textLine, lineWidth);
                }
            }
        }
    }

dump | () | method |

`public function dump():String`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Dumps the underlying contents of the TextBlock as an XML string. This can be useful in automated testing, and includes text, formatting, and rendering information. It is only available in the debugger Flash Player.

Note: The content and format of the output might change in the future. Adobe does not guarantee backward compatibility of this method.

The following table describes the output:

Tag | Attribute | Description
--- | --- | ---
`<block>` |  | TextBlock
`<line` |  | TextLine
| `s=` | start inline run element
| `l=` | limit inline run element
`>` |  | close of line tag
`<run` |  | The elements of a line
| `s=` | start inline run element
| `l=` | limit inline run element
`>` |  | close of run tag
`<inter` |  | inter element
| `cursor=` | character cursor (index into the original text)
| `tcb=` | typographic cluster boundary
| `wb=` | word boundary
| `lbo=` | line break opportunity
| `lb=` | actual line break
`/>` |  | end of inter tag
`<char` |  | Character element
| `usv=` | Unicode scalar value
`/>` |  | end of char tag
`<glyph` |  | Computed glyph or shaped glyph element
| `font=` | font name
| `gid=` | glyph index
| `xa=` | xAdvance
| `ya=` | yAdvance
| `xp=` | xPlacement
| `yp=` | yPlacement
| `r=` | rotation
| `color=` | color
| `xP=` | xPosition
| `yP=` | yPosition
| `attached=` | whether two elements are attached
| `itcbo=` | internal typographic cluster boundary offsets
| `bl=` | bidirectional level
| `sc=` | spacing class
`/>` |  | end of glyph tag
`<fo` |  | graphic element
| `id=` | element id
| `xa=` | xAdvance
| `ya=` | yAdvance
| `xp=` | xPlacement
| `yp=` | yPlacement
| `r=` | rotation
| `color=` | color
| `xP=` | xPosition
| `yP=` | yPosition
| `lb=` | left bound
| `rb=` | right bound
| `tb=` | top bound
| `bb=` | bottom bound
| `itcbo=` | internal typographic cluster boundary offsets
| `bl=` | bidirectional level
| `sc=` | spacing class
`/>` |  | end of fo tag
`<embeddedRun` |  | embedded run
| `xa=` | xAdvance
| `ya=` | yAdvance
| `xp=` | xPlacement
| `yp=` | yPlacement
| `r=` | rotation
| `xP=` | xPosition
| `yP=` | yPosition
`>` |  | close of embeddedRun tag
`<run>` |  | run
`</run>` |  | ending run tag
`</embeddedRun>` |  | ending embeddedRun tag
`<carets` |  | the carets of a line
| `s=` | start inline run element
| `l=` | limit inline run element
`>` |  | close of carets tag
`<cursor>` |  | cursor
| `x=` | left side x position
`/>` |  | end of cursor tag
`<cluster` |  | cluster
| `c=` | center position
| `s=` | start tc offset
| `l=` | limit tc offset
| `bidi` | bidirectional level
`/>` |  | end of cluster tag
`</carets>` |  | ending carets tag
`</line>` |  | ending line tag
`</block>` |  | ending block tag

Returns

| `String`

See also

TextLine

findNextAtomBoundary | () | method |

`public function findNextAtomBoundary(afterCharIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Finds the index of the next Atom boundary from the specified character index, not including the character at the specified index. The characters between atom boundaries combine to form one atom in a `TextLine`, such as an 'e' and a combining acute accent.

Parameters

| `afterCharIndex:int` — Specifies the index of the character from which to search for the next atom boundary.

Returns

| `int` — The index of the next atom boundary from the specified character index.

Throws

| `RangeError` — The `index` specified is out of range.
| `IllegalOperationError` — The TextLine to which the indexed character belongs is not valid.

See also

TextLine.atomCount

findNextWordBoundary | () | method |

`public function findNextWordBoundary(afterCharIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Finds the index of the next word boundary from the specified character index, not including the character at the specified index. Word boundaries are determined based on the Unicode properties of the characters.

Parameters

| `afterCharIndex:int` — Specifies the index of the character from which to search for the next word boundary.

Returns

| `int` — The index of the next word boundary from the specified character index.

Throws

| `RangeError` — The `index` specified is out of range.
| `IllegalOperationError` — The TextLine to which the indexed character belongs is not valid.

findPreviousAtomBoundary | () | method |

`public function findPreviousAtomBoundary(beforeCharIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Finds the index of the previous atom boundary to the specified character index, not including the character at the specified index. The characters between atom boundaries combine to form one atom in a `TextLine`, such as an 'e' and a combining acute accent.

Parameters

| `beforeCharIndex:int` — Specifies the index of the character from which to search for the previous atom boundary.

Returns

| `int` — The index of the previous atom boundary to the specified character index.

Throws

| `RangeError` — The `index` specified is out of range.
| `IllegalOperationError` — The TextLine to which the indexed character belongs is not valid.

See also

TextLine.atomCount

findPreviousWordBoundary | () | method |

`public function findPreviousWordBoundary(beforeCharIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Finds the index of the previous word boundary to the specified character index, not including the character at the specified index. Word boundaries are determined based on the Unicode properties of the characters.

Parameters

| `beforeCharIndex:int` — Specifies the index of the character from which to search for the previous word boundary.

Returns

| `int` — The index of the previous word boundary to the specified character index.

Throws

| `RangeError` — The `index` specified is out of range.
| `IllegalOperationError` — The TextLine to which the indexed character belongs is not valid.

getTextLineAtCharIndex | () | method |

`public function getTextLineAtCharIndex(charIndex:int):TextLine`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the TextLine containing the character specified by the `charIndex` parameter.

Parameters

| `charIndex:int` — The zero-based index value of the character (for example, the first character is 0, the second character is 1, and so on).

Returns

| `TextLine` — The TextLine containing the character at `charIndex`

Throws

| `RangeError` — The character index specified is out of range.

releaseLines | () | method |

`public function releaseLines(firstLine:TextLine, lastLine:TextLine):*`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Removes a range of text lines from the list of lines maintained by the TextBlock. This allows the lines to be garbage-collected if no other references exist.

Sets the `textBlock`, `nextLine`, and `previousLine` members of the removed lines to `null`. Sets the `validity` of the removed lines and of all lines which follow the removed lines in the TextBlock to `TextLineValidity.INVALID`.

Parameters

| `firstLine:TextLine` — Specifies the first line to be released.
| `lastLine:TextLine` — Specifies the last line to be released.

Returns

| `*`

Throws

| `ArgumentError` — If the TextLine specified by `firstLine` or `lastLine` is not in the list of text lines maintained by the text block.

See also

TextLine
Examples How to use examples
TextBlockExample.as
This example displays four TextBlock paragraphs of English and Japanese text. The Japanese text is converted to Strings from Unicode character codes. When you click on the stage, the example rotates the text from horizontal to vertical or from veritcal to horizontal.

    package {
         import flash.text.engine.TextBlock;
        import flash.text.engine.TextLine;
        import flash.text.engine.TextElement;
        import flash.text.engine.ElementFormat;
        import flash.text.engine.TextRotation;
        import flash.text.engine.TextBaseline;
        import flash.text.engine.LineJustification;
        import flash.text.engine.GlyphRotation;
        import flash.text.engine.FontDescription;
        import flash.text.engine.EastAsianJustifier;
        import flash.display.Loader;
        import flash.display.Sprite;
        import flash.display.Stage;
        import flash.events.MouseEvent;
        import flash.system.Capabilities;

        public class TextBlockExample extends Sprite {

            var vertical:Boolean;
            var container:Sprite;
            var textBlocks:Vector.<TextBlock>;
            var loader:Loader = new Loader();

            public function TextBlockExample():void {
                createContent();
                createLines();
                parent.addEventListener(MouseEvent.CLICK, clickHandler);
            }

            private function createEmptyBlock():TextBlock {

                var textBlock:TextBlock = new TextBlock();
                textBlock.baselineZero = TextBaseline.IDEOGRAPHIC_CENTER;
                textBlock.textJustifier = new EastAsianJustifier("ja", LineJustification.ALL_BUT_LAST);
                textBlock.lineRotation = vertical? TextRotation.ROTATE_90: TextRotation.ROTATE_0;
                if (vertical)
                    textBlock.glyphRotation = GlyphRotation.FULL_AND_WIDE
                else
                    textBlock.glyphRotation = GlyphRotation.NONE;
                return textBlock;
            }

            private function paragraph0(format:ElementFormat):TextBlock {

                var textBlock:TextBlock = createEmptyBlock();
                if(!vertical)
                {
                    textBlock.content = new TextElement(
                    "Click anywhere on the stage to rotate text to vertical", format);
                }
                else
                {
                    textBlock.content = new TextElement(
                    "Click anywhere on the stage to rotate text to horizontal", format);
                    textBlock.glyphRotation = GlyphRotation.NONE;
                }
                return textBlock;
            }

            private function paragraph1(format:ElementFormat):TextBlock {

                var textBlock:TextBlock = createEmptyBlock();
                textBlock.content = new TextElement(
                String.fromCharCode(
                    0x5185, 0x95A3, 0x5E9C, 0x304C, 0x300C, 0x653F, 0x5E9C, 0x30A4,
                    0x30F3, 0x30BF, 0x30FC, 0x30CD, 0x30C3, 0x30C8, 0x30C6, 0x30EC,
                    0x30D3, 0x300D, 0x306E, 0x52D5, 0x753B, 0x914D, 0x4FE1, 0x5411,
                    0x3051, 0x306B, 0x30A2, 0x30C9, 0x30D3, 0x30B7, 0x30B9, 0x30C6,
                    0x30E0, 0x30BA, 0x793E, 0x306E
                ) +
                "FMS 2" +
                String.fromCharCode(0x3092, 0x63A1, 0x7528, 0x30E0, 0x30BA),
                format);

                return textBlock;
            }

            private function paragraph2(format:ElementFormat):TextBlock {
                var textBlock:TextBlock = createEmptyBlock();
                textBlock.content = new TextElement(
                String.fromCharCode(
                    0x30AF, 0x30ED, 0x30B9, 0x30D7, 0x30E9, 0x30C3, 0x30C8, 0x30D5,
                    0x30A9, 0x30FC, 0x30E0, 0x4E0A, 0x3067, 0x518D, 0x751F, 0x53EF,
                    0x80FD, 0x306A
                ) +
                "Flash Video" +
                String.fromCharCode(
                    0x3092, 0x914D, 0x4FE1, 0x3001, 0x653F, 0x5E9C, 0x6700, 0x65B0,
                    0x60C5, 0x5831, 0x3092, 0x3088, 0x308A, 0x591A, 0x304F, 0x306E,
                    0x56FD, 0x6C11, 0x306B, 0x9AD8, 0x54C1, 0x8CEA, 0x306A, 0x753B,
                    0x50CF, 0x3092, 0x7C21, 0x5358, 0x304B, 0x3064, 0x30EA, 0x30A2,
                    0x30EB, 0x30BF, 0x30A4, 0x30E0, 0x306B, 0x63D0, 0x4F9B, 0x3059,
                    0x308B, 0x3053, 0x3068, 0x304C, 0x53EF, 0x80FD, 0x306B
                ),    format);
                return textBlock;
            }

            private function paragraph3(format:ElementFormat):TextBlock {
                var textBlock:TextBlock = createEmptyBlock();
                textBlock.content = new TextElement(
                String.fromCharCode(0x3010) +
                "2007" +
                String.fromCharCode(0x5E74, 0xFF12, 0x6708) +
                "21" +
                String.fromCharCode(0x65E5, 0x3011),
                format);

                return textBlock;
            }

            // Create new content
            private function createContent():void {
                var font:FontDescription = new FontDescription();
                if (Capabilities.os.search("Mac OS") > -1)
                    font.fontName = String.fromCharCode(0x5C0F, 0x585A, 0x660E, 0x671D) + " Pro R"; // "Kozuka Mincho Pro R"                    koFont.fontName = "Adobe " + String.fromCharCode(0xBA85, 0xC870) + " Std M"; // "Adobe Myungjo Std M"
                else
                    font.fontName = "Kozuka Mincho Pro R";
                var blackFormat:ElementFormat = new ElementFormat();
                blackFormat.fontDescription = font;
                blackFormat.fontSize = 12;
                blackFormat.locale = "ja";
                blackFormat.color = 0x000000;
                var redFormat:ElementFormat = new ElementFormat();
                redFormat.color = 0xCC0000;

                textBlocks = new Vector.<TextBlock>();
                textBlocks.push(
                    paragraph0(redFormat),
                    paragraph1(blackFormat),
                    paragraph2(blackFormat),
                    paragraph3(blackFormat)//,
                );
            }

            private function createLines():void {
                if (container != null) {
                    removeChild(container);
                }

                container = new Sprite();
                container.y = 45;
                container.x = 40;
                addChild(container);
                var baseline:Number = vertical? this.stage.stageWidth - 12: 12;

                for (var i:uint = 0; i < textBlocks.length; i++) {
                    var textBlock:TextBlock = textBlocks[i];
                    var previousLine:TextLine = null;

                    while (true) {
                        var textLine:TextLine = textBlock.createTextLine(
                            previousLine,
                            300);
                        if (textLine == null)
                            break;
                        if (vertical)
                        {
                            textLine.x = baseline-120;//baseline-120;
                            baseline -= 24;
                        }
                        else
                        {
                            textLine.y = baseline+50;
                            baseline += 24;
                        }
                        container.addChild(textLine);
                        previousLine = textLine;
                    }
                    if (vertical)
                        baseline -= 16;
                    else
                        baseline += 16;
                }
            }

            // Toggle horizontal/vertical on mouse click
            private function clickHandler(event:MouseEvent):void {
                vertical = !vertical;
                createContent();
                createLines();
            }
        }
    }

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