TextBlock  - AS3

Specifies that you want to enhance screen appearance at the expense of what-you-see-is-what-you-get (WYSIWYG) print fidelity. For platforms and fonts that do not support sub pixel glyph positioning during device font rendering, but do support non-linear scaling, setting this property to true enables the use of those metrics at some cost to WYSIWYG print fidelity, particularly for small point sizes. Non linear font scaling works by selectivly scaling the width of individual glyphs to conceal unsightly gaps caused by pixel snapping.

On platforms which do support sub-pixel glyph positioning, this flag is ignored.

This flag has no effect on embedded font rendering

The default value is true.

The font used to determine the baselines for all the lines created from the block, independent of their content. Baselines depend on font and font size.

The default value is null. When the baseline font is null, the baseline font size is ignored and the baseline for any given line is based on the font and size of the largest text in the line. When you specify both baselineFontDescription and baselineFontSize, they determine the baselines for all the lines in the text block, independent of their content. This combination is most often useful in Asian typography.

Related API Elements

The font size used to calculate the baselines for the lines created from the block. Baselines depend on font and font size.

The default value is 12. When the baseline font is null, the baseline font size is ignored and the baseline for any given line is based on the font and size of the largest text in the line.

Related API Elements

Specifies which baseline is at y=0 for lines created from this block. Valid values for this property are found in the members of the TextBaseline class.

The default value is TextBaseline.ROMAN.

To set values for this property, use the following string values:

Related API Elements

Specifies the bidirectional paragraph embedding level of the text block. In general, use 0 for LTR paragraphs (English, Japanese, etc) and 1 for RTL paragraphs (Arabic, Hebrew, etc). The use of values other than 0 or 1 is reserved for special cases - see UAX#9, "Unicode Bidirectional Algorithm" (http://www.unicode.org/reports/tr9/) for details.

The default value is 0.

Modifying bidiLevel changes the validity of all previously broken lines to TextLineValidity.INVALID. After changing bidiLevel, the firstInvalidLine property equals the firstLine property, and you must rebreak all the lines in the TextBlock.

Related API Elements

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;
    
    public class TextBlock_bidiLevelExample extends Sprite {
        
        public function TextBlock_bidiLevelExample():void {             
            var fontSize:Number = 36;

            var format:ElementFormat = new ElementFormat();        
            format.fontDescription = new FontDescription("Adobe Hebrew");
            format.fontSize = fontSize;
            var y:Number = 0;
            var leading:Number = fontSize * 0.2;
            var text:String = "abc" + String.fromCharCode(0x05D0, 0x05D1, 0x05D2);

            var textBlock:TextBlock = new TextBlock();
            textBlock.content = new TextElement(text, format);
                        
            // bidiLevel even
            textBlock.bidiLevel = 0;
            var textLine = textBlock.createTextLine(null, 400);
            y += leading + textLine.ascent;
            textLine.y = y;
            y += textLine.descent;
            addChild(textLine);      
            
            // bidiLevel odd
            textBlock.content = new TextElement(text, format);
            textBlock.bidiLevel = 1;
            textLine = textBlock.createTextLine(null, 400);
            y += leading + textLine.ascent;          
            textLine.y = y;
            addChild(textLine);   
        }
    }
}

Holds the contents of the text block. Because ContentElement is a base class, assign content an instance of a ContentElement subclass: TextElement, GraphicElement, or GroupElement. A TextElement object contains a String, a GraphicElement object contains a DisplayObject, and a GroupElement contains a Vector object that contains one or more TextElement, GraphicElement, or other GroupElement objects. Use a TextElement for a paragraph of homogenous text, a GraphicElement for a graphic, and a GroupElement for a combination of text and graphic elements or multiples instances of these elements, as well as other GroupElement objects.

The default value is null.

Modifying the content property changes the validity of all previously created lines to TextLineValidity.INVALID. After changing content, the firstInvalidLine property equals the firstLine property and you must rebreak all lines in the TextBlock.

Related API Elements

Identifies the first line in the text block in which TextLine.validity is not equal to TextLineValidity.VALID.

The default value is null.

Related API Elements

The first TextLine in the TextBlock, if any.

The default value is null.

Related API Elements

The last TextLine in the TextBlock, if any.

The default value is null.

Related API Elements

Rotates the text lines in the text block as a unit. Call the createTextLine() method after setting lineRotation for it to take effect. The default value is TextRotation.ROTATE_0.

The final rotation of any glyph depends on the values of ElementFormat.textRotation, ContentElement.textRotation, and TextBlock.lineRotation.

TextBlock.lineRotation is typically used for Asian text. To create a paragraph of vertical Japanese text, do the following:

1. Set the TextBlock.lineRotation property to TextRotation.ROTATE_90.
2. Leave the ElementFormat.textRotation property of the content as the default, TextRotation.AUTO.

Use the following constants, which are defined in the TextRotation class, to set the value for this property:

More examples

Related API Elements

