ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Show Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes
flash.text.engine 

GroupElement  - AS3

Packageflash.text.engine
Classpublic final class GroupElement
InheritanceGroupElement Inheritance ContentElement Inheritance Object

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

A GroupElement object groups a collection of TextElement, GraphicElement, or other GroupElement objects that you can assign as a unit to the content property of a TextBlock object. A GroupElement object can also simply share common formatting within another GroupElement object.

When a GroupElement contains another GroupElement, the inner GroupElement retains its own formatting (ElementFormat settings). It does not inherit the formatting of the outer GroupElement.

On a GroupElement, most of the format properties have no impact. For this reason, it is legal to create a text line for a GroupElement object that has a null elementFormat parameter. A few format properties such as kerning and ligature do affect formatting where intersections occur between members of the group. If the group has a null format, the format of the preceding element determines the formatting where intersections occur between members of the group.

View the examples

More examples

Related API Elements



Public Properties
 PropertyDefined By
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  elementCount : int
[read-only] The number of elements in the group.
GroupElement
 InheritedelementFormat : ElementFormat
The ElementFormat object used for the element.
ContentElement
 InheritedeventMirror : EventDispatcher
The EventDispatcher object that receives copies of every event dispatched to valid text lines based on this content element.
ContentElement
 InheritedgroupElement : GroupElement
[read-only] The GroupElement object that contains this element, or null if it is not in a group.
ContentElement
 InheritedrawText : String
[read-only] A copy of the text in the element, including any U+FDEF characters.
ContentElement
 Inheritedtext : String
[read-only] A copy of the text in the element, not including any U+FDEF characters, which represent graphic elements in the String.
ContentElement
 InheritedtextBlock : flash.text.engine:TextBlock
[read-only] The TextBlock to which this element belongs.
ContentElement
 InheritedtextBlockBeginIndex : int
[read-only] The index in the text block of the first character of this element.
ContentElement
 InheritedtextRotation : String
The rotation to apply to the element as a unit.
ContentElement
 InheriteduserData : *
Provides a way for an application to associate arbitrary data with the element.
ContentElement
Public Methods
 MethodDefined By
  
GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")
Creates a new GroupElement instance.
GroupElement
  
Retrieves an element from within the group.
GroupElement
  
Returns the element containing the character specified by the charIndex parameter.
GroupElement
  
Returns the index of the element specified by the element parameter.
GroupElement
  
groupElements(beginIndex:int, endIndex:int):GroupElement
Replaces the range of elements that the beginIndex and endIndex parameters specify with a new GroupElement containing those elements.
GroupElement
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Merges the text from the range of elements that the beginIndex and endIndex parameters specify into the element specified by beginIndex without affecting the format of that element.
GroupElement
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
replaceElements(beginIndex:int, endIndex:int, newElements:Vector.<ContentElement>):Vector.<ContentElement>
Replaces the range of elements that the beginIndex and endIndex parameters specify with the contents of the newElements parameter.
GroupElement
  
Sets the elements in the group to the contents of the Vector.
GroupElement
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
Splits a TextElement into two, creating a new TextElement at the specified position.
GroupElement
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
Ungroups the elements in a nested GroupElement that groupIndex specifies within an outer GroupElement object.
GroupElement
 Inherited
Returns the primitive value of the specified object.
Object
Public Constants
 ConstantDefined By
Property Detail

elementCount

property
elementCount:int  [read-only]

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

The number of elements in the group.



Implementation
    public function get elementCount():int
Constructor Detail

GroupElement

()Constructor
public function GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

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

Creates a new GroupElement instance.

Parameters
elements:Vector.<ContentElement> (default = null) — A Vector of ContentElement objects to be contained in the GroupElement. The Vector can be empty. The default value is null.
 
elementFormat:ElementFormat (default = null) — The element format for the group. The default value is null. This format applies to the intersections between elements in the group; those elements do not inherit the format.
 
eventMirror:EventDispatcher (default = null) — The EventDispatcher object that receives copies of every event dispatched to text lines created based on this content element. The default value is null.
 
