Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.text.engine 
TextLine 
Packageflash.text.engine
Classpublic final class TextLine
InheritanceTextLine Inheritance DisplayObjectContainer Inheritance InteractiveObject Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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()

After normal event-dispatching for a text line finishes, if the line is valid, events are mirrored to the event dispatchers that are specified in the eventMirror properties of the content element objects that contributed to the text line. These objects are recorded in the TextLine.mirrorRegions property. The events are not mirrored if event propagation failed or was stopped, or if the text line is not valid.

Mirroring of mouse events is a special case. Because mirror regions aren't actually display objects, mouseOver and mouseOut events are simulated for them. rollOver and rollOut events are not simulated. All naturally occurring mouseOver, mouseOut, rollOver and rollOut events (whether targeted at the text line or at children of the text line) are ignored - they are not mirrored.

The origin of a text line object is the beginning of the baseline. If you don't set the vertical position (y property) of a line that contains Latin text on a Roman baseline, only the descenders of the text appear below the top of the Sprite to which you add the text line. See the following diagram:

Text baselines

The TextLine class has several ancestor classes — DisplayObjectContainer, InteractiveObject, DisplayObject, and EventDispatcher — from which it inherits properties and methods. The following inherited properties are inapplicable to TextLine objects:

  • contextMenu
  • focusRect
  • tabChildren
  • tabEnabled
  • tabIndex
  • transform

If you try to set these properties, the text engine throws the error: IllegalOperationError. You can read these properties, but they always contain default values.

View the examples

See also



Public Properties
 PropertyDefined By
 InheritedaccessibilityImplementation : AccessibilityImplementation
The current accessibility implementation (AccessibilityImplementation) for this InteractiveObject instance.
InteractiveObject
 InheritedaccessibilityProperties : AccessibilityProperties
The current accessibility options for this display object.
DisplayObject
 Inheritedalpha : 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
 InheritedblendMode : String
A value from the BlendMode class that specifies which blend mode to use.
DisplayObject
 InheritedblendShader : Shader
[write-only] Sets a shader that is used for blending the foreground and background.
DisplayObject
 InheritedcacheAsBitmap : Boolean
If set to true, Flash Player or Adobe AIR caches an internal bitmap representation of the display object.
DisplayObject
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
 InheritedcontextMenu : NativeMenu
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
 InheriteddoubleClickEnabled : Boolean
Specifies whether the object receives doubleClick events.
InteractiveObject
 Inheritedfilters : Array
An indexed array that contains each filter object currently associated with the display object.
DisplayObject
 InheritedfocusRect : Object
Specifies whether this object displays a focus rectangle.
InteractiveObject
  hasGraphicElement : Boolean
[read-only] Indicates whether the text line contains any graphic elements.
TextLine
 Inheritedheight : Number
Indicates the height of the display object, in pixels.
DisplayObject
 InheritedloaderInfo : LoaderInfo
[read-only] Returns a LoaderInfo object containing information about loading the file to which this display object belongs.
DisplayObject
 Inheritedmask : DisplayObject
The calling display object is masked by the specified mask object.
DisplayObject
  mirrorRegions : Vector.<flash.text.engine:TextLineMirrorRegion>
[read-only] A Vector containing the TextLineMirrorRegion objects associated with the line, or null if none exist.
TextLine
 InheritedmouseChildren : Boolean
Determines whether or not the children of the object are mouse enabled.
DisplayObjectContainer
 InheritedmouseEnabled : Boolean
Specifies whether this object receives mouse messages.
InteractiveObject
 InheritedmouseX : Number
[read-only] Indicates the x coordinate of the mouse position, in pixels.
DisplayObject
 InheritedmouseY : Number
[read-only] Indicates the y coordinate of the mouse position, in pixels.
DisplayObject
 Inheritedname : String
Indicates the instance name of the DisplayObject.
DisplayObject
  nextLine : flash.text.engine:TextLine
[read-only] The next TextLine in the TextBlock, or null if the current line is the last line in the block or the validity of the line is TextLineValidity.STATIC.
TextLine
 InheritednumChildren : int
[read-only] Returns the number of children of this object.
DisplayObjectContainer
 InheritedopaqueBackground : Object
Specifies whether the display object is opaque with a certain background color.
DisplayObject
 Inheritedparent : DisplayObjectContainer
[read-only] Indicates the DisplayObjectContainer object that contains this display object.
DisplayObject
  previousLine : flash.text.engine: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
 Inheritedprototype : 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 are displayed.
TextLine
 Inheritedroot : 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
 Inheritedrotation : Number
Indicates the rotation of the DisplayObject instance, in degrees, from its original orientation.
DisplayObject
 InheritedrotationX : Number
Indicates the x-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 InheritedrotationY : Number
Indicates the y-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 InheritedrotationZ : Number
Indicates the z-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container.
DisplayObject
 Inheritedscale9Grid : Rectangle
The current scaling grid that is in effect.
DisplayObject
 InheritedscaleX : Number
Indicates the horizontal scale (percentage) of the object as applied from the registration point.
DisplayObject
 InheritedscaleY : Number
Indicates the vertical scale (percentage) of an object as applied from the registration point of the object.
DisplayObject
 InheritedscaleZ : Number
Indicates the depth scale (percentage) of an object as applied from the registration point of the object.
DisplayObject
 InheritedscrollRect : Rectangle
The scroll rectangle bounds of the display object.
DisplayObject
  specifiedWidth : Number
[read-only] The width that was specified to the TextBlock.createTextLine() method when it created the line.
TextLine
 Inheritedstage : Stage
[read-only] The Stage of the display object.
DisplayObject
 InheritedtabChildren : Boolean
Determines whether the children of the object are tab enabled.
DisplayObjectContainer
 InheritedtabEnabled : Boolean
Specifies whether this object is in the tab order.
InteractiveObject
 InheritedtabIndex : int
Specifies the tab ordering of objects in a SWF file.
InteractiveObject
  textBlock : flash.text.engine: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
 InheritedtextSnapshot : flash.text: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
 Inheritedtransform : flash.geom: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
 Inheritedvisible : Boolean
Whether or not the display object is visible.
DisplayObject
 Inheritedwidth : Number
Indicates the width of the display object, in pixels.
DisplayObject
 Inheritedx : Number
Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
 Inheritedy : Number
Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of the parent DisplayObjectContainer.
DisplayObject
 Inheritedz : Number
Indicates the z coordinate position along the z-axis of the DisplayObject instance relative to the 3D parent container.
DisplayObject
Public Methods
 MethodDefined By
 Inherited
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
Adds a child DisplayObject instance to this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
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
 Inherited
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
 Inherited
Determines whether the specified display object is a child of the DisplayObjectContainer instance or the instance itself.
DisplayObjectContainer
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
Dumps the underlying contents of the TextLine as an XML string.
TextLine
  
Releases the atom data of the line for garbage collection.
TextLine
  
Gets the bidirectional level of the atom at the specified index.
TextLine
  
Gets the bounds of the atom at the specified index relative to the text line.
TextLine
  
Gets the center of the atom as measured along the baseline at the specified index.
TextLine
  
Gets the graphic of the atom at the specified index, or null if the atom is a character.
TextLine
  
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
  
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
  
Gets the text block begin index of the atom at the specified index.
TextLine
  
Gets the text block end index of the atom at the specified index.
TextLine
  
Gets the rotation of the atom at the specified index.
TextLine
  
Indicates whether a word boundary occurs to the left of the atom at the specified index.
TextLine
  
Gets the position of the specified baseline, relative to TextBlock.baselineZero.
TextLine
 Inherited
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
 Inherited
Returns the child display object instance that exists at the specified index.
DisplayObjectContainer
 Inherited
Returns the child display object that exists with the specified name.
DisplayObjectContainer
 Inherited
Returns the index position of a child DisplayObject instance.
DisplayObjectContainer
  
Returns the first TextLineMirrorRegion on the line whose mirror property matches that specified by the mirror parameter, or null if no match exists.
TextLine
 Inherited
Returns an array of objects that lie under the specified point and are children (or grandchildren, and so on) of this DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
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
 Inherited
Converts the point object from the Stage (global) coordinates to the display object's (local) coordinates.
DisplayObject
 Inherited
Converts a two-dimensional point from the Stage (global) coordinates to a three-dimensional display object's (local) coordinates.
DisplayObject
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Evaluates the bounding box of the display object to see if it overlaps or intersects with the bounding box of the obj display object.
DisplayObject
 Inherited
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
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Converts a three-dimensional point of the three-dimensional display object's (local) coordinates to a two-dimensional point in the Stage (global) coordinates.
DisplayObject
 Inherited
Converts the point object from the display object's (local) coordinates to the Stage (global) coordinates.
DisplayObject
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance.
DisplayObjectContainer
 Inherited
Removes a child DisplayObject from the specified index position in the child list of the DisplayObjectContainer.
DisplayObjectContainer
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Changes the position of an existing child in the display object container.
DisplayObjectContainer
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Swaps the z-order (front-to-back order) of the two specified child objects.
DisplayObjectContainer
 Inherited
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
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 InheritedDispatched when a display object is added to the display list.DisplayObject
 InheritedDispatched 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
 InheritedDispatched when the user selects 'Clear' (or 'Delete') from the text context menu.InteractiveObject
 InheritedDispatched when a user presses and releases the main button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user gesture triggers the context menu associated with this interactive object in an AIR application.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a copy operation or selects 'Copy' from the text context menu.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a cut operation or selects 'Cut' from the text context menu.InteractiveObject
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
 InheritedDispatched 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
 Inherited[broadcast event] Dispatched when the playhead is entering a new frame.DisplayObject
 Inherited[broadcast event] Dispatched when the playhead is exiting the current frame.DisplayObject
 InheritedDispatched after a display object gains focus.InteractiveObject
 InheritedDispatched after a display object loses focus.InteractiveObject
 Inherited[broadcast event] Dispatched after the constructors of frame display objects have run but before frame scripts have run.DisplayObject
 InheritedDispatched when the user presses a key.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using keyboard navigation.InteractiveObject
 InheritedDispatched when the user releases a key.InteractiveObject
 InheritedDispatched when a user presses and releases the middle button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the middle pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user attempts to change focus by using a pointer device.InteractiveObject
 InheritedDispatched when a user moves the pointing device while it is over an InteractiveObject.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a mouse wheel is spun over an InteractiveObject instance.InteractiveObject
 InheritedDispatched by the drag initiator InteractiveObject when the user releases the drag gesture.InteractiveObject
 InheritedDispatched by the target InteractiveObject when a dragged object is dropped on it and the drop has been accepted with a call to DragManager.acceptDragDrop().InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture enters its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject when a drag gesture leaves its boundary.InteractiveObject
 InheritedDispatched by an InteractiveObject continually while a drag gesture remains within its boundary.InteractiveObject
 InheritedDispatched at the beginning of a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched during a drag operation by the InteractiveObject that is specified as the drag initiator in the DragManager.doDrag() call.InteractiveObject
 InheritedDispatched when the user activates the platform specific accelerator key combination for a paste operation or selects 'Paste' from the text context menu.InteractiveObject
 InheritedDispatched when a display object is about to be removed from the display list.DisplayObject
 InheritedDispatched 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
 Inherited[broadcast event] Dispatched when the display list is about to be updated and rendered.DisplayObject
 InheritedDispatched when a user presses and releases the right button of the user's pointing device over the same InteractiveObject.InteractiveObject
 InheritedDispatched when a user presses the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when a user releases the pointing device button over an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device away from an InteractiveObject instance.InteractiveObject
 InheritedDispatched when the user moves a pointing device over an InteractiveObject instance.InteractiveObject
 InheritedDispatched 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
 InheritedDispatched when the value of the object's tabChildren flag changes.InteractiveObject
 InheritedDispatched when the object's tabEnabled flag changes.InteractiveObject
 InheritedDispatched when the value of the object's tabIndex property changes.InteractiveObject
 InheritedDispatched when a user enters one or more characters of text.InteractiveObject
Public Constants
 ConstantDefined 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
Runtime Versions: Flash Player 10, AIR 1.5

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
Runtime Versions: Flash Player 10, AIR 1.5

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

descent

property 
descent:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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
Runtime Versions: Flash Player 10, AIR 1.5

Indicates whether the text line contains any graphic elements.



Implementation
    public function get hasGraphicElement():Boolean

See also

mirrorRegions

property 
mirrorRegions:Vector.<flash.text.engine:TextLineMirrorRegion>  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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



Implementation
    public function get mirrorRegions():Vector.<flash.text.engine:TextLineMirrorRegion>

See also

nextLine

property 
nextLine:flash.text.engine:TextLine  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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



Implementation
    public function get nextLine():flash.text.engine:TextLine

See also

previousLine

property 
previousLine:flash.text.engine:TextLine  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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():flash.text.engine:TextLine

See also

rawTextLength

property 
rawTextLength:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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 are displayed.



Implementation
    public function get rawTextLength():int

See also

specifiedWidth

property 
specifiedWidth:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

The width that was 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

property 
textBlock:flash.text.engine:TextBlock  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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



Implementation
    public function get textBlock():flash.text.engine:TextBlock

See also

textBlockBeginIndex

property 
textBlockBeginIndex:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

textHeight

property 
textHeight:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

textWidth

property 
textWidth:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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


Example  ( How to use this 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);
            var fontDescriptionItalic = fontDescription.clone();
            fontDescriptionItalic.fontPosture = FontPosture.ITALIC;
            var formatItalic = new ElementFormat(fontDescriptionItalic, 12);
            textElement = new TextElement(str, formatItalic);
            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
Runtime Versions: Flash Player 10, AIR 1.5

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


Example  ( How to use this example )
When the String in the following example is justified and submitted to TextBlock.createTextLine() with a width of 500, it gets an actual width of 500 but has an unjustified width of 268.9921875.
     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.SpaceJustifier;
     import flash.text.engine.LineJustification;

     var str:String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, ";
     var fontDescription:FontDescription = new FontDescription();
     var textBlock:TextBlock = new TextBlock();
     var format:ElementFormat = new ElementFormat(fontDescription, 12);
     var textElement:TextElement = new TextElement(str, format);
     textBlock.content = textElement;
     var spaceJustifier:SpaceJustifier = new SpaceJustifier("en", LineJustification.ALL_INCLUDING_LAST);
     textBlock.textJustifier = spaceJustifier;
     var textLine:TextLine = textBlock.createTextLine(null, 500);
     textLine.y = 20;

     addChild(textLine);
     trace("textWidth value is: " + textLine.textWidth);        // 500.00244140625
     trace("unjustifiedTextWidth is: " + textLine.unjustifiedTextWidth); // 268.9921875
     

userData

property 
public var userData:*

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

Provides a way for the author to associate arbitrary data with the text line.

validity

property 
validity:String

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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 may change lines that follow from VALID to POSSIBLY_INVALID or INVALID. It may 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

Method Detail

dump

()method
public function dump():String

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

flushAtomData

()method 
public function flushAtomData():void

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

Releases the atom data of the line for garbage collection. The term atom refers to the indivisible entities that make up a text line. The text engine generates atom data when you access the atomCount property or call one of the methods that retrieve information about an atom.

See also

getAtomBidiLevel

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

Gets the bidirectional level of the atom at the specified index. Determined by a combination of TextBlock.bidiLevel and the Unicode bidirectional properties of the characters that 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 are AtomBidiLevel 1, the English atoms are AtomBidiLevel 2, Arabic atoms are AtomBidiLevel 3, and the number atoms are 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 bidirectional 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

getAtomBounds

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomCenter

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomGraphic

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomIndexAtCharIndex

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomIndexAtPoint

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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 you can easily use it with MouseEvent.stageX and MouseEvent.stageY properties.

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

getAtomTextBlockBeginIndex

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomTextBlockEndIndex

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getAtomTextRotation

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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 element and the line. Its primary use is for setting the orientation of the caret (cursor) when interacting with a TextLine.

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

getAtomWordBoundaryOnLeft

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getBaselinePosition

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

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

getMirrorRegion

()method 
public function getMirrorRegion(mirror:EventDispatcher):flash.text.engine:TextLineMirrorRegion

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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 bidirectional level and line breaking. The nextRegion and previousRegion properties link all the mirror regions generated from one text element.

Parameters

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

Returns
flash.text.engine:TextLineMirrorRegion — The first TextLineMirrorRegion on the line whose mirror property matches the specified value, or null if no match exists.

See also

Constant Detail

MAX_LINE_WIDTH

Constant
public static const MAX_LINE_WIDTH:int = 1000000

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

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

TextLineExample.as

This example displays various text lines 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 Class in the Properties window of 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 flash.text.engine.FontWeight;
    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 fontDescriptionItalic:FontDescription = new FontDescription("Arial", FontWeight.NORMAL, FontPosture.ITALIC);
        private var fontDescriptionNormal:FontDescription = new FontDescription("Arial", FontWeight.NORMAL , FontPosture.NORMAL);
        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.";
            
            var formatItalic:ElementFormat = new ElementFormat(fontDescriptionItalic);
            formatItalic.fontSize = 12;
            var textElement1:TextElement = new TextElement(directions, formatItalic);
            textBlock.content = textElement1;
            createLines(textBlock, 15, 160, 400, this);
            
            var formatNormal:ElementFormat = new ElementFormat(fontDescriptionNormal);
            formatNormal.fontSize = 16;
            var textElement2:TextElement = new TextElement(myText, formatNormal);
            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 = new ElementFormat(fontDescriptionNormal);
            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 textElement3:TextElement = new TextElement(atomInfo, format);
            atomtextBlock.content = textElement3;
            createLines(atomtextBlock,20,200,500, atomDataContainer)
            addChild(atomDataContainer);
        }
            
        private function removeAtom(textLine):void
        {
            textLine.removeChild(textLine.userData);
        }
    }    
}