package {
    import flash.display.Sprite;
    import flash.text.engine.FontDescription;
    import flash.text.engine.TextBlock;
    import flash.text.engine.TextElement;
    import flash.text.engine.TextLine;
    import flash.text.engine.TextRotation;
    import flash.text.engine.ElementFormat;
    
    public class TextBlock_lineRotationExample extends Sprite {
        
        public function TextBlock_lineRotationExample():void {
            var Japanese:String = String.fromCharCode(
                0x5185, 0x95A3, 0x5E9C, 0x304C, 0x300C, 0x653F, 0x5E9C, 0x30A4,
                0x30F3, 0x30BF, 0x30FC, 0x30CD, 0x30C3, 0x30C8, 0x30C6, 0x30EC, 
                0x30D3, 0x300D, 0x306E, 0x52D5, 0x753B, 0x914D, 0x4FE1, 0x5411, 
                0x3051, 0x306B, 0x30A2, 0x30C9, 0x30D3, 0x30B7, 0x30B9, 0x30C6, 
                0x30E0, 0x30BA, 0x793E, 0x306E
            ) +
            "FMS 2" +
            String.fromCharCode(0x3092, 0x63A1, 0x7528, 0x3059, 0x308B, 0x3068, 
                0x767a, 0x8868, 0x3057, 0x307e, 0x3057, 0x305F, 0x3002);

            var fontDescription:FontDescription = new FontDescription("MS Mincho");
            var format:ElementFormat = new ElementFormat();
            format.fontSize = 15;
            format.fontDescription = fontDescription;
                        
            var textElement:TextElement = new TextElement(Japanese, format); 
            var textBlock:TextBlock = new TextBlock();
            textBlock.content = textElement;
            textBlock.lineRotation = TextRotation.ROTATE_90;

            var linePosition:Number = this.stage.stageWidth - 120;
            var previousLine:TextLine = null;
        
            while (true) {
                var textLine:TextLine = textBlock.createTextLine(
                    previousLine, 
                    300);
                if (textLine == null) 
                    break;
                textLine.y = 30;    
                textLine.x = linePosition;
                linePosition -= 24;
                addChild(textLine);                
                previousLine = textLine;
            }        
        }
    }
}

Specifies the tab stops for the text in the text block, in the form of a Vector of TabStop objects.

The default value is null, which means no tab stops are specified. When no tab stops are specified (or the insertion point is beyond the last specified tab stop) the runtime creates half-inch tabs by default.

When the tabStops property is set, the TextBlock makes a copy of the Vector for internal use. Modifying the original Vector or its contents does not affect the TextBlock. When the tabStops property is queried, a copy of the internal Vector is returned. Again, modifying this returned vector or its contents does not affect the TextBlock.

Related API Elements

Specifies the TextJustifier to use during line creation.

The default value is a constructed default TextJustifier object.

When the textJustifier property is set, the TextBlock makes a copy of the object for internal use. Modifying the original object does not affect the TextBlock. When the textJustifier property is queried, a copy of the internal object is returned. Again, modifying this returned object does not affect the TextBlock.

More examples

Related API Elements

Indicates the result of a createTextLine() operation. Changing the content of the block invalidates previously broken lines and resets this property to null.

The default value is null.

Values for this property are found in TextLineCreationResult

Related API Elements

Provides a way for the application to associate arbitrary data with the text block. The data could be information that refers to the content, such as a revision date or the name of the author, or it could be cached data that you use during processing.

Creates a TextBlock object

Related API Elements

Instructs the text block to create a line of text from its content, beginning at the point specified by the previousLine parameter and breaking at the point specified by the width parameter. The text line is a TextLine object, which you can add to the display list.

Breaking lines over a range of a text block that has already been broken can change the validity of lines in and beyond the area where breaking takes place. The status of lines can change from VALID to INVALID or POSSIBLY_INVALID. If a newly broken line aligns perfectly with a previously broken line which has a status of POSSIBLY_INVALID, that previously broken line and all following POSSIBLY_INVALID lines change back to a status of VALID. The validity of lines that have been set to values that are not members of TextLineValidity do not change to VALID, but could change to INVALID. Check the firstInvalidLine property after any change to the text block to see where to begin or continue rebreaking text lines.

You can create artificial word breaks by including the Unicode Zero Width Space (ZWSP) character in the text. This can be useful for languages such as Thai, which require a dictionary for correct line breaking. The Flash runtime does not include such a dictionary.

In order to reduce memory overhead, when all the desired lines have been created, unless it is expected that the lines will need to be repeatedly rebroken due to, for example, the resizing of the container, the user should call the releaseLineCreationData() method allowing the text block to dispose of the temporary data associated with line breaking.

Parameters

