flash.text.engine

# GroupElement - AS3

Package | flash.text.engine
Class | public final class GroupElement
Inheritance | GroupElement ContentElement 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

Adding GraphicElement and GroupElement objects

Related API Elements

ContentElement
GraphicElement
TextBlock
TextElement

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : 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
|  | elementFormat : ElementFormat The ElementFormat object used for the element. | ContentElement
|  | eventMirror : EventDispatcher The EventDispatcher object that receives copies of every event dispatched to valid text lines based on this content element. | ContentElement
|  | groupElement : GroupElement [read-only] The GroupElement object that contains this element, or null if it is not in a group. | ContentElement
|  | rawText : String [read-only] A copy of the text in the element, including any U+FDEF characters. | ContentElement
|  | text : 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
|  | textBlock : flash.text.engine:TextBlock [read-only] The TextBlock to which this element belongs. | ContentElement
|  | textBlockBeginIndex : int [read-only] The index in the text block of the first character of this element. | ContentElement
|  | textRotation : String The rotation to apply to the element as a unit. | ContentElement
|  | userData : * Provides a way for an application to associate arbitrary data with the element. | ContentElement

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0") Creates a new GroupElement instance. | GroupElement
|  | getElementAt(index:int):ContentElement Retrieves an element from within the group. | GroupElement
|  | getElementAtCharIndex(charIndex:int):ContentElement Returns the element containing the character specified by the charIndex parameter. | GroupElement
|  | getElementIndex(element:ContentElement):int 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
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | mergeTextElements(beginIndex:int, endIndex:int):flash.text.engine:TextElement 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
|  | propertyIsEnumerable(name:String):Boolean 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
|  | setElements(value:Vector.<ContentElement>):void Sets the elements in the group to the contents of the Vector. | GroupElement
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | splitTextElement(elementIndex:int, splitIndex:int):flash.text.engine:TextElement Splits a TextElement into two, creating a new TextElement at the specified position. | GroupElement
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | ungroupElements(groupIndex:int):void Ungroups the elements in a nested GroupElement that groupIndex specifies within an outer GroupElement object. | GroupElement
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Public Constants
Hide Inherited Public Constants
Show Inherited Public Constants

| Constant | Defined 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

ContentElement
ElementFormat
flash.events.EventDispatcher
TextLineMirrorRegion
TextRotation
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

TextElement

### 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

TextElement

### 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.

Examples How to use this example
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.
Copy

    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);
                }
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00