Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.text.engine 
ElementFormat 
Packageflash.text.engine
Classpublic final class ElementFormat
InheritanceElementFormat Inheritance Object

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

The ElementFormat class represents formatting information which can be applied to a ContentElement. Use the ElementFormat class to create specific text formatting for the various subclasses of ContentElement. The properties of the ElementFormat class apply to device and embedded fonts.

An ElementFormat object that is applied to a ContentElement in a TextBlock does not invalidate the TextBlock. Once an ElementFormat has been applied to a ContentElement, its locked property is set to true. The properties of a locked ElementFormat object cannot be changed. Instead, use the clone() method to create an unlocked copy of the object, which can be modified and assigned to the ContentElement.

View the examples

See also



Public Properties
 PropertyDefined By
  alignmentBaseline : String
Specifies the type of baseline in the containing element to which to align the dominant baselines of elements having this format.
ElementFormat
  alpha : Number
Specifies the transparency of the line elements affected by this obect.
ElementFormat
  baselineShift : Number
Indicates the baseline shift for the element in pixels.
ElementFormat
  breakOpportunity : String
The line break opportunity applied to this text.
ElementFormat
  color : uint
Indicates the color of the text.
ElementFormat
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  digitCase : String
The digit case used for this text.
ElementFormat
  digitWidth : String
The digit width used for this text.
ElementFormat
  dominantBaseline : String
Specifies the type of baseline to use as the dominant baseline.
ElementFormat
  fontDescription : FontDescription
An object whose properties describe a font.
ElementFormat
  fontSize : Number
The size of text in pixels.
ElementFormat
  kerning : String
Kerning adjusts the pixels between certain character pairs to improve readability.
ElementFormat
  ligatureLevel : String
The ligature level used for this text.
ElementFormat
  locale : String
The locale of the text.
ElementFormat
  locked : Boolean
Indicates whether the ElementFormat is locked.
ElementFormat
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  textRotation : String
Sets the rotation applied to individual glyphs.
ElementFormat
  trackingLeft : Number
The tracking or manual kerning applied to the left of each glyph in pixels.
ElementFormat
  trackingRight : Number
The tracking or manual kerning applied to the right of each glyph in pixels.
ElementFormat
  typographicCase : String
The typographic case used for this text.
ElementFormat
Public Methods
 MethodDefined By
  
ElementFormat(fontDescription:FontDescription = null, fontSize:Number = 12.0, color:uint = 0x000000, alpha:Number = 1.0, textRotation:String = "auto", dominantBaseline:String = "roman", alignmentBaseline:String = "useDominantBaseline", baselineShift:Number = 0.0, kerning:String = "on", trackingRight:Number = 0.0, trackingLeft:Number = 0.0, locale:String = "en", breakOpportunity:String = "auto", digitCase:String = "default", digitWidth:String = "default", ligatureLevel:String = "common", typographicCase:String = "default")
Creates an ElementFormat object.
ElementFormat
  
Constructs an unlocked, cloned copy of the ElementFormat.
ElementFormat
  
Returns a FontMetrics object with properties which describe the emBox, strikethrough position, strikethrough thickness, underline position, and underline thickness for the font specified by fontDescription and fontSize.
ElementFormat
 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
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 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
 Inherited
Returns the primitive value of the specified object.
Object
Property Detail

alignmentBaseline

property
alignmentBaseline:String

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

Specifies the type of baseline in the containing element to which to align the dominant baselines of elements having this format. Use TextBaseline constants for this property.

The largest vertical element in the line determines the alignment of baselines unless TextBlock.baselineFontDescription and TextBlock.baselineFontSize are set to override that logic.

The default value is TextBaseline.USE_DOMINANT_BASELINE.

To set values for this property, use the following string values:

String valueDescription
TextBaseline.ROMANThe dominantBaseline aligns with the roman baseline of the line.
TextBaseline.ASCENTThe dominantBaseline aligns with the ascent baseline of the line.
TextBaseline.DESCENTThe dominantBaseline aligns with the descent baseline of the line.
TextBaseline.IDEOGRAPHIC_TOPThe dominantBaseline aligns with the ideographic top baseline of the line.
TextBaseline.IDEOGRAPHIC_CENTERThe dominantBaseline aligns with the ideographic center baseline of the line.
TextBaseline.IDEOGRAPHIC_BOTTOMThe dominantBaseline aligns with the ideographic bottom baseline of the line.
TextBaseline.USE_DOMINANT_BASELINEThe dominantBaseline aligns with the same baseline of the line.

SubclassEffect of setting property
GraphicElementSets the alignment baseline of the line to which the dominantBaseline of the graphic element aligns.
GroupElementHas no effect.
TextElementSets the alignment baseline of the line to which the dominantBaseline of the text element aligns.



Implementation
    public function get alignmentBaseline():String
    public function set alignmentBaseline(value:String):void

Throws
ArgumentError — If set to any value which is not a member of TextBaseline.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

alpha

property 
alpha:Number

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

Specifies the transparency of the line elements affected by this obect. Valid values range from 0 (fully transparent) to 1 (fully opaque). Display objects with alpha set to 0 are active, even though they are invisible.

The default value is 1.

SubclassEffect of setting property
GraphicElementApplies the specified alpha to the graphic element. Combines multiplicatively with any alpha set on the graphic DisplayObject itself or on the TextLine.
GroupElementHas no effect.
TextElementApplies the specified alpha to the text element. Combines multiplicatively with any alpha set on the TextLine.



Implementation
    public function get alpha():Number
    public function set alpha(value:Number):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

baselineShift

property 
baselineShift:Number

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

Indicates the baseline shift for the element in pixels.

The element is shifted away from the dominantBaseline by this amount. The offset is added to the y position of the members of the element, so in non-rotated text, a positive baseline shift moves the element down and a negative baseline shift moves the element up.

The default value is 0.0, indicating no shift.

SubclassEffect of setting property
GraphicElementShifts the graphic away from the baseline.
GroupElementHas no effect.
TextElementShifts the text away from the baseline.



Implementation
    public function get baselineShift():Number
    public function set baselineShift(value:Number):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

breakOpportunity

property 
breakOpportunity:String

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

The line break opportunity applied to this text. This property determines which characters can be used for breaking when wrapping text is broken into multiple lines. Use BreakOpportunity constants for this property.

The default value is BreakOpportunity.AUTO.

To set values for this property, use the following string values:

String valueDescription
BreakOpportunity.AUTOLine breaking opportunities are based on standard Unicode character properties, such as breaking between words and on hyphens.
BreakOpportunity.ANYAny character in the ContentElement object is treated as a line break opportunity. This value is typically used when Roman text is embedded in Asian text and it is desirable for breaks to happen in the middle of words.
BreakOpportunity.NONENo characters in the range are treated as line break opportunities.
BreakOpportunity.ALLAll characters in the range are treated as line break opportunities, meaning that a line break will occur after each character. Useful for creating effects like text on a path.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementDetermines the break opportunity between adjacent text elements in the group. If the elementFormat of the group is null, the format of the first of the adjacent elements is used.
TextElementDetermines the break opportunity between the characters in the text element.



Implementation
    public function get breakOpportunity():String
    public function set breakOpportunity(value:String):void

Throws
ArgumentError — If set to a value not a member of BreakOpportunity.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

color

property 
color:uint

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

Indicates the color of the text. An integer containing three 8-bit RGB components; for example, 0xFF0000 is red and 0x00FF00 is green.

The default value is 0x000000, which is black.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementSets the color of the text.



Implementation
    public function get color():uint
    public function set color(value:uint):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

digitCase

property 
digitCase:String

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

The digit case used for this text. Digit case affects the style and positioning of groups of numeric characters. Use DigitCase constants for this property.

The default value is DigitCase.DEFAULT.

To set values for this property, use the following string values:

String valueDescription
DigitCase.DEFAULTApplies default digit case to the text.
DigitCase.LININGApplies lining digit case to the text.
DigitCase.OLD_STYLEApplies old style digit case to the text.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the digit case used for the text in the element.



Implementation
    public function get digitCase():String
    public function set digitCase(value:String):void

Throws
ArgumentError — If set to any value which is not a member of DigitCase.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

digitWidth

property 
digitWidth:String

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

The digit width used for this text. Use DigitWidth constants for this property.

The default value is DigitWidth.DEFAULT.

To set values for this property, use the following string values:

String valueDescription
DigitWidth.DEFAULTApplies default digit width to the text.
DigitWidth.PROPORTIONALApplies proportional digit width to the text.
DigitWidth.TABULARApplies tabular digit width to the text.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the digit width used for the text in the element.



Implementation
    public function get digitWidth():String
    public function set digitWidth(value:String):void

Throws
ArgumentError — If set to any value which is not a member of DigitWidth.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

dominantBaseline

property 
dominantBaseline:String

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

Specifies the type of baseline to use as the dominant baseline. The dominant baseline is aligned with the alignment baseline to determine the vertical position of the element on the line. Use TextBaseline constants for this property.

The content of the element determines the baselines. In the case of a TextElement, the font and the point size determine the baselines. In the case of a GraphicElement, the height of the element determines the baselines.

The default value is TextBaseline.ROMAN.

To set values for this property, use the following string values:

String valueDescription
TextBaseline.ROMANThe roman baseline of the element aligns with the alignmentBaseline.
TextBaseline.ASCENTThe ascent baseline of the element aligns with the alignmentBaseline.
TextBaseline.DESCENTThe descent baseline of the element aligns with the alignmentBaseline.
TextBaseline.IDEOGRAPHIC_TOPThe ideographic top baseline of the element aligns with the alignmentBaseline.
TextBaseline.IDEOGRAPHIC_CENTERThe ideographic center baseline of the element aligns with the alignmentBaseline.
TextBaseline.IDEOGRAPHIC_BOTTOMThe ideographic bottom baseline of the element aligns with the alignmentBaseline.

SubclassEffect of setting property
GraphicElementDetermines which of the baselines of the graphic element aligns with the alignmentBaseline.
GroupElementHas no effect.
TextElementDetermines which of the baselines of the text element aligns with the alignmentBaseline.



Implementation
    public function get dominantBaseline():String
    public function set dominantBaseline(value:String):void

Throws
ArgumentError — If set to any value which is not a member of TextBaseline.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

fontDescription

property 
fontDescription:FontDescription

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

An object whose properties describe a font.

The default value is a default-constructed FontDescription object.

When the fontDescription property is set, the FontDescription object provided is locked: its locked property is set to true. A locked FontDescription cannot be modified.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the font used for the text in the element.



Implementation
    public function get fontDescription():FontDescription
    public function set fontDescription(value:FontDescription):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

fontSize

property 
fontSize:Number

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

The size of text in pixels.

The default value is 12.0.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the size in pixels for the text in the element.



Implementation
    public function get fontSize():Number
    public function set fontSize(value:Number):void

Throws
ArgumentError — If set to a value less than zero.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

kerning

property 
kerning:String

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

Kerning adjusts the pixels between certain character pairs to improve readability. Kerning is supported for all fonts which have kerning tables.

The default value is Kerning.ON.

To set values for this property, use the following constants in the Kerning class:

String valueDescription
Kerning.ONKerning is enabled.
Kerning.OFFKerning is disabled.
Kerning.AUTOKerning is enabled except where inappropriate in Asian typography. Kerning is applied between two characters if neither is Kanji, Hiragana, or Katakana.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementDetermines whether kerning is applied between adjacent text elements in the group. If the elementFormat of the group is null, the format of the first of the adjacent elements is used.
TextElementDetermines whether kerning is applied between the characters in the text element.