Related API Elements

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;
    
    public class TextBlock_createTextLineExample extends Sprite {
        
        public function TextBlock_createTextLineExample():void {
            
            var str:String = "I am a TextElement, created from a String and assigned " +
            "to the content property of a TextBlock. The createTextLine() method " +
            "then created these lines, 300 pixels wide, for display." ;
            
            var fontDescription:FontDescription = new FontDescription("Arial");
            var format:ElementFormat = new ElementFormat(fontDescription);
            format.fontSize = 16;
            var textElement:TextElement = new TextElement(str, format); 
            var textBlock:TextBlock = new TextBlock();
            textBlock.content = textElement; 
            createLines(textBlock); 
        }
        
        private function createLines(textBlock:TextBlock):void 
        {            
            var lineWidth:Number = 300;
            var xPos:Number = 15.0;
            var yPos:Number = 20.0;
            
            var textLine:TextLine = textBlock.createTextLine (null, lineWidth);
            while (textLine)
            {
                textLine.x = xPos;
                textLine.y = yPos;
                yPos += textLine.height + 2;
                addChild (textLine);
                textLine = textBlock.createTextLine (textLine, lineWidth);
            }
        }
    }
}

Dumps the underlying contents of the TextBlock as an XML string. This can be useful in automated testing, and includes text, formatting, and layout information.

The following describes the output:

	 >block<
	 	[0-N LINE]
	 >/block<
	 

For a description of the output for each line, see the TextLine.dump() method.

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

Related API Elements

Finds the index of the next atom boundary from the specified character index, not including the character at the specified index. The characters between atom boundaries combine to form one atom in a TextLine, such as an 'e' and a combining acute accent.

Parameters

Related API Elements

Finds the index of the next word boundary from the specified character index, not including the character at the specified index. Word boundaries are determined based on the Unicode properties of the characters.

Parameters

Finds the index of the previous atom boundary to the specified character index, not including the character at the specified index. The characters between atom boundaries combine to form one atom in a TextLine, such as an 'e' and a combining acute accent.

Parameters

Related API Elements

Finds the index of the previous word boundary to the specified character index, not including the character at the specified index. Word boundaries are determined based on the Unicode properties of the characters.

Parameters

Returns the TextLine containing the character specified by the charIndex parameter.

Parameters

Instructs the text block to re-use an existing text line to create a line of text from its content, beginning at the point specified by the previousLine parameter and breaking at the point specified by the width parameter. The text line is a TextLine object, which you can add to the display list. By re-using an existing text line, performance is enhanced due to reduced object creation.

The textLine being recreated is released from whatever text block it is in, if any. In addition, all properties, including inherited properties from DisplayObjectContainer, InteractiveObject, and DisplayObject are reset to their default values. Finally, all children of the line are removed including graphic elements and other decorations, and all event listeners on the line are removed. To improve performance, the only exception to this complete reset is that the line itself is not removed from its parent.

Breaking lines over a range of a text block that has already been broken can change the validity of lines in and beyond the area where breaking takes place. The status of lines can change from VALID to INVALID or POSSIBLY_INVALID. If a newly broken line aligns perfectly with a previously broken line which has a status of POSSIBLY_INVALID, that previously broken line and all following POSSIBLY_INVALID lines change back to a status of VALID. The validity of lines that have been set to values that are not members of TextLineValidity do not change to VALID, but could change to INVALID. Check the firstInvalidLine property after any change to the text block to see where to begin or continue rebreaking text lines.

You can create artificial word breaks by including the Unicode Zero Width Space (ZWSP) character in the text. This can be useful for languages such as Thai, which require a dictionary for correct line breaking. The Flash runtime does not include such a dictionary.

In order to reduce memory overhead, when all the desired lines have been created, unless it is expected that the lines will need to be repeatedly rebroken due to, for example, the resizing of the container, the user should call the releaseLineCreationData() method allowing the text block to dispose of the temporary data associated with line breaking.

Parameters

Related API Elements

var elementFormat:ElementFormat = new ElementFormat();
elementFormat.fontDescription = new FontDescription("Arial");
elementFormat.fontSize = 48;

var textElement:TextElement = new TextElement("Text you'll never see", elementFormat)
var textBlock:TextBlock = new TextBlock(textElement);
var textLine:TextLine = textBlock.createTextLine();
textLine.x = 50;
textLine.y = 50;
addChild(textLine);

// Reuse the element format to preserve the text formatting
var elementTwo:TextElement = new TextElement("Text you see", elementFormat);  
textBlock.content = elementTwo;
textBlock.recreateTextLine(textLine);

// Set the position (and any other display object properties like alpha, children, etc.)
// otherwise, they're all set to default properties.
textLine.x = 50;  
textLine.y = 50;

Instructs the text block to release all the temporary data associated with the creation of text lines. To minimize an application's memory foot print, you should call the releaseLineCreationData() method when you are done creating text lines from a text block. However, to maximize performance for rebreaking the lines (for example when the container is resized) the releaseLineCreationData() method should not be called. It is up to the application to balance memory vs. performance.

The recommended process for text that is not expected to change is: initialize a text block, call the createTextLine() method as often as necessary to create the desired output, and then call the releaseLineCreationData() method.

Related API Elements

Removes a range of text lines from the list of lines maintained by the TextBlock. This allows the lines to be garbage-collected if no other references exist.

Sets the textBlock, nextLine, and previousLine members of the removed lines to null. Sets the validity of the removed lines and of all lines which follow the removed lines in the TextBlock to TextLineValidity.INVALID.

Parameters

Related API Elements