ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
GroupElement

Package | flash.text.engine
Class | public final class GroupElement
Inheritance | GroupElement ContentElement Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The GroupElement class represents a collection of ContentElement objects to which you can apply element formatting as a whole. Typically, a GroupElement object contains a collection of TextElement, GraphicElement and other GroupElement objects that represents a block of text and graphics to assign to the `content` property of a TextBlock object. A GroupElement object could also simply share common formatting within another GroupElement object.

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

On a GroiupElement 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

See also

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 used for the element. | ContentElement
|  | eventMirror : EventDispatcher The EventDispatcher object that receives copies of every event dispatched to text lines based on this content element. | ContentElement
|  | groupElement : GroupElement [read-only] The GroupElement which contains this element, or null if it is not in a group. | ContentElement
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | rawText : String [read-only] A copy of the text in the element, including the U+FDEF characters representing graphic elements. | ContentElement
|  | text : String [read-only] A copy of the text in the element, not including the U+FDEF characters representing graphic elements. | ContentElement
|  | textBlock : 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 the author to associate arbitrary data with the element. | ContentElement

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | GroupElement(elements:Vector = 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):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):Vector Replaces the range of elements that the beginIndex and endIndex parameters specify with the contents of the newElements parameter. | GroupElement
|  | setElements(value:Vector):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):TextElement Splits a portion of a TextElement in the group into a new TextElement which is inserted into the group following the specified TextElement. | GroupElement
|  | 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
--- | --- | ---
|  | GRAPHIC_ELEMENT : uint = 0xFDEF [static] Used to indicate the presence a graphic element in the text. | ContentElement

Property Detail

elementCount | property

`elementCount:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The number of elements in the group.

Implementation
`public function get elementCount():int`
Constructor Detail

GroupElement | () | Constructor

`public function GroupElement(elements:Vector = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates a new GroupElement instance.

Parameters

| `elements:Vector` (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 the element as a unit. Use `TextRotation`

Throws

| `ArgumentError` — The `elements` specified contains `null` elements.
| `ArgumentError` — The `elements` specified contains elements which are not a known subclass of `ContentElement`.
| `ArgumentError` — The `elements` specified contains elements which are specified as the `content` of a `TextBlock`.
| `ArgumentError` — The `elements` specified contains elements which are already members of a group,or appear more than once in the `elements`.

See also

ContentElement
ElementFormat
flash.events.EventDispatcher
TextLineMirrorRegion
TextRotation
Method Detail

getElementAt | () | method

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

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Player Version : | Flash Player 10

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

Player Version : | Flash Player 10

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

Player Version : | Flash Player 10

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` are out of range.

mergeTextElements | () | method |

`public function mergeTextElements(beginIndex:int, endIndex:int):TextElement`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

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

| `TextElement` — The first text element in the range, now containing all the text in the range.

Throws

| `RangeError` — if `beginIndex` or `endIndex` are out of range.
| `ArgumentError` — if any of the elements in the specified range are not TextElement.

See also

TextElement

replaceElements | () | method |

`public function replaceElements(beginIndex:int, endIndex:int, newElements:Vector):Vector`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Replaces the range of elements that the `beginIndex` and `endIndex` parameters specify with the contents of the `newElements` parameter. As designed, 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.

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` — The elements to use to replace the specified range of elements.

Returns

| `Vector` — A Vector containing the elements that were replaced.

Throws

| `RangeError` — The `beginIndex` or `endIndex` specified is out of range.
| `ArgumentError` — The `newElements` specified contains `null` elements.
| `ArgumentError` — The `newElements` specified contains `this`.
| `ArgumentError` — The `newElements` specified contains elements that are not a known subclass of `ContentElement` .
| `ArgumentError` — The `newElements` specified contains elements that are specified as the `content` of a `TextBlock`.
| `ArgumentError` — The `newElements` specified contains 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):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Parameters

| `value:Vector`

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):TextElement`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Splits a portion of a TextElement in the group into a new TextElement which is inserted into the group following the specified TextElement.

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

| `TextElement` — The new text element containing the latter portion of the original text element.

Throws

| `RangeError` — if `elementIndex` or `charIndex` are out of range.
| `ArgumentError` — if the element at `elementIndex` is not a TextElement.

See also

TextElement

ungroupElements | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

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 an GroupElement.

Examples How to use examples
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 = "This red box is a GraphicElement ";
                var str2 = " 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.textHeight+8;
                    textLine.y = yPos;
                    textLine = textBlock.createTextLine(textLine, line_length);
                }
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00