textRotation:String (default = "rotate0") — The rotation applied to the element as a unit. Use TextRotation constants for this property. The default value is TextRotation.ROTATE_0.

Throws
ArgumentError — The specified element contains null elements.
 
ArgumentError — The specified element contains an element that is not a known subclass of ContentElement.
 
ArgumentError — The specified element contains elements that are specified as the content of a TextBlock.
 
ArgumentError — The specified element contains elements that are already members of a group, or appear more than once in the elements.

Related API Elements

Method Detail

getElementAt

()method
public function getElementAt(index:int):ContentElement

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

Retrieves an element from within the group.

Parameters

index:int — The index of the element to retrieve.

Returns
ContentElement

Throws
RangeError — If index is out of range.

getElementAtCharIndex

()method 
public function getElementAtCharIndex(charIndex:int):ContentElement

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

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

Parameters

charIndex:int — The zero-based index value for the character whose element you want to find. A value of 0 corresponds to the first character in the group, not the first character in the TextBlock.

Returns
ContentElement — The element containing the character at charIndex.

Throws
RangeError — If charIndex is not in the range of 0 - rawText.length.

getElementIndex

()method 
public function getElementIndex(element:ContentElement):int

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

Returns the index of the element specified by the element parameter.

Parameters

element:ContentElement — The element in the group whose index you want to retrieve.

Returns
int — The index of the element specified by element, or -1 if the element is not in the group.

groupElements

()method 
public function groupElements(beginIndex:int, endIndex:int):GroupElement

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

Replaces the range of elements that the beginIndex and endIndex parameters specify with a new GroupElement containing those elements. As designed, the elements from beginIndex to endIndex-1 are replaced.

Parameters

beginIndex:int — The zero-based index value for the start position of the range to group.
 
endIndex:int — The zero-based index value following the end position of the range to group.

Returns
GroupElement — The new group.

Throws
RangeError — If beginIndex or endIndex is out of range.

mergeTextElements

()method 
public function mergeTextElements(beginIndex:int, endIndex:int):flash.text.engine:TextElement

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

Merges the text from the range of elements that the beginIndex and endIndex parameters specify into the element specified by beginIndex without affecting the format of that element. As designed, the text from elements from beginIndex to endIndex-1 are merged. After their text has been merged, elements from beginIndex+1 to endIndex-1 are removed from the group and orphaned, with null group properties.

Parameters

beginIndex:int — The zero-based index value for the start position of the range to merge.
 
endIndex:int — The zero-based index value following the end position of the range to merge.

Returns
flash.text.engine:TextElement — The first text element in the range, now containing all the text in the range.

Throws
RangeError — If beginIndex or endIndex is out of range.
 
ArgumentError — If any of the elements in the specified range is not TextElement.

Related API Elements

replaceElements

()method 
public function replaceElements(beginIndex:int, endIndex:int, newElements:Vector.<ContentElement>):Vector.<ContentElement>

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

Replaces the range of elements that the beginIndex and endIndex parameters specify with the contents of the newElements parameter. The elements from beginIndex to endIndex-1 are replaced.

To delete elements, pass null for newElements. To insert an element, pass the same value for beginIndex and endIndex. The new element is inserted before the specified index. To append an element, pass elementCount for beginIndex and endIndex.

After the operation, the replaced elements are orphaned, with null group properties and returned.

Parameters

beginIndex:int — The zero-based index value for the start position of the replacement range.
 
endIndex:int — The zero-based index value following the end position of the replacement range.
 
newElements:Vector.<ContentElement> — The elements to use to replace the specified range of elements.

Returns
Vector.<ContentElement> — A Vector containing the elements that were replaced.

Throws
RangeError — The beginIndex or endIndex specified is out of range.
 
ArgumentError — The newElements specified contain null elements.
 
ArgumentError — The newElements specified contain this.
 
ArgumentError — The newElements specified contain elements that are not a known subclass of ContentElement .
 
ArgumentError — The newElements specified contain elements that are specified as the content of a TextBlock.
 
ArgumentError — The newElements specified contain elements that are already members of a group or appear more than once in the elements.
 
ArgumentError — If the operation would result in nested rotations within the GroupElement.

