flash.text.engine
public final class GroupElement
继承GroupElement Inheritance ContentElement Inheritance Object

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

GroupElement 对象将 TextElement、GraphicElement 或其他 GroupElement 对象组成一个集合,您可以将这些对象作为一个整体分配给 TextBlock 对象的 content 属性。GroupElement 对象也可以只共享另一个 GroupElement 对象内的公共格式。

当 GroupElement 包含另一个 GroupElement 时,内部的 GroupElement 将保留自己的格式设置(ElementFormat 设置)。它不会继承外部 GroupElement 的格式设置。

在 GroupElement 上,大多数格式属性均毫无影响。出于此原因,为具有空 elementFormat 参数的 GroupElement 对象创建文本行是合理的。一些格式属性(例如 kerningligature)会对组成员之间出现交集处的格式设置产生影响。如果组具有 null 格式,则上一元素的格式将确定组成员之间出现交集处的格式设置。

查看示例

另请参见

ContentElement
GraphicElement
TextBlock
TextElement


公共属性
 属性定义方
 Inheritedconstructor : Object
对类对象或给定对象实例的构造函数的引用。
Object
  elementCount : int
[只读 (read-only)] 组中的元素数。
GroupElement
 InheritedelementFormat : ElementFormat
用于元素的 ElementFormat 对象。
ContentElement
 InheritedeventMirror : EventDispatcher
EventDispatcher 对象,该对象将接收调度到基于此内容元素的有效文本行的每个事件的副本。
ContentElement
 InheritedgroupElement : GroupElement
[只读 (read-only)] 包含此元素的 GroupElement 对象;如果此元素不在一个组中,则为 null。
ContentElement
 Inheritedprototype : Object
[静态] 对类或函数对象的原型对象的引用。
Object
 InheritedrawText : String
[只读 (read-only)] 元素中的文本的副本,包括 U+FDEF 字符。
ContentElement
 Inheritedtext : String
[只读 (read-only)] 元素中的文本的副本,不包括表示 String 中的图形元素的 U+FDEF 字符。
ContentElement
 InheritedtextBlock : TextBlock
[只读 (read-only)] 此元素所属的 TextBlock。
ContentElement
 InheritedtextBlockBeginIndex : int
[只读 (read-only)] 文本块中此元素的第一个字符的索引。
ContentElement
 InheritedtextRotation : String
应用于元素的旋转(旋转时将元素作为一个单元)。
ContentElement
 InheriteduserData : *
为作者提供了一种将任意数据与元素相关联的途径。
ContentElement
公共方法
 方法定义方
  
GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")
创建新的 GroupElement 实例。
GroupElement
  
从组中检索一个元素。
GroupElement
  
返回包含由 charIndex 参数指定的字符的元素。
GroupElement
  
返回由 element 参数指定的元素的索引。
GroupElement
  
groupElements(beginIndex:int, endIndex:int):GroupElement
将 beginIndex 和 endIndex 参数指定的元素范围替换为包含这些元素的一个新的 GroupElement。
GroupElement
 Inherited
指示对象是否已经定义了指定的属性。
Object
 Inherited
指示 Object 类的实例是否在指定为参数的对象的原型链中。
Object
  
mergeTextElements(beginIndex:int, endIndex:int):TextElement
将 beginIndex 和 endIndex 参数指定的元素范围中的文本合并到 beginIndex 指定的元素中,但不影响该元素的格式。
GroupElement
 Inherited
指示指定的属性是否存在、是否可枚举。
Object
  
replaceElements(beginIndex:int, endIndex:int, newElements:Vector.<ContentElement>):Vector.<ContentElement>
将 beginIndex 和 endIndex 参数指定的元素范围替换为 newElements 参数的内容。
GroupElement
  
将组中的元素设置为该矢量的内容。
GroupElement
 Inherited
设置循环操作动态属性的可用性。
Object
  
splitTextElement(elementIndex:int, splitIndex:int):TextElement
将组中 TextElement 的一部分拆分为新的 TextElement,并将新 TextElement 插入到组中指定 TextElement 的后面。
GroupElement
 Inherited
返回指定对象的字符串表示形式。
Object
  
对 groupIndex 在外部 GroupElement 对象中指定的嵌套 GroupElement 中的元素取消分组。
GroupElement
 Inherited
返回指定对象的原始值。
Object
公共常量
 常量定义方
 InheritedGRAPHIC_ELEMENT : uint = 0xFDEF
[静态] 指示文本中存在图形元素。
ContentElement
属性详细信息
elementCount属性
elementCount:int  [只读 (read-only)]

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

组中的元素数。



实现
    public function get elementCount():int
构造函数详细信息
GroupElement()构造函数
public function GroupElement(elements:Vector.<ContentElement> = null, elementFormat:ElementFormat = null, eventMirror:EventDispatcher = null, textRotation:String = "rotate0")

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

创建新的 GroupElement 实例。

参数
elements:Vector.<ContentElement> (default = null) — 要包含在 GroupElement 中的 ContentElement 对象的矢量。该矢量可以为空。默认值为 null
 
elementFormat:ElementFormat (default = null) — 组的元素格式。默认值为 null。此格式将应用于组中元素之间的交集,这些元素不继承该格式。
 
eventMirror:EventDispatcher (default = null)EventDispatcher 对象,该对象将接收调度到基于此内容元素创建的文本行的每个事件的副本。默认值为 null
 
textRotation:String (default = "rotate0") — 作为一个单元应用于元素的旋转。将 TextRotation 常量用于此属性。默认值为 TextRotation.ROTATE_0

引发
ArgumentError — 指定的 element 包含 null 元素。
 
ArgumentError — 指定的 element 包含不是 ContentElement 的已知子类的元素。
 
ArgumentError — 指定的 element 包含已作为 TextBlockcontent 指定的元素。
 
ArgumentError — 指定的 element 包含已经是组成员或在 elements 中出现多次的元素。

另请参见

方法详细信息
getElementAt()方法
public function getElementAt(index:int):ContentElement

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

从组中检索一个元素。

参数

index:int — 要检索的元素的索引。

返回
ContentElement

引发
RangeError — 如果 index 超出范围。
getElementAtCharIndex()方法 
public function getElementAtCharIndex(charIndex:int):ContentElement

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

返回包含由 charIndex 参数指定的字符的元素。

参数

charIndex:int — 字符(您想要查找其元素)的从零开始的索引值。值 0 对应于组中的第一个字符,不对应于 TextBlock 中的第一个字符。

返回
ContentElement — 包含 charIndex 处的字符的元素。

引发
RangeError — 如果 charIndex 不在 0 - rawText.length 范围内。
getElementIndex()方法 
public function getElementIndex(element:ContentElement):int

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

返回由 element 参数指定的元素的索引。

参数

element:ContentElement — 想要检索其索引的组中的元素。

返回
int — 由 element 指定的元素的索引;如果元素不在组中,则为 -1。
groupElements()方法 
public function groupElements(beginIndex:int, endIndex:int):GroupElement

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

beginIndexendIndex 参数指定的元素范围替换为包含这些元素的一个新的 GroupElement。正如所设计的一样,将替换从 beginIndex 到 endIndex-1 的元素。

参数

beginIndex:int — 要分组的范围的开始位置的从零开始的索引值。
 
endIndex:int — 要分组的范围的结束位置后面的从零开始的索引值。

返回
GroupElement — 新组。

引发
RangeError — 如果 beginIndexendIndex 超出范围。
mergeTextElements()方法 
public function mergeTextElements(beginIndex:int, endIndex:int):TextElement

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

beginIndexendIndex 参数指定的元素范围中的文本合并到 beginIndex 指定的元素中,但不影响该元素的格式。正如所设计的一样,将合并从 beginIndex 到 endIndex-1 的元素中的文本。在合并了从 beginIndex+1 到 endIndex-1 的元素中的文本之后,这些元素将从组中删除并处于孤立状态,且具有 null group 属性。

参数

beginIndex:int — 要合并的范围的开始位置的从零开始的索引值。
 
endIndex:int — 要合并的范围的结束位置后面的从零开始的索引值。

返回
TextElement — 范围内的第一个文本元素,现在包含该范围内的所有文本。

引发
RangeError — 如果 beginIndexendIndex 超出范围。
 
ArgumentError — 如果指定范围内的任何元素不是 TextElement。

另请参见

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

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

beginIndexendIndex 参数指定的元素范围替换为 newElements 参数的内容。正如所设计的一样,将替换从 beginIndex 到 endIndex-1 的元素。

若要删除元素,请为 newElements 传递 null

若要插入一个元素,请为 beginIndexendIndex 传递相同的值。新元素将插入到指定索引之前。

若要追加一个元素,请为 beginIndexendIndex 传递 elementCount

操作完成后,被替换的元素处于孤立状态,并且具有 null group 属性。

参数

beginIndex:int — 替换范围开始位置的从零开始的索引值。
 
endIndex:int — 替换范围结束位置后面从零开始的索引值。
 
newElements:Vector.<ContentElement> — 要用来替换指定范围元素的元素。

返回
Vector.<ContentElement> — 包含被替换元素的矢量。

引发
RangeError — 指定的 beginIndexendIndex 超出范围。
 
ArgumentError — 指定的 newElements 包含 null 元素。
 
ArgumentError — 指定的 newElements 包含 this
 
ArgumentError — 指定的 newElements 包含不是 ContentElement 的已知子类的元素。
 
ArgumentError — 指定的 newElements 包含已作为 TextBlockcontent 指定的元素。
 
ArgumentError — 指定的 newElements 包含已经是组成员或在 elements 中出现多次的元素。
 
ArgumentError — 如果操作将在 GroupElement 内生成嵌套旋转。
setElements()方法 
public function setElements(value:Vector.<ContentElement>):void

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

将组中的元素设置为该矢量的内容。

参数

value:Vector.<ContentElement>


引发
ArgumentError — 指定的 value 包含 null 元素。
 
ArgumentError — 指定的 value 包含 this
 
ArgumentError — 指定的 value 包含非 ContentElement 的已知子类的元素。
 
ArgumentError — 指定的 value 包含被指定为 TextBlockcontent 的元素。
 
ArgumentError — 指定的 value 包含已经是组成员或在 value 中出现多次的元素。
 
ArgumentError — 如果操作将在 GroupElement 内生成嵌套旋转。
splitTextElement()方法 
public function splitTextElement(elementIndex:int, splitIndex:int):TextElement

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

将组中 TextElement 的一部分拆分为新的 TextElement,并将新 TextElement 插入到组中指定 TextElement 的后面。

参数

elementIndex:int — 组中该元素位置的从零开始的索引值。
 
splitIndex:int — TextElement 中要进行拆分的位置处的字符的从零开始的索引值。指定字符为新 TextElement 中的第一个字符。

返回
TextElement — 包含原始文本元素后面部分的新文本元素。

引发
RangeError — 如果 elementIndexcharIndex 超出范围。
 
ArgumentError — 如果 elementIndex 处的元素不是 TextElement。

另请参见

ungroupElements()方法 
public function ungroupElements(groupIndex:int):void

语言版本: ActionScript 3.0
运行时版本: Flash Player 10, AIR 1.5

groupIndex 在外部 GroupElement 对象中指定的嵌套 GroupElement 中的元素取消分组。操作完成后,取消分组的元素将替代嵌套的 GroupElement,后者将处于孤立状态,具有值为 nullgroup 属性。

参数

groupIndex:int — 要拆分的组的位置的从零开始的索引值。


引发
RangeError — 如果 groupIndex 超出范围。
 
ArgumentError — 如果 groupIndex 处的元素不是 GroupElement。
示例 如何使用示例
GroupElementExample.as

此示例创建了一个红色的框作为 GraphicElement 对象,并将该对象与两个 TextElement 对象结合在一起创建了一个 GroupElement 对象。它将 GroupElement 对象分配给从中创建三条行的 TextBlock 的 content 属性。
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);
            }
        }
    }    
}