Implementation
    public function get kerning():String
    public function set kerning(value:String):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

ligatureLevel

property 
ligatureLevel:String

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

The ligature level used for this text. A ligature occurs where two or more letter-forms are joined as a single glyph. Ligatures usually replace consecutive characters sharing common components, such as the letter pairs 'fi', 'fl', or 'ae'. They are used with both Latin and non-Latin character sets. Use LigatureLevel constants for this property.

The default value is LigatureLevel.COMMON.

To set values for this property, use the following string values:

String valueDescription
LigatureLevel.NONENo ligatures are created.
LigatureLevel.MINIMUMMinimal ligatures are created.
LigatureLevel.COMMONCommon ligatures are created.
LigatureLevel.UNCOMMONUncommon ligatures are created.
LigatureLevel.EXOTICExotic ligatures are created.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementDetermines the ligature level between adjacent text elements in the group. If the elementFormat of the group is null, the format of the first of the adjacent elements is used.
TextElementDetermines the ligature level between the characters in the text element.



Implementation
    public function get ligatureLevel():String
    public function set ligatureLevel(value:String):void

Throws
ArgumentError — If set to any value which is not a member of LigatureLevel.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

locale

property 
locale:String

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

The locale of the text. Controls case transformations and shaping. Standard locale identifiers are used. For example "en", "en_US" and "en-US" are all English, "ja" is Japanese. See iso639-2 code list for a list of locale codes.

The default value is "en".

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines transformations and shaping for the text in the element.



Implementation
    public function get locale():String
    public function set locale(value:String):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

locked

property 
locked:Boolean

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

Indicates whether the ElementFormat is locked. If true the ElementFormat cannot be modified. Call ElementFormat.clone() to get an unlocked copy of the ElementFormat object.



Implementation
    public function get locked():Boolean
    public function set locked(value:Boolean):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

textRotation

property 
textRotation:String

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

Sets the rotation applied to individual glyphs. Use constants defined in the TextRotation class for this property.

The default value is TextRotation.AUTO.

The final rotation of any glyph is the sum of ElementFormat.textRotation, ContentElement.textRotation, and TextBlock.lineRotation.

You typically use this property for Asian text where characters must be rotated to display properly in vertical layout. Use TextRotation.AUTO in combination with TextBlock.lineRotation = TextRotation.ROTATE_90 to accomplish this.

Setting this property on fonts which do not contain vertical layout information can give undesirable results. Fonts that contain a vmtx or VORG table, such as the Japanese font, "MS Mincho", work correctly because the tables supply the data that the layout engine requires for correct layout. Fonts such as Verdana, which do not contain the necessary information, do not.

To set values for this property, use the following string values:

String valueDescription
TextRotation.ROTATE_0Glyphs are not rotated.
TextRotation.ROTATE_90Glyphs are rotated 90 degrees clockwise.
TextRotation.ROTATE_180Glyphs are rotated 180 degrees.
TextRotation.ROTATE_270Glyphs are rotated 270 degrees clockwise.
TextRotation.AUTOSpecifies a 90 degree counter clockwise rotation for full width and wide glyphs only, as determined by the Unicode properties of the glyph. This value is typically used with Asian text to rotate only those glyphs that require rotation. This rotation is applied only in vertical text to return full width and wide characters to a vertical orientation without affecting other characters.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the rotation of the glyphs in the text element.



Implementation
    public function get textRotation():String
    public function set textRotation(value:String):void

Throws
ArgumentError — If set to any value which is not a member of TextRotation.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

trackingLeft

property 
trackingLeft:Number

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

The tracking or manual kerning applied to the left of each glyph in pixels. If kerning is enabled, the trackingLeft value is added to the values in the kerning table for the font. If kerning is disabled, the trackingLeft value is used as a manual kerning value. Supports both positive and negative values.

Typically, the desired tracking value is split between trackingRight and trackingLeft. Otherwise, in mixed directionality text, there is twice the tracking at one bidi boundary and none at the other.