setElements

()method 
public function setElements(value:Vector.<ContentElement>):void

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

Sets the elements in the group to the contents of the Vector.

Parameters

value:Vector.<ContentElement>

Throws
ArgumentError — The value specified contains null elements.
 
ArgumentError — The value specified contains this.
 
ArgumentError — The value specified contains elements that are not a known subclass of ContentElement .
 
ArgumentError — The value specified contains elements that are specified as the content of a TextBlock.
 
ArgumentError — The value specified contains elements that are already members of a group, or appear more than once in the value.
 
ArgumentError — If the operation would result in nested rotations within the GroupElement.

splitTextElement

()method 
public function splitTextElement(elementIndex:int, splitIndex:int):flash.text.engine:TextElement

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

Splits a TextElement into two, creating a new TextElement at the specified position.

Parameters

elementIndex:int — The zero-based index value for the position of the element in the group.
 
splitIndex:int — The zero-based index value for the character in the TextElement where the split is to occur. The specified character is the first character in the new TextElement.

Returns
flash.text.engine:TextElement — The new text element containing the latter portion of the original text element.

Throws
RangeError — If elementIndex or charIndex is out of range.
 
ArgumentError — If the element at elementIndex is not a TextElement.

Related API Elements

ungroupElements

()method 
public function ungroupElements(groupIndex:int):void

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

Ungroups the elements in a nested GroupElement that groupIndex specifies within an outer GroupElement object. After the operation, the ungrouped elements replace the nested GroupElement, which becomes an orphan with a null group property.

Parameters

groupIndex:int — The zero-based index value for the position of the group to be split.

Throws
RangeError — If groupIndex is out of range.
 
ArgumentError — If the element at groupIndex is not a GroupElement.
GroupElementExample.as

This example creates a red box as a GraphicElement object and combines it with two TextElement objects to create a GroupElement object. It assigns the GroupElement object to the content property of a TextBlock, from which it creates three lines.

package {

    import flash.display.Sprite;
    import flash.display.MovieClip;
    import flash.text.engine.ContentElement;
    import flash.text.engine.TextBlock;
    import flash.text.engine.TextElement;
    import flash.text.engine.GraphicElement;
    import flash.text.engine.GroupElement;
    import flash.text.engine.TextLine;
    import flash.text.engine.ElementFormat;
    import flash.text.engine.FontDescription;
    
    public class GroupElementExample extends Sprite {
        
        public function GroupElementExample():void {
            
            var redBox:MovieClip = new MovieClip();
            redBox.graphics.beginFill(0xCC0000, 1.0);
            redBox.graphics.drawRect(0, 0, 20, 20);
            redBox.graphics.endFill(); 
            
            var format:ElementFormat = new ElementFormat();
            var fontDescription:FontDescription = new FontDescription("Arial");
            format.fontSize = 16;
            format.fontDescription = fontDescription;
            
            var str1:String = "This red box is a GraphicElement ";
            var str2:String = " in the middle of two TextElements, " +
            " which together make " +
            "up a GroupElement in a TextBlock that is broken into three lines.";
            
            var textElement1:TextElement = new TextElement(str1,format);
            var graphicElement:GraphicElement = new GraphicElement(redBox,redBox.width,redBox.height, format);
            var textElement2:TextElement = new TextElement(str2, format);
            var groupVector:Vector.<ContentElement> = new Vector.<ContentElement>();
            groupVector.push(textElement1, graphicElement, textElement2);
            var groupElement = new GroupElement(groupVector);
            var textBlock:TextBlock = new TextBlock();
            textBlock.content = groupElement;
            createTextLines(textBlock);
        }
        
        private function createTextLines(textBlock:TextBlock):void 
        {
        
            var yPos = 20;
            var line_length:Number = 450;
            var textLine:TextLine = textBlock.createTextLine (null, line_length);
 
            while (textLine)
            {
                addChild(textLine);
                textLine.x = 15;
                yPos += textLine.height+8;
                textLine.y = yPos;
                textLine = textBlock.createTextLine(textLine, line_length);
            }
        }
    }    
}