Language version: | ActionScript 3.0 |
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.
elementCount:int
[read-only]
Language version: | ActionScript 3.0
|
The number of elements in the group.
Implementation
public function get elementCount():int
public function GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")
Language version: | ActionScript 3.0 |
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 .
|
See also
public function getElementAt(index:int):ContentElement
Language version: | ActionScript 3.0 |
Retrieves an element from within the group.
Parameters
| index:int — The index of the element to retrieve.
|
Returns
Throws
public function getElementAtCharIndex(charIndex:int):ContentElement
Language version: | ActionScript 3.0 |
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
Throws
| RangeError — If charIndex is not in the range of 0 - rawText.length .
|
public function getElementIndex(element:ContentElement):int
Language version: | ActionScript 3.0 |
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.
|
public function groupElements(beginIndex:int, endIndex:int):GroupElement
Language version: | ActionScript 3.0 |
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
Throws
| RangeError — If beginIndex or endIndex is out of range.
|
public function mergeTextElements(beginIndex:int, endIndex:int):TextElement
Language version: | ActionScript 3.0 |
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 is out of range.
|
|
| ArgumentError — If any of the elements in the specified range is not TextElement.
|
See also
public function replaceElements(beginIndex:int, endIndex:int, newElements:Vector.<ContentElement>):Vector.<ContentElement>
Language version: | ActionScript 3.0
|
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
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 .
|
public function setElements(value:Vector.<ContentElement>):void
Language version: | ActionScript 3.0
|
Sets the elements in the group to the contents of the Vector.
Parameters
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 .
|
public function splitTextElement(elementIndex:int, splitIndex:int):TextElement
Language version: | ActionScript 3.0 |
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
| 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.
|
See also
public function ungroupElements(groupIndex:int):void
Language version: | ActionScript 3.0 |
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
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);
}
}
}
}
© 2004-2022 Adobe Systems Incorporated. All rights reserved.
Mon Feb 26 2024, 5:22 PM GMT