| 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 |
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:
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.
See also
| Property | Defined By | ||
|---|---|---|---|
 | accessibilityProperties : AccessibilityProperties
The current accessibility options for this display object. | DisplayObject | |
| alpha : Number
Indicates the alpha transparency value of the object specified. | DisplayObject | |
| ascent : Number [read-only]
Specifies the number of pixels from the baseline to the top of the tallest characters in the line. | TextLine | ||
| atomCount : int [read-only]
The number of atoms in the line, which is the number of indivisible elements, including spaces and graphic
elements. | TextLine | ||
| blendMode : String
A value from the BlendMode class that specifies which blend mode to use. | DisplayObject | |
| blendShader : Shader [write-only]
Sets a shader that is used for blending the foreground and background. | DisplayObject | |
| cacheAsBitmap : Boolean
If set to true, Flash Player or Adobe AIR caches an internal bitmap representation of the
display object. | DisplayObject | |
| constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| contextMenu : 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 | ||
| height : Number
Indicates the height of the display object, in pixels. | DisplayObject | |
| loaderInfo : LoaderInfo [read-only]
Returns a LoaderInfo object containing information about loading the file
to which this display object belongs. | DisplayObject | |
| mask : DisplayObject
The calling display object is masked by the specified mask object. | DisplayObject | |
| mirrorRegions : Vector.<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 enabled. | DisplayObjectContainer | |
| mouseEnabled : Boolean
Specifies whether this object receives mouse messages. | InteractiveObject | |
| mouseX : Number [read-only]
Indicates the x coordinate of the mouse position, in pixels. | DisplayObject | |
| mouseY : Number [read-only]
Indicates the y coordinate of the mouse position, in pixels. | DisplayObject | |
| name : String
Indicates the instance name of the DisplayObject. | DisplayObject | |
| nextLine : 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 | ||
| prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | |
| rawTextLength : int [read-only]
The length of the raw text in the text block that became the line,
including the U+FDEF characters representing graphic elements
and any trailing spaces, which are part of the line but not 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 | |
| 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. | 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 | ||
| 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 author to associate arbitrary data with the text line. | TextLine | ||
| validity : String
Specifies the current validity of the text line. | TextLine | ||
| visible : Boolean
Whether or not the display object is visible. | DisplayObject | |
| width : Number
Indicates the width of the display object, in pixels. | DisplayObject | |
| x : Number
Indicates the x coordinate of the DisplayObject instance relative to the local coordinates of
the parent DisplayObjectContainer. | DisplayObject | |
| y : Number
Indicates the y coordinate of the DisplayObject instance relative to the local coordinates of
the parent DisplayObjectContainer. | DisplayObject | |
| 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 | ||
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 | ||
|
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 a listener from the EventDispatcher object. | EventDispatcher | |
|
Changes the position of an existing child in the display object container. | DisplayObjectContainer | |
|
Sets the availability of a dynamic property for loop operations. | Object | |
|
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 |
Hide Inherited Public Properties
Show Inherited Public Properties
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.
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.
public function get atomCount():intIllegalOperationError — 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.
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.
public function get hasGraphicElement():BooleanSee 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.
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.
public function get nextLine():flash.text.engine:TextLineSee 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.
public function get previousLine():flash.text.engine:TextLineSee 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.
public function get rawTextLength():intSee 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.
public function get specifiedWidth():NumberSee 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.
public function get textBlock():flash.text.engine:TextBlockSee 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.
public function get textBlockBeginIndex():intSee 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.
public function get textHeight():NumberSee 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.
public function get textWidth():NumberSee also
specifiedWidth, textWidth
and width properties in each case.
The trace output is:
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.
public function get unjustifiedTextWidth():NumberSee also
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.
public function get validity():String public function set validity(value:String):voidArgumentError — 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
| 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.
ReturnsString |
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).
|
int — The bidirectional level of the atom at atomIndex.
|
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).
|
Rectangle — The bounds of the atom at atomIndex.
|
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).
|
Number — The center of the atom at atomIndex.
|
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).
|
DisplayObject — The graphic of the atom at atomIndex.
|
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).
|
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.
|
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.
|
int — The index of the atom under the point. Returns -1 if the point is not over any atom.
|
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).
|
int — The text block begin index of the atom at atomIndex.
|
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).
|
int — The text block end index of the atom at atomIndex.
|
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).
|
String — The rotation of the atom at atomIndex.
|
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).
|
Boolean — A Boolean value that indicates whether a word boundary occurs to the left of the atom at atomIndex.
|
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.
|
Number — The position of the specified baseline relative to TextBlock.baselineZero.
|
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.
|
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
| 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
getAtomBounds() to frame each one.
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);
}
}
}