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

Package | flash.text.engine
Class | public final class TextLine
Inheritance | TextLine DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The TextLine class is used to display text on the display list.

You cannot create a TextLine object directly from ActionScript code. If you call `new TextLine()`, an exception is thrown. To create a TextLine object, call the `createTextLine()` method of a TextBlock.

The TextLine encapsulates the minimum information necessary to render its contents. You can retrieve additional information that is useful for interactivity through some methods that describe the properties of the atoms of the line. The term atom refers to both graphic elements and characters (including groups of combining characters), the indivisible entities that make up a text line. It is important to note that the player does not create or store the data that these methods require.until you call them. To avoid memory overhead, avoid creating atom data unnecessarily. If the atom data is no longer needed, call the `flushAtomData()` method to make it available for garbage collection.

The following methods and properties generate atom data if it does not exist:

- `atomCount`
- `getAtomBidiLevel()`
- `getAtomBounds()`
- `getAtomCenter()`
- `getAtomIndexAtCharIndex()`
- `getAtomIndexAtPoint()`
- `getAtomGraphic()`
- `getAtomTextBlockBeginIndex()`
- `getAtomTextBlockEndIndex()`
- `getAtomTextRotation()`
- `getAtomWordBoundaryOnLeft()`

Unlike other interactive objects, a text line cannot be tab enabled. Attempting to set `tabEnabled`, `tabIndex`, or `tabChildren` on a `TextLine` object results in an `ArgumentError` being thrown. It is up to the container that owns the text line to manage tabbing.

Similarly, a text line cannot have a focus rect. The value of `TextLine.focusRect` is ignored.

After the normal event dispatching process for a text line has completed, if event propagation has not failed or been stopped, events targeted at the text line will be mirrored to the event dispatchers specified in the `eventMirror` members of the `ContentElement` objects which contributed to the text line, as recorded in the `eventMirrors` member of the line. For mouse events, the mouse coordinates of the event are compared to the bounds of each mirror region, and the event is only dispatched if the event is in the mirror region bounds. All other events will be dispatched to all mirrors on the line.

The origin of a text line object is the beginning of the baseline. If you add a text line containing Latin text on a Roman baseline as a child of a Sprite, without setting the `y` property (vertical position) of the line, all but the descenders of your text will be above the top of the Sprite. See the following diagram:

View the examples

See also

TextBlock
ContentElement.eventMirror

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | accessibilityProperties : AccessibilityProperties The current accessibility options for this display object. | DisplayObject
|  | alpha : Number Indicates the alpha transparency value of the object specified. | DisplayObject
|  | ascent : Number [read-only] Specifies the number of pixels from the baseline to the top of the tallest characters in the line. | TextLine
|  | atomCount : int [read-only] The number of atoms in the line, which is the number of indivisible elements, including spaces and graphic elements. | TextLine
|  | blendMode : String A value from the BlendMode class that specifies which blend mode to use. | DisplayObject
|  | cacheAsBitmap : Boolean If set to true, Flash Player caches an internal bitmap representation of the display object. | DisplayObject
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | contextMenu : ContextMenu Specifies the context menu associated with this object. | InteractiveObject
|  | descent : Number [read-only] Specifies the number of pixels from the baseline to the bottom of the lowest-descending characters in the line. | TextLine
|  | doubleClickEnabled : Boolean Specifies whether the object receives doubleClick events. | InteractiveObject
|  | filters : Array An indexed array that contains each filter object currently associated with the display object. | DisplayObject
|  | focusRect : Object Specifies whether this object displays a focus rectangle. | InteractiveObject
|  | hasGraphicElement : Boolean [read-only] Indicates whether the text line contains any graphic elements. | TextLine
|  | height : Number Indicates the height of the display object, in pixels. | DisplayObject
|  | loaderInfo : LoaderInfo [read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs. | DisplayObject
|  | mask : DisplayObject The calling display object is masked by the specified mask object. | DisplayObject
|  | mirrorRegions : Vector [read-only] A Vector containing the TextLineMirrorRegion objects associated with the line, or null if none exist. | TextLine
|  | mouseChildren : Boolean Determines whether or not the children of the object are mouse enabled. | DisplayObjectContainer
|  | mouseEnabled : Boolean Specifies whether this object receives mouse messages. | InteractiveObject
|  | mouseX : Number [read-only] Indicates the x coordinate of the mouse position, in pixels. | DisplayObject
|  | mouseY : Number [read-only] Indicates the y coordinate of the mouse position, in pixels. | DisplayObject
|  | name : String Indicates the instance name of the DisplayObject. | DisplayObject
|  | nextLine : TextLine [read-only] The next TextLine in the TextBlock, or null if this is the last line in the block or the validity of the line is TextLineValidity.STATIC. | TextLine
|  | numChildren : int [read-only] Returns the number of children of this object. | DisplayObjectContainer
|  | opaqueBackground : Object Specifies whether the display object is opaque with a certain background color. | DisplayObject
|  | parent : DisplayObjectContainer [read-only] Indicates the DisplayObjectContainer object that contains this display object. | DisplayObject
|  | previousLine : TextLine [read-only] The previous TextLine in the TextBlock, or null if the line is the first line in the block or the validity of the line is TextLineValidity.STATIC. | TextLine
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | rawTextLength : int [read-only] The length of the raw text in the text block that became the line, including the U+FDEF characters representing graphic elements and any trailing spaces, which are part of the line but not actually displayed. | TextLine
|  | root : DisplayObject [read-only] For a display object in a loaded SWF file, the root property is the top-most display object in the portion of the display list's tree structure represented by that SWF file. | DisplayObject
|  | rotation : Number Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation. | DisplayObject
|  | scale9Grid : Rectangle The current scaling grid that is in effect. | DisplayObject
|  | scaleX : Number Indicates the horizontal scale (percentage) of the object as applied from the registration point. | DisplayObject
|  | scaleY : Number Indicates the vertical scale (percentage) of an object as applied from the registration point of the object. | DisplayObject
|  | scrollRect : Rectangle The scroll rectangle bounds of the display object. | DisplayObject
|  | specifiedWidth : Number [read-only] The width specified to the TextBlock.createTextLine() method when it created the line. | TextLine
|  | stage : Stage [read-only] The Stage of the display object. | DisplayObject
|  | tabChildren : Boolean Determines whether the children of the object are tab enabled. | DisplayObjectContainer
|  | tabEnabled : Boolean Specifies whether this object is in the tab order. | InteractiveObject
|  | tabIndex : int Specifies the tab ordering of objects in a SWF file. | InteractiveObject
|  | textBlock : TextBlock [read-only] The TextBlock containing this text line, or null if the validity of the line is TextLineValidity.STATIC. | TextLine
|  | textBlockBeginIndex : int [read-only] The index of the first character of the line in the raw text of the text block. | TextLine
|  | textHeight : Number [read-only] The logical height of the text line, which is equal to ascent + descent. | TextLine
|  | textSnapshot : TextSnapshot [read-only] Returns a TextSnapshot object for this DisplayObjectContainer instance. | DisplayObjectContainer
|  | textWidth : Number [read-only] The logical width of the text line, which is the width that the text engine uses to lay out the line. | TextLine
|  | transform : Transform An object with properties pertaining to a display object's matrix, color transform, and pixel bounds. | DisplayObject
|  | unjustifiedTextWidth : Number [read-only] The width of the line if it was not justified. | TextLine
|  | userData : * Provides a way for the author to associate arbitrary data with the text line. | TextLine
|  | validity : String Specifies the current validity of the text line. | TextLine
|  | visible : Boolean Whether or not the display object is visible. | DisplayObject
|  | width : Number Indicates the width of the display object, in pixels. | DisplayObject
|  | x : Number Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject
|  | y : Number Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer. | DisplayObject

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addChild(child:DisplayObject):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addChildAt(child:DisplayObject, index:int):DisplayObject Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | areInaccessibleObjectsUnderPoint(point:Point):Boolean Indicates whether the security restrictions would cause any display objects to be omitted from the list returned by calling the DisplayObjectContainer.getObjectsUnderPoint() method with the specified point point. | DisplayObjectContainer
|  | contains(child:DisplayObject):Boolean Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself. | DisplayObjectContainer
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | dump():String Dumps the underlying contents of the TextLine as an XML string. | TextLine
|  | flushAtomData():void Releases the atom data of the line for garbage collection. | TextLine
|  | getAtomBidiLevel(atomIndex:int):int Gets the bidirectional level of the atom at the specified index. | TextLine
|  | getAtomBounds(atomIndex:int):Rectangle Gets the bounds of the atom at the specified index relative to the text line. | TextLine
|  | getAtomCenter(atomIndex:int):Number Gets the center of the atom as measured along the baseline at the specified index. | TextLine
|  | getAtomGraphic(atomIndex:int):DisplayObject Gets the graphic of the atom at the specified index, or null if the atom is a character. | TextLine
|  | getAtomIndexAtCharIndex(charIndex:int):int Returns the index of the atom containing the character specified by the charIndex parameter, or -1 if the character does not contribute to any atom in the line. | TextLine
|  | getAtomIndexAtPoint(stageX:Number, stageY:Number):int Returns the index of the atom at the point specified by the x and y parameters, or -1 if no atom exists at that point. | TextLine
|  | getAtomTextBlockBeginIndex(atomIndex:int):int Gets the text block begin index of the atom at the specified index. | TextLine
|  | getAtomTextBlockEndIndex(atomIndex:int):int Gets the text block end index of the atom at the specified index. | TextLine
|  | getAtomTextRotation(atomIndex:int):String Gets the rotation of the atom at the specified index. | TextLine
|  | getAtomWordBoundaryOnLeft(atomIndex:int):Boolean Indicates whether a word boundary occurs to the left of the atom at the specified index. | TextLine
|  | getBaselinePosition(baseline:String):Number Gets the position of the specified baseline, relative to TextBlock.baselineZero. | TextLine
|  | getBounds(targetCoordinateSpace:DisplayObject):Rectangle Returns a rectangle that defines the area of the display object relative to the coordinate system of the targetCoordinateSpace object. | DisplayObject
|  | getChildAt(index:int):DisplayObject Returns the child display object instance that exists at the specified index. | DisplayObjectContainer
|  | getChildByName(name:String):DisplayObject Returns the child display object that exists with the specified name. | DisplayObjectContainer
|  | getChildIndex(child:DisplayObject):int Returns the index position of a child DisplayObject instance. | DisplayObjectContainer
|  | getMirrorRegion(mirror:EventDispatcher):TextLineMirrorRegion Returns the first TextLineMirrorRegion on the line whose mirror property matches that specified by the mirror parameter, or null if no match exists. | TextLine
|  | getObjectsUnderPoint(point:Point):Array Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance. | DisplayObjectContainer
|  | getRect(targetCoordinateSpace:DisplayObject):Rectangle Returns a rectangle that defines the boundary of the display object, based on the coordinate system defined by the targetCoordinateSpace parameter, excluding any strokes on shapes. | DisplayObject
|  | globalToLocal(point:Point):Point Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates. | DisplayObject
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | hitTestObject(obj:DisplayObject):Boolean Evaluates the display object to see if it overlaps or intersects with the obj display object. | DisplayObject
|  | hitTestPoint(x:Number, y:Number, shapeFlag:Boolean = false):Boolean Evaluates the display object to see if it overlaps or intersects with the point specified by the x and y parameters. | DisplayObject
|  | 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
|  | localToGlobal(point:Point):Point Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates. | DisplayObject
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeChild(child:DisplayObject):DisplayObject Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer
|  | removeChildAt(index:int):DisplayObject Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer. | DisplayObjectContainer
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | setChildIndex(child:DisplayObject, index:int):void Changes the position of an existing child in the display object container. | DisplayObjectContainer
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | swapChildren(child1:DisplayObject, child2:DisplayObject):void Swaps the z-order (front-to-back order) of the two specified child objects. | DisplayObjectContainer
|  | swapChildrenAt(index1:int, index2:int):void Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the child list. | DisplayObjectContainer
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | added | Dispatched when a display object is added to the display list. | DisplayObject
|  | addedToStage | Dispatched when a display object is added to the on stage display list, either directly or through the addition of a sub tree in which the display object is contained. | DisplayObject
|  | clear | Dispatched when the user selects 'Clear' (or 'Delete') from the text context menu. | InteractiveObject
|  | click | Dispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject. | InteractiveObject
|  | copy | Dispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu. | InteractiveObject
|  | cut | Dispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu. | InteractiveObject
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | doubleClick | Dispatched when a user presses and releases the main button of a pointing device twice in rapid succession over the same InteractiveObject when that object's doubleClickEnabled flag is set to true. | InteractiveObject
|  | enterFrame | Dispatched when the playhead is entering a new frame. | DisplayObject
|  | exitFrame | Dispatched when the playhead is exiting the current frame. | DisplayObject
|  | focusIn | Dispatched after a display object gains focus. | InteractiveObject
|  | focusOut | Dispatched after a display object loses focus. | InteractiveObject
|  | frameConstructed | Dispatched after the constructors of frame display objects have run but before frame scripts have run. | DisplayObject
|  | keyDown | Dispatched when the user presses a key. | InteractiveObject
|  | keyFocusChange | Dispatched when the user attempts to change focus by using keyboard navigation. | InteractiveObject
|  | keyUp | Dispatched when the user releases a key. | InteractiveObject
|  | mouseDown | Dispatched when a user presses the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseFocusChange | Dispatched when the user attempts to change focus by using a pointer device. | InteractiveObject
|  | mouseMove | Dispatched when a user moves the pointing device while it is over an InteractiveObject. | InteractiveObject
|  | mouseOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | mouseOver | Dispatched when the user moves a pointing device over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseUp | Dispatched when a user releases the pointing device button over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | mouseWheel | Dispatched when a mouse wheel is spun over an InteractiveObject instance in the Flash Player window. | InteractiveObject
|  | paste | Dispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu. | InteractiveObject
|  | removed | Dispatched when a display object is about to be removed from the display list. | DisplayObject
|  | removedFromStage | Dispatched when a display object is about to be removed from the display list, either directly or through the removal of a sub tree in which the display object is contained. | DisplayObject
|  | render | Dispatched when the display list is about to be updated and rendered. | DisplayObject
|  | rollOut | Dispatched when the user moves a pointing device away from an InteractiveObject instance. | InteractiveObject
|  | rollOver | Dispatched when the user moves a pointing device over an InteractiveObject instance. | InteractiveObject
|  | selectAll | Dispatched when the user activates the platform specific accelerator key combination for a select all operation or selects 'Select All' from the text context menu. | InteractiveObject
|  | tabChildrenChange | Dispatched when the value of the object's tabChildren flag changes. | InteractiveObject
|  | tabEnabledChange | Dispatched when the object's tabEnabled flag changes. | InteractiveObject
|  | tabIndexChange | Dispatched when the value of the object's tabIndex property changes. | InteractiveObject

Public Constants

| Constant | Defined By
--- | --- | ---
|  | MAX_LINE_WIDTH : int = 1000000 [static] The maximum requested width of a text line, in pixels. | TextLine

Property Detail

ascent | property

`ascent:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the number of pixels from the baseline to the top of the tallest characters in the line. For a TextLine that contains only a graphic element, `ascent` is set to 0.

Implementation
`public function get ascent():Number`

atomCount | property |

`atomCount:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The number of atoms in the line, which is the number of indivisible elements, including spaces and graphic elements.

Accessing this property causes the player to create the atom data if it does not yet exist.

Implementation
`public function get atomCount():int`
Throws

| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

descent | property |

`descent:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the number of pixels from the baseline to the bottom of the lowest-descending characters in the line. For a TextLine that contains only a graphic element, `descent` is set to 0.

Implementation
`public function get descent():Number`

hasGraphicElement | property |

`hasGraphicElement:Boolean` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Indicates whether the text line contains any graphic elements.

Implementation
`public function get hasGraphicElement():Boolean`

See also

GraphicElement

mirrorRegions | property |

`mirrorRegions:Vector` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

A Vector containing the `TextLineMirrorRegion` objects associated with the line, or `null` if none exist.

Implementation
`public function get mirrorRegions():Vector`

See also

ContentElement.eventMirror
TextLineMirrorRegion

nextLine | property |

`nextLine:TextLine` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The next TextLine in the TextBlock, or `null` if this is the last line in the block or the validity of the line is `TextLineValidity.STATIC`.

Implementation
`public function get nextLine():TextLine`

See also

TextLine

previousLine | property |

`previousLine:TextLine` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The previous TextLine in the TextBlock, or `null` if the line is the first line in the block or the validity of the line is `TextLineValidity.STATIC`.

Implementation
`public function get previousLine():TextLine`

See also

TextLine

rawTextLength | property |

`rawTextLength:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The length of the raw text in the text block that became the line, including the U+FDEF characters representing graphic elements and any trailing spaces, which are part of the line but not actually displayed.

Implementation
`public function get rawTextLength():int`

See also

TextBlock
TextElement.rawText

specifiedWidth | property |

`specifiedWidth:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The width specified to the `TextBlock.createTextLine()` method when it created the line. This value is useful when deciding if a change requires rebreaking the line.

Implementation
`public function get specifiedWidth():Number`

See also

TextBlock.createTextLine()
textWidth
width

textBlock | property |

`textBlock:TextBlock` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The TextBlock containing this text line, or null if the validity of the line is `TextLineValidity.STATIC`.

Implementation
`public function get textBlock():TextBlock`

See also

TextBlock

textBlockBeginIndex | property |

`textBlockBeginIndex:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The index of the first character of the line in the raw text of the text block.

Implementation
`public function get textBlockBeginIndex():int`

See also

TextBlock

textHeight | property |

`textHeight:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The logical height of the text line, which is equal to `ascent` + `descent`. To get the inked height, access the inherited `height` property.

The value is calculated based on the difference between the baselines that bound the line, either ideo top/bottom or ascent/descent depending on whether TextBlock.baselineZero is ideo or not. Graphic elements are not considered when computing these baselines.

Implementation
`public function get textHeight():Number`

See also

height

textWidth | property |

`textWidth:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The logical width of the text line, which is the width that the text engine uses to lay out the line. Access the inherited `width` property to get the actual width of the bounding box of all the drawn pixels.

Implementation
`public function get textWidth():Number`

See also

specifiedWidth
width
Example
This example displays a line once in normal posture and once in italic, and traces the values of the `specifiedWidth`, `textWidth` and `width` properties in each case. The trace output is:

- specifiedWidth is: 500
- textWidth is: 268.9921875
- width is: 269
- specifiedWidth is: 500
- textWidth is: 267.52734375
- width is: 267.55

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

        public class TextLine_textWidthExample extends Sprite {

            public function TextLine_textWidthExample() {

                var str:String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, ";
                var yPos:Number = 20;
                var fontDescription:FontDescription = new FontDescription();
                var textBlock:TextBlock = new TextBlock();
                fontDescription.fontPosture = FontPosture.NORMAL;
                var format:ElementFormat = new ElementFormat(fontDescription, 12);
                var textElement:TextElement = new TextElement(str, format);
                textBlock.content = textElement;
                createLine(textBlock, yPos);
                fontDescription.fontPosture = FontPosture.ITALIC;
                format = new ElementFormat(fontDescription, 12);
                textElement = new TextElement(str, format);
                textBlock.content = textElement;
                createLine(textBlock, yPos + 20);
            }

            private function createLine(textBlock:TextBlock, yPos:Number):void {
                var textLine:TextLine = textBlock.createTextLine (null, 500);
                trace("specifiedWidth is: " + textLine.specifiedWidth);
                trace("textWidth is: " + textLine.textWidth);
                trace("width is: " + textLine.width);
                addChild(textLine);
                textLine.x = 15;
                textLine.y = yPos;
            }
        }
    }

unjustifiedTextWidth | property |

`unjustifiedTextWidth:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The width of the line if it was not justified. For unjustified text, this value is the same as `textWidth`. For justified text, this value is what the length would have been without justification and `textWidth` represents the actual line width. For example, when the following String is justified and submitted to `TextBlock.createTextLine()` with a width of 500, it has an actual width of 500 but an unjustified width of 268.9921875.

Implementation
`public function get unjustifiedTextWidth():Number`

See also

EastAsianJustifier
LineJustification
SpaceJustifier
Example

      var str = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, ";

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 line.

validity | property |

`validity:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Specifies the current validity of the text line. System values for this property are found in the members of the `TextLineValidity` class. The rules for setting this property are as follows:

A line is considered USER_INVALID if validity is set to any string which is not a member of `TextLineValidity`. USER_INVALID is an abstraction used here to represent any such value.

When the contents of the TextBlock are modified, player code marks affected text lines, the previous line, and all following lines as INVALID. The previous line must be marked invalid when a change allows the previous line to absorb part of the content that was originally on the first affected line.

Newly broken lines are always VALID. The player code might change following lines from VALID to POSSIBLY_INVALID or INVALID. It might change POSSIBLY_INVALID lines to VALID if the line breaks match up, or to INVALID if they don't.

User code can mark VALID lines as INVALID or USER_INVALID, and can mark USER_INVALID lines as VALID. User code cannot mark lines POSSIBLY_INVALID.

User code can mark any line STATIC. Doing so causes the `block` member to become `null`. It also clears the atom data of the line and prevents it from being re-created. Any graphic elements in a STATIC text line is removed and reparented if they are part of a new text line broken from the text block from which the STATIC text line originally derived.

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

| `ArgumentError` — if current value is `TextLineValidity.STATIC`
| `ArgumentError` — if current value is `TextLineValidity.INVALID` and new value is anything other than `TextValidity.STATIC`
| `ArgumentError` — if current value is `TextLineValidity.POSSIBLY_INVALID` and new value is `TextLineValidity.VALID`
| `ArgumentError` — If new value is `TextLineValidity.POSSIBLY_INVALID`

See also

TextLineValidity
Method Detail

dump | () | method

`public function dump():String`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Dumps the underlying contents of the TextLine 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.

For a description of the output, see the TextBlock.dump() method.

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

Returns

| `String`

See also

TextBlock.dump()

flushAtomData | () | method |

`public function flushAtomData():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Releases the atom data of the line for garbage collection. The term atom refers to the indivisible entities that make up a text line. Atom data is generated by the `atomCount` property and the various methods in this class that retrieve information about an individual atom.

See also

atomCount
getAtomBidiLevel()
getAtomBounds()
getAtomCenter()
getAtomGraphic()
getAtomIndexAtCharIndex()
getAtomIndexAtPoint()
getAtomTextBlockBeginIndex()
getAtomTextBlockEndIndex()
getAtomTextRotation()
getAtomWordBoundaryOnLeft()

getAtomBidiLevel | () | method |

`public function getAtomBidiLevel(atomIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the bidirectional level of the atom at the specified index. The value is determined by a combination of `TextBlock.bidiLevel` and the Unicode bidirectional properties of the characters in the block that combine to form the line.

For example, if you start a text block with some Hebrew text, you set `TextBlock.bidiLevel` to 1, establishing a default of right to left. If within the text you have a quote in English (left to right), that text has an `AtomBidiLevel` of 2. If within the English you have a bit of Arabic (right to left), `AtomBidiLevel` for that run goes to 3. If within the Arabic a number (left to right) occurs, the `AtomBidiLevel` setting for the number is 4. It does not matter in which line the atoms end up; the Hebrew atoms will be `AtomBidiLevel` 1, the English atoms will be `AtomBidiLevel` 2, Arabic atoms will be `AtomBidiLevel` 3, and the number atoms will be `AtomBidiLevel` 4.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `int` — The bidirectonal level of the atom at `atomIndex`

Throws

| `RangeError` — The specified atom index is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

TextBlock.bidiLevel
flushAtomData()

getAtomBounds | () | method |

`public function getAtomBounds(atomIndex:int):Rectangle`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the bounds of the atom at the specified index relative to the text line. The bounds of the specified atom consist of its horizontal position (`x`) in the line, its vertical position in the line (`y`), its width (`w`) and its height (`h`). All values are in pixels.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `Rectangle` — The bounds of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomCenter | () | method |

`public function getAtomCenter(atomIndex:int):Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the center of the atom as measured along the baseline at the specified index.

Calling this method causes the player to create the atom data, if it does not yet exist.

Parameters

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

Returns

| `Number` — The center of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomGraphic | () | method |

`public function getAtomGraphic(atomIndex:int):DisplayObject`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the graphic of the atom at the specified index, or `null` if the atom is a character.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `DisplayObject` — The graphic of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomIndexAtCharIndex | () | method |

`public function getAtomIndexAtCharIndex(charIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the index of the atom containing the character specified by the `charIndex` parameter, or -1 if the character does not contribute to any atom in the line. The `charIndex` is relative to the entire contents of the text block containing the line.

Calling this method causes the player to create the atom data if it does not yet exist.

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

| `int` — The index of the atom containing the character at `charIndex`. Returns -1 if the character does not contribute to any atom in the line.

Throws

| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomIndexAtPoint | () | method |

`public function getAtomIndexAtPoint(stageX:Number, stageY:Number):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the index of the atom at the point specified by the `x` and `y` parameters, or -1 if no atom exists at that point.

Calling this method causes the player to create the atom data if it does not yet exist.

This method takes global coordinates so that it may easily be used with `MouseEvent.stageX` and `MouseEvent.stageY`.

Parameters

| `stageX:Number` — The global x coordinate of the point to test.
| `stageY:Number` — The global y coordinate of the point to test.

Returns

| `int` — The index of the atom under the point. Returns -1 if the point is not over any atom.

Throws

| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomTextBlockBeginIndex | () | method |

`public function getAtomTextBlockBeginIndex(atomIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the text block begin index of the atom at the specified index.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `int` — The text block begin index of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomTextBlockEndIndex | () | method |

`public function getAtomTextBlockEndIndex(atomIndex:int):int`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the text block end index of the atom at the specified index.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `int` — The text block end index of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getAtomTextRotation | () | method |

`public function getAtomTextRotation(atomIndex:int):String`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the rotation of the atom at the specified index. TextRotation constants are used for this property. The rotation of the atom is the cumulative rotations of the glyph (as determined by `ElementFormat.textRotation` and / or `TextBlock.glyphRotation`), the element, and the line.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `String` — The rotation of the atom at `atomIndex`

Throws

| `RangeError` — The specified atom index is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

ElementFormat.textRotation
TextBlock.glyphRotation
flushAtomData()

getAtomWordBoundaryOnLeft | () | method |

`public function getAtomWordBoundaryOnLeft(atomIndex:int):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Indicates whether a word boundary occurs to the left of the atom at the specified index. Word boundaries are determined based on the Unicode properties of the characters which contributed to the line.

Calling this method causes the player to create the atom data if it does not yet exist.

Parameters

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

Returns

| `Boolean` — A Boolean value that indicates whether a word boundary occurs to the left of the atom at `atomIndex`

Throws

| `RangeError` — The atom index specified is out of range.
| `IllegalOperationError` — The `validity` of the line is `TextLineValidity.STATIC`.

See also

flushAtomData()

getBaselinePosition | () | method |

`public function getBaselinePosition(baseline:String):Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Gets the position of the specified baseline, relative to `TextBlock.baselineZero`.

Parameters

| `baseline:String` — The baseline for which to retrieve the position. Use `TextBaseline` values.

Returns

| `Number` — The position of the specified baseline relative to `TextBlock.baselineZero`.

Throws

| `ArgumentError` — If the `baseline` specified is not a member of `TextBaseline`.

See also

TextBlock.baselineZero
TextBaseline

getMirrorRegion | () | method |

`public function getMirrorRegion(mirror:EventDispatcher):TextLineMirrorRegion`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the first `TextLineMirrorRegion` on the line whose `mirror` property matches that specified by the `mirror` parameter, or `null` if no match exists.

Even a single `TextElement` can produce multiple `TextLineMirrorRegion` objects on one or more lines, depending on bi-di and line breaking. All the mirror regions generated from one text element are linked by their next and previous references.

Parameters

| `mirror:EventDispatcher` — The `EventDispatcher` mirror object to search for.

Returns

| `TextLineMirrorRegion` — The first `TextLineMirrorRegion` on the line whose `mirror` property matches the specified value, or `null` if no match exists.

See also

TextLineMirrorRegion
ContentElement.eventMirror
Constant Detail

MAX_LINE_WIDTH | Constant

`public static const MAX_LINE_WIDTH:int = 1000000`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The maximum requested width of a text line, in pixels. The `TextBlock.createTextLine()` method uses this constant as the default value for the `width` parameter, if you do not specify a value.

See also

TextBlock.createTextLine
Examples How to use examples
TextLineExample.as
This example displays various text textLines and steps through the atoms in a text block, using `getAtomBounds()` to frame each one.

1. Add the NumericStepper component to the library.
2. Save this code as TextLineExample.as in the same directory as your FLA.
3. Set the DocumentClass in the FLA to TextLineExample.

    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;
        import flash.text.engine.FontPosture;
        import fl.controls.NumericStepper;
        import flash.events.Event;
        import flash.geom.Rectangle;

        public class TextLineExample extends Sprite {

            private var atomStepper:NumericStepper = new NumericStepper();
            private var atomDataContainer:Sprite;
            private var fontDescription:FontDescription = new FontDescription("Arial");
            private var textBlock:TextBlock = new TextBlock();
            private var textLine:TextLine;

            public function TextLineExample():void {

                var myText:String = "I am a TextElement, created from a String and assigned " +
                "to the content property of a TextBlock. From the text block, " +
                "the createTextLine() method created these lines, 300 pixels wide, "  +
                "for display." ;

                atomStepper.minimum = 0;
                atomStepper.value = 0;
                atomStepper.width = 50;
                addChild(atomStepper);
                atomStepper.x = 20;
                atomStepper.y = 120;
                atomStepper.addEventListener(Event.CHANGE, nsChange);

                var directions:String = "Click up / down arrows to frame atoms in text block above.";

                fontDescription.fontPosture = FontPosture.ITALIC;
                var format:ElementFormat = new ElementFormat(fontDescription);
                format.fontSize = 12;
                var textElement1:TextElement = new TextElement(directions, format);
                textBlock.content = textElement1;
                createLines(textBlock, 15, 160, 400, this);

                var textElement2:TextElement = new TextElement(myText, format);
                fontDescription.fontPosture = FontPosture.NORMAL;
                format.fontSize = 16;
                textBlock.content = textElement2;
                createLines(textBlock, 15.0, 20.0, 300, this);
                textLine = textBlock.firstLine;
                atomStepper.maximum = textLine.atomCount - 1;
                showAtom(textLine, 0);
            }

            private function nsChange(event:Event):void
            {
                removeAtom(textLine);
                if (atomStepper.value == textLine.atomCount - 1)
                {
                    if(textLine != textBlock.lastLine)
                    {
                        textLine = textLine.nextLine;
                        atomStepper.maximum = textLine.atomCount - 1;
                        atomStepper.value = 0;
                    }
                }
                showAtom(textLine, atomStepper.value);
            }

            private function createLines(textBlock, startX, startY, width, container)
            {
                var textLine:TextLine = textBlock.createTextLine (null, width);
                while (textLine)
                {
                    textLine.x = startX;
                    textLine.y = startY;
                    startY += textLine.height + 2;
                    container.addChild(textLine);
                    textLine = textBlock.createTextLine (textLine, width);
                }
            }

            private function showAtom(textLine, i):void
            {
                var box:Sprite = new Sprite();
                var mcGraphics = box.graphics;
                var bounds:Rectangle = textLine.getAtomBounds(i);
                mcGraphics.lineStyle(1, 0xFF0000, 1.0);
                mcGraphics.drawRect(bounds.left, bounds.top, bounds.width, bounds.height);
                textLine.userData = textLine.addChild(box);
                displayAtomData(textLine,i);
            }

            private function displayAtomData(textLine, i)
            {
                if(atomDataContainer != null)
                    removeChild(atomDataContainer);
                atomDataContainer=new Sprite();
                var format:ElementFormat = new ElementFormat(fontDescription);
                fontDescription.fontPosture = FontPosture.NORMAL;
                format.fontSize = 12;
                format.color = 0x00000FF;
                var n:int = 0;
                var nxtY:Number = 0;
                var atomInfo:String = "value of getAtomBidiLevel() is: " + textLine.getAtomBidiLevel(i)+"\n"
                +"value of getAtomCenter() is: " + textLine.getAtomCenter(i)+"\n"
                +"value of getAtomIndexAtCharIndex() is: " + textLine.getAtomIndexAtCharIndex(i)+"\n"
                +"value of getAtomTextBlockBeginIndex() is: " + textLine.getAtomTextBlockBeginIndex(i)+"\n"
                +"value of getAtomTextBlockEndIndex() is: " + textLine.getAtomTextBlockEndIndex(i)+"\n"
                +"value of getAtomTextRotation() is: " + textLine.getAtomTextRotation(i)+"\n";
                var atomtextBlock:TextBlock = new TextBlock();
                var te3:TextElement = new TextElement(atomInfo, format);
                atomtextBlock.content = te3;
                createLines(atomtextBlock,20,200,500, atomDataContainer)
                addChild(atomDataContainer);
            }

            private function removeAtom(textLine):void
            {
                textLine.removeChild(textLine.userData);
            }
        }
    }

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