The default value is 0.0.

SubclassEffect of setting property
GraphicElementDetermines the tracking applied to the left side of the graphic.
GroupElementHas no effect.
TextElementDetermines the tracking applied to the left side of characters in the text element.

Example:

          //positive tracking added to kerning
          var ef1:ElementFormat = new ElementFormat();
          ef1.kerning = flash.text.engine.Kerning.ON;
          ef1.trackingLeft = 0.5;
     
          //negative manual kerning
          var ef2:ElementFormat = new ElementFormat();
          ef2.kerning = flash.text.engine.Kerning.OFF;
          ef2.trackingLeft = -1.0;
     



Implementation
    public function get trackingLeft():Number
    public function set trackingLeft(value:Number):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

trackingRight

property 
trackingRight:Number

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

The tracking or manual kerning applied to the right of each glyph in pixels. If kerning is enabled, the trackingRight value is added to the values in the kerning table for the font. If kerning is disabled, the trackingRight value is used as a manual kerning value. Supports both positive and negative values.

Typically, the desired tracking value is split between trackingRight and trackingLeft. Otherwise, in mixed directionality text, there is twice the tracking at one bidi boundary and none at the other.

The default value is 0.0.

SubclassEffect of setting property
GraphicElementDetermines the tracking applied to the right side of the graphic.
GroupElementHas no effect.
TextElementDetermines the tracking applied to the right side of characters in the text element.

Example:

          //positive tracking added to kerning
          var ef1:ElementFormat = new ElementFormat();
          ef1.kerning = flash.text.engine.Kerning.ON;
          ef1.trackingRight = 0.5;
     
          //negative manual kerning
          var ef2:ElementFormat = new ElementFormat();
          ef2.kerning = flash.text.engine.Kerning.OFF;
          ef2.trackingRight = -1.0;
     



Implementation
    public function get trackingRight():Number
    public function set trackingRight(value:Number):void

Throws
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

typographicCase

property 
typographicCase:String

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

The typographic case used for this text. Use constants defined in the TypographicCase class for this property.

The default value is TypographicCase.DEFAULT.

To set values for this property, use the following string values:

String valueDescription
TypographicCase.DEFAULTSpecifies that normal case is used for all characters.
TypographicCase.TITLESpecifies that uppercase characters use title glyphs on output.
TypographicCase.CAPSSpecifies that spacing is adjusted for uppercase characters on output.
TypographicCase.SMALL_CAPSSpecifies that uppercase characters use small caps glyphs on output.
TypographicCase.UPPERCASESpecifies that all characters use uppercase glyphs on output.
TypographicCase.LOWERCASESpecifies that all characters use lowercase glyphs on output.
TypographicCase.CAPS_AND_SMALL_CAPSSpecifies that all lowercase characters use small caps glyphs on output.

SubclassEffect of setting property
GraphicElementHas no effect.
GroupElementHas no effect.
TextElementDetermines the typographic case used for the text in the element.



Implementation
    public function get typographicCase():String
    public function set typographicCase(value:String):void

Throws
ArgumentError — If set to a value not a member of TypographicCase.
 
IllegalOperationError — If set after the ElementFormat object is locked (locked is true).

See also

Constructor Detail

ElementFormat

()Constructor
public function ElementFormat(fontDescription:FontDescription = null, fontSize:Number = 12.0, color:uint = 0x000000, alpha:Number = 1.0, textRotation:String = "auto", dominantBaseline:String = "roman", alignmentBaseline:String = "useDominantBaseline", baselineShift:Number = 0.0, kerning:String = "on", trackingRight:Number = 0.0, trackingLeft:Number = 0.0, locale:String = "en", breakOpportunity:String = "auto", digitCase:String = "default", digitWidth:String = "default", ligatureLevel:String = "common", typographicCase:String = "default")

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

Creates an ElementFormat object.

Parameters
fontDescription:FontDescription (default = null) — The FontDescription object which identifies the font used with this element format. The default value is null. If no font description is provided, a default font description is constructed.
 
fontSize:Number (default = 12.0) — The size of text in pixels.
 
color:uint (default = 0x000000) — The color of text. A hexadecimal number containing three 8-bit RGB components; for example, 0xFF0000 is red and 0x00FF00 is green.
 
alpha:Number (default = 1.0) — The alpha property applied to all line atoms based on the element format.
 
textRotation:String (default = "auto") — the rotation applied to individual glyphs. Use TextRotation constants for this property.
 
dominantBaseline:String (default = "roman") — The baseline to which the glyphs in the text snap. Use TextBaseline constants for this property.
 
alignmentBaseline:String (default = "useDominantBaseline") — The baseline on the containing line to which the dominant baseline snaps. Use TextBaseline constants for this property.
 
baselineShift:Number (default = 0.0) — The baseline shift for the text in pixels em.
 
kerning:String (default = "on") — The kerning used for this text. Use constants defined in the Kerning class.
 
trackingRight:Number (default = 0.0) — The tracking or manual kerning applied to the right of each glyph in pixels.
 
trackingLeft:Number (default = 0.0) — The tracking or manual kerning applied to the left of each glyph in pixels.
 
locale:String (default = "en") — The locale of the text.
 
breakOpportunity:String (default = "auto") — The line break opportunity applied to this text. Use BreakOpportunity constants for this property.
 
digitCase:String (default = "default") — The digit case used for this text. Use DigitCase constants for this property.
 
digitWidth:String (default = "default") — The digit width used for this text. Use DigitWidth constants for this property.
 
ligatureLevel:String (default = "common") — The ligature level used for this text. Use LigatureLevel constants for this property.
 
typographicCase:String (default = "default") — The typographic case used for this text. Use TypographicCase constants for this property.

Throws
ArgumentError — The fontSize specified is less than 0.
 
ArgumentError — The textRotation specified is not a member of TextRotation.
 
ArgumentError — The dominantBaseline specified is not a member of TextBaseline.
 
ArgumentError — The alignmentBaseline specified is not a member of TextBaseline.
 
ArgumentError — The kerning specified is not a member of Kerning.
 
ArgumentError — The breakOpportunity specified is not a member of BreakOpportunity.
 
ArgumentError — The digitCase specified is not a member of DigitCase.
 
ArgumentError — The digitWidth specified is not a member of DigitWidth.
 
ArgumentError — The ligatureLevel specified is not a member of LigatureLevel.
 
ArgumentError — The typographicCase specified is not a member of TypographicCase.
Method Detail

clone

()method
public function clone():ElementFormat

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

Constructs an unlocked, cloned copy of the ElementFormat.

Returns
ElementFormat — An unlocked copy of the ElementFormat object.

Example  ( How to use this example )

This example creates an ElementFormat object and sets a FontSize. A new TextElement is created, using the ElementFormat (and therefore locking it), and the TextElement is used as content for a TextBlock. A line of text is created from the TextBlock.

To modify the ElementFormat object, first check its locked property. If true, use the clone() method to create an unlocked copy of the ElementFormat, change its properties, then re-link the new ElementFormat to the TextBlock. When the lines are re-broken, the new lines will have the new font settings.


package {

    import flash.display.Sprite;
    import flash.text.engine.*;

    
    public class ElementFormat_cloneExample extends Sprite {
        private var ef1:ElementFormat;
        private var ef2:ElementFormat;
        
        public function ElementFormat_cloneExample():void {
            var fd:FontDescription = new FontDescription();
            fd.fontLookup = flash.text.engine.FontLookup.DEVICE;
            fd.fontName = "Palatino";

            var ef1:ElementFormat = new ElementFormat(fd);
            ef1.fontSize=20;
            
            var str:String = "This is flash text 0123456789";
            var tb:TextBlock = new TextBlock();
            var te1:TextElement = new TextElement(str, ef1);
            tb.content = te1;
            var line1:TextLine = tb.createTextLine(null, 600);
            addChild(line1);
            
            ef2 = (ef1.locked) ? ef1.clone() : ef1;    
            ef2.fontSize = 32;

            tb.content.elementFormat=ef2;
            var line2:TextLine = tb.createTextLine(null, 600);
            addChild(line2);
            
        }
    }    
}

getFontMetrics

()method 
public function getFontMetrics():FontMetrics

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

Returns a FontMetrics object with properties which describe the emBox, strikethrough position, strikethrough thickness, underline position, and underline thickness for the font specified by fontDescription and fontSize.

Returns
FontMetrics — A FontMetrics object describing properties of the font specified by fontDescription.

See also


Example  ( How to use this example )

This example creates an ElementFormat object with an assigned FontDescription and uses the getFontMetrics method to display metrics for the chosen font at 24 points.

package {

    import flash.display.Sprite;
    import flash.text.engine.*;

    
    public class FontMetricsExample extends Sprite {
        
        public function FontMetricsExample():void {
            var fd:FontDescription = new FontDescription();
            fd.fontName = "Garamond";
            fd.fontWeight = flash.text.engine.FontWeight.BOLD;

            var ef1:ElementFormat = new ElementFormat(fd);
            ef1.fontSize = 24;            
            var fm1:FontMetrics = ef1.getFontMetrics();

            trace(fm1.emBox);
            trace(fm1.strikethroughOffset);
            trace(fm1.strikethroughThickness);
            trace(fm1.subscriptScale);
            trace(fm1.subscriptOffset);
            trace(fm1.superscriptScale);
            trace(fm1.superscriptOffset);
            trace(fm1.underlineOffset);
            trace(fm1.underlineThickness);
            
            
        }
    }    
}
ElementFormatExample.as

This example creates two ElementFormat objects and sets several of their properties. It then assigns the new ElementFormats to a TextElement object, which has been assigned as the content of a TextBlock. Note that changing the ElementFormat of a TextElement does not affect TextLines that have been previously created by the parent TextBlock.


package {

    import flash.display.Sprite;
    import flash.text.engine.*;

    
    public class ElementFormatExample extends Sprite {
        
        public function ElementFormatExample():void {
            var fd:FontDescription = new FontDescription();
            fd.fontName = "Garamond";
            fd.fontWeight = flash.text.engine.FontWeight.BOLD;

            var ef1:ElementFormat = new ElementFormat(fd);
            ef1.fontSize = 30;
            ef1.color = 0xFF0000;
            ef1.alpha = 100;
            ef1.kerning = flash.text.engine.Kerning.ON;
            ef1.trackingRight = 2;
            ef1.typographicCase = flash.text.engine.TypographicCase.UPPERCASE;
            ef1.alignmentBaseline = flash.text.engine.TextBaseline.DESCENT;
            ef1.ligatureLevel = flash.text.engine.LigatureLevel.EXOTIC;
            
            var ef2:ElementFormat = new ElementFormat(fd);
            ef2.fontSize = 30;
            ef2.color = 0xFF0000;
            ef2.alpha = 0.3;
            ef2.kerning = flash.text.engine.Kerning.OFF;
            ef2.typographicCase = flash.text.engine.TypographicCase.LOWERCASE;
            ef2.digitCase = flash.text.engine.DigitCase.OLD_STYLE;
            ef2.textRotation = flash.text.engine.TextRotation.ROTATE_180;
            
            var str:String = "This is flash text 0123456789";
            var tb:TextBlock = new TextBlock();
            var te1:TextElement = new TextElement(str, ef1);
            tb.content = te1;
            var line1:TextLine = tb.createTextLine(null, 600);
            addChild(line1);
            line1.x = 15;
            line1.y = 30;

            tb.content.elementFormat = ef2;
            var line2:TextLine = tb.createTextLine(null, 600);
            addChild(line2);
            line2.x = 15;
            line2.y = 60;
            
        }
    }    
}