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
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():Number
atomCount | 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():int
Throws
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():Number
hasGraphicElement | 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:TextLine
Related 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:TextLine
Related 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():int
Related 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():Number
Related 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:TextBlock
Related 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():Number
Related 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():Number
Related 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():Number
Related 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):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 .
|
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