| Package | flash.text.engine |
| Class | public final class TextLine |
| Inheritance | TextLine  DisplayObjectContainer InteractiveObject DisplayObject EventDispatcher Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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 and to provide 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.
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:
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
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.
More examples
Related API Elements
Hide Inherited Public Properties
Show Inherited Public Properties| Property | Defined By | ||
|---|---|---|---|
 | accessibilityImplementation : AccessibilityImplementation
The current accessibility implementation (AccessibilityImplementation)
for this InteractiveObject instance. | InteractiveObject | |
| 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 | |
| blendShader : Shader [write-only]
Sets a shader that is used for blending the foreground and background. | DisplayObject | |
| cacheAsBitmap : Boolean
If set to true, Flash runtimes cache an internal bitmap representation of the
display object. | DisplayObject | |
| cacheAsBitmapMatrix : Matrix
If non-null, this Matrix object defines how a display object is rendered when
cacheAsBitmap is set to true. | DisplayObject | |
| constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| contextMenu : 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 | ||
| 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 | ||
| hasTabs : Boolean [read-only]
Indicates whether the text line contains any tabs. | 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 | |
| metaData : Object
Obtains the meta data object of the DisplayObject instance if meta data was stored alongside the
the instance of this DisplayObject in the SWF file through a PlaceObject4 tag. | 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 | ||
| mouseChildren : Boolean
Determines whether or not the children of the object are mouse, or user input device, enabled. | DisplayObjectContainer | |
| mouseEnabled : Boolean
Specifies whether this object receives mouse, or other user input, messages. | InteractiveObject | |
| mouseX : Number [read-only]
Indicates the x coordinate of the mouse or user input device position, in pixels. | DisplayObject | |
| mouseY : Number [read-only]
Indicates the y coordinate of the mouse or user input device position, in pixels. | DisplayObject | |
| name : String
Indicates the instance name of the DisplayObject. | DisplayObject | |
| needsSoftKeyboard : Boolean
Specifies whether a virtual keyboard (an on-screen, software keyboard) should display
when this InteractiveObject instance receives focus. | InteractiveObject | |
| 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 | ||
| 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 : 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 | ||
| 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 | ||
| 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 | |
| rotationX : Number
Indicates the x-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | DisplayObject | |
| rotationY : Number
Indicates the y-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | DisplayObject | |
| rotationZ : Number
Indicates the z-axis rotation of the DisplayObject instance, in degrees, from its original orientation relative to the 3D parent container. | 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 | |
| scaleZ : Number
Indicates the depth 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 | |
| softKeyboard : String
Controls the appearance of the soft keyboard. | InteractiveObject | |
| softKeyboardInputAreaOfInterest : Rectangle
Defines the area that should remain on-screen when a soft keyboard is displayed (not available on iOS). | InteractiveObject | |
| specifiedWidth : Number [read-only]
The width that was 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 : flash.text.engine:TextBlock [read-only]
The TextBlock containing this text line, or null if the validity of the line is TextLineValidity.STATIC,
meaning that the connection between the line and the TextBlock has been severed. | 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 : 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 | ||
| totalAscent : Number [read-only]
Specifies the number of pixels from the baseline to the top of the tallest character or graphic in the line. | TextLine | ||
| totalDescent : Number [read-only]
Specifies the number of pixels from the baseline to the bottom of the lowest-descending character or graphic in the line. | TextLine | ||
| totalHeight : Number [read-only]
The total logical height of the text line, which is equal to totalAscent + totalDescent. | TextLine | ||
| transform : 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 application 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 | |
| z : Number
Indicates the z coordinate position along the z-axis of the DisplayObject
instance relative to the 3D parent container. | DisplayObject | |
| Method | Defined By | ||
|---|---|---|---|
|
Adds a child DisplayObject instance to this DisplayObjectContainer instance. | DisplayObjectContainer | |
|
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 | |
|
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 | |
|
Determines whether the specified display object is a child of the DisplayObjectContainer instance or
the instance itself. | DisplayObjectContainer | |
|
Dispatches an event into the event flow. | EventDispatcher | |
Dumps the underlying contents of the TextLine as an XML string. | TextLine | ||
Deprecated since Flash Player 10.1Now does nothing
This method is deprecated and has no effect. | 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 | ||
|
Returns a rectangle that defines the area of the display object relative to the coordinate system
of the targetCoordinateSpace object. | DisplayObject | |
|
Returns the child display object instance that exists at the specified index. | DisplayObjectContainer | |
|
Returns the child display object that exists with the specified name. | DisplayObjectContainer | |
|
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 | ||
|
Returns an array of objects that lie under the specified point and are children
(or grandchildren, and so on) of this DisplayObjectContainer instance. | DisplayObjectContainer | |
|
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 | |
|
Converts the point object from the Stage (global) coordinates
to the display object's (local) coordinates. | DisplayObject | |
|
Converts a two-dimensional point from the Stage (global) coordinates to a
three-dimensional display object's (local) coordinates. | DisplayObject | |
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
Indicates whether an object has a specified property defined. | Object | |
|
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 | |
|
Evaluates the display object to see if it overlaps or intersects with the
point specified by the x and y parameters. | DisplayObject | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
|
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 | |
|
Converts the point object from the display object's (local) coordinates to the
Stage (global) coordinates. | DisplayObject | |
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Removes the specified child DisplayObject instance from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer | |
|
Removes a child DisplayObject from the specified index position in the child list of
the DisplayObjectContainer. | DisplayObjectContainer | |
|
Removes all child DisplayObject instances from the child list of the DisplayObjectContainer instance. | DisplayObjectContainer | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
|
Raises a virtual keyboard. | InteractiveObject | |
|
Changes the position of an existing child in the display object container. | DisplayObjectContainer | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
|
Recursively stops the timeline execution of all MovieClips rooted at this object. | DisplayObjectContainer | |
|
Swaps the z-order (front-to-back order) of the two specified child objects. | DisplayObjectContainer | |
|
Swaps the z-order (front-to-back order) of the child objects at the two specified index positions in the
child list. | DisplayObjectContainer | |
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
| Constant | Defined By | ||
|---|---|---|---|
| MAX_LINE_WIDTH : int = 1000000 [static]
The maximum requested width of a text line, in pixels. | TextLine | ||
ascent | property |
ascent:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberatomCount | property |
atomCount:int [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
The number of atoms in the line, which is the number of indivisible elements, including spaces and graphic elements.
Implementation
public function get atomCount():intThrows
IllegalOperationError — The validity of the line is TextLineValidity.STATIC.
|
descent | property |
descent:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberhasGraphicElement | property |
hasTabs | property |
mirrorRegions | property |
mirrorRegions:Vector.<flash.text.engine:TextLineMirrorRegion> [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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>Related API Elements
nextLine | property |
nextLine:flash.text.engine:TextLine [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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:TextLineRelated API Elements
previousLine | property |
previousLine:flash.text.engine:TextLine [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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:TextLineRelated API Elements
rawTextLength | property |
rawTextLength:int [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():intRelated API Elements
specifiedWidth | property |
specifiedWidth:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberRelated API Elements
textBlock | property |
textBlock:flash.text.engine:TextBlock [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
The TextBlock containing this text line, or null if the validity of the line is TextLineValidity.STATIC,
meaning that the connection between the line and the TextBlock has been severed.
Implementation
public function get textBlock():flash.text.engine:TextBlockRelated API Elements
textBlockBeginIndex | property |
textHeight | property |
textHeight:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberRelated API Elements
textWidth | property |
textWidth:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberRelated API Elements
Example ( How to use this example )
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;
}
}
}
totalAscent | property |
totalDescent | property |
totalHeight | property |
unjustifiedTextWidth | property |
unjustifiedTextWidth:Number [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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():NumberRelated API Elements
Example ( How to use this example )
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, Flash Lite 4 |
Provides a way for the application 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, Flash Lite 4 |
Specifies the current validity of the text line.
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, the Flash runtime 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 Flash runtime 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.
Application code can mark VALID lines as INVALID or USER_INVALID, and can mark USER_INVALID lines as VALID. Application code cannot mark lines POSSIBLY_INVALID.
Application code can mark any line STATIC. Doing so causes the block member to become null.
Any graphic elements in a STATIC text line are 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):voidThrows
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.
|
Related API Elements
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 layout information.
The following describes the output:
[LINE] <line ascent=[Number] descent=[Number] rotation=[int]> <elements> [0-N ELEMENT] </elements> <clusters> [0-N CLUSTER] </clusters> </line> [ELEMENT] <glyph isEmbedded=[Boolean] fontName=[String] isBold=[Boolean] isItalic=[Boolean] gid=[int] pointSize=[Number] x=[Number] y=[Number] rotation=[int]/> or <graphic child=[int] x=[Number] y=[Number] rotation=[int]/> or <embeddedRun x=[Number] y=[Number]> [LINE] </embeddedRun> [CLUSTER] <cluster xLeft=[Number] xCenter=[Number] xRight=[Number] cursorOnLeft=[Boolean] cursorOnRight=[Boolean] wordBoundaryOnLeft=[Boolean] wordBoundaryOnRight=[Boolean]/>
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.
ReturnsString |
Related API Elements
flushAtomData | () | method |
public function flushAtomData():void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
This method is deprecated and has no effect. Atom data is compressed and is not a factor in managing memory efficiency.
Related API Elements
getAtomBidiLevel | () | method |
public function getAtomBidiLevel(atomIndex:int):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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).
|
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.
|
Related API Elements
getAtomBounds | () | method |
public function getAtomBounds(atomIndex:int):Rectangle| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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).
|
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.
|
getAtomCenter | () | method |
public function getAtomCenter(atomIndex:int):Number| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
Gets the center of the atom as measured along the baseline at the specified index.
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).
|
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.
|
getAtomGraphic | () | method |
public function getAtomGraphic(atomIndex:int):DisplayObject| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
Gets the graphic of the atom at the specified index, or null if the atom is a character.
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).
|
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.
|
getAtomIndexAtCharIndex | () | method |
public function getAtomIndexAtCharIndex(charIndex:int):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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).
|
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.
|
getAtomIndexAtPoint | () | method |
public function getAtomIndexAtPoint(stageX:Number, stageY:Number):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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.
|
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.
|
getAtomTextBlockBeginIndex | () | method |
public function getAtomTextBlockBeginIndex(atomIndex:int):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
Gets the text block begin index of the atom at the specified index.
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).
|
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.
|
getAtomTextBlockEndIndex | () | method |
public function getAtomTextBlockEndIndex(atomIndex:int):int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
Gets the text block end index of the atom at the specified index.
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).
|
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.
|
getAtomTextRotation | () | method |
public function getAtomTextRotation(atomIndex:int):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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).
|
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.
|
Related API Elements
getAtomWordBoundaryOnLeft | () | method |
public function getAtomWordBoundaryOnLeft(atomIndex:int):Boolean| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
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).
|
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.
|
getBaselinePosition | () | method |
public function getBaselinePosition(baseline:String):Number| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
|
Number — The position of the specified baseline relative to TextBlock.baselineZero.
|
Throws
ArgumentError — If the baseline specified is not a member of TextBaseline.
|
Related API Elements
getMirrorRegion | () | method |
public function getMirrorRegion(mirror:EventDispatcher):flash.text.engine:TextLineMirrorRegion| Language Version: | ActionScript 3.0 |
| Runtime Versions: | Flash Player 10, AIR 1.5, Flash Lite 4 |
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.
|
flash.text.engine:TextLineMirrorRegion — The first TextLineMirrorRegion on the line whose mirror property matches
the specified value, or null if no match exists.
|
Related API Elements
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, Flash Lite 4 |
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.
Related API Elements
getAtomBounds() to frame each one.
- Add the NumericStepper component to the library.
- Save this code as TextLineExample.as in the same directory as your FLA.
- 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);
}
}
}
Thu Dec 6 2018, 01:12 PM -08:00