flash.text.engine

# ElementFormat - AS3

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

More examples

Formatting text

Related API Elements

ContentElement.elementFormat

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined 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
|  | constructor : 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
|  | 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined 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
|  | clone():ElementFormat Constructs an unlocked, cloned copy of the ElementFormat. | ElementFormat
|  | getFontMetrics():FontMetrics 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
|  | 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
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | 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
|  | valueOf():Object 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 value | Description
--- | ---
`TextBaseline.ROMAN` | The `dominantBaseline` aligns with the roman baseline of the line.
`TextBaseline.ASCENT` | The `dominantBaseline` aligns with the ascent baseline of the line.
`TextBaseline.DESCENT` | The `dominantBaseline` aligns with the descent baseline of the line.
`TextBaseline.IDEOGRAPHIC_TOP` | The `dominantBaseline` aligns with the ideographic top baseline of the line.
`TextBaseline.IDEOGRAPHIC_CENTER` | The `dominantBaseline` aligns with the ideographic center baseline of the line.
`TextBaseline.IDEOGRAPHIC_BOTTOM` | The `dominantBaseline` aligns with the ideographic bottom baseline of the line.
`TextBaseline.USE_DOMINANT_BASELINE` | The `dominantBaseline` aligns with the same baseline of the line.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Sets the alignment baseline of the line to which the `dominantBaseline` of the graphic element aligns.
`GroupElement` | Has no effect.
`TextElement` | Sets 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`).

More examples

Baseline alignment and shift

Related API Elements

TextBaseline
ElementFormat.dominantBaseline

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Applies the specified alpha to the graphic element. Combines multiplicatively with any alpha set on the graphic `DisplayObject` itself or on the `TextLine`.
`GroupElement` | Has no effect.
`TextElement` | Applies 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`).

More examples

Font color and transparency (alpha)

Related API Elements

DisplayObject.alpha

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Shifts the graphic away from the baseline.
`GroupElement` | Has no effect.
`TextElement` | Shifts 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`).

More examples

Baseline alignment and shift

### 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 value | Description
--- | ---
`BreakOpportunity.AUTO` | Line breaking opportunities are based on standard Unicode character properties, such as breaking between words and on hyphens.
`BreakOpportunity.ANY` | Any 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.NONE` | No characters in the range are treated as line break opportunities.
`BreakOpportunity.ALL` | All 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.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Determines 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.
`TextElement` | Determines 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`).

More examples

Line breaks for wrapped text

Related API Elements

BreakOpportunity

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Sets 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 value | Description
--- | ---
`DigitCase.DEFAULT` | Applies default digit case to the text.
`DigitCase.LINING` | Applies lining digit case to the text.
`DigitCase.OLD_STYLE` | Applies old style digit case to the text.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

Related API Elements

DigitCase

### 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 value | Description
--- | ---
`DigitWidth.DEFAULT` | Applies default digit width to the text.
`DigitWidth.PROPORTIONAL` | Applies proportional digit width to the text.
`DigitWidth.TABULAR` | Applies tabular digit width to the text.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

Related API Elements

DigitWidth

### 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 value | Description
--- | ---
`TextBaseline.ROMAN` | The roman baseline of the element aligns with the `alignmentBaseline`.
`TextBaseline.ASCENT` | The ascent baseline of the element aligns with the `alignmentBaseline`.
`TextBaseline.DESCENT` | The descent baseline of the element aligns with the `alignmentBaseline`.
`TextBaseline.IDEOGRAPHIC_TOP` | The ideographic top baseline of the element aligns with the `alignmentBaseline`.
`TextBaseline.IDEOGRAPHIC_CENTER` | The ideographic center baseline of the element aligns with the `alignmentBaseline`.
`TextBaseline.IDEOGRAPHIC_BOTTOM` | The ideographic bottom baseline of the element aligns with the `alignmentBaseline`.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Determines which of the baselines of the graphic element aligns with the `alignmentBaseline`.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

More examples

Baseline alignment and shift

Related API Elements

TextBaseline
ElementFormat.alignmentBaseline

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

Related API Elements

FontDescription

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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 value | Description
--- | ---
`Kerning.ON` | Kerning is enabled.
`Kerning.OFF` | Kerning is disabled.
`Kerning.AUTO` | Kerning is enabled except where inappropriate in Asian typography. Kerning is applied between two characters if neither is Kanji, Hiragana, or Katakana.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Determines 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.
`TextElement` | Determines 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`).

More examples

Kerning and tracking

Related API Elements

Kerning

### 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 value | Description
--- | ---
`LigatureLevel.NONE` | No ligatures are created.
`LigatureLevel.MINIMUM` | Minimal ligatures are created.
`LigatureLevel.COMMON` | Common ligatures are created.
`LigatureLevel.UNCOMMON` | Uncommon ligatures are created.
`LigatureLevel.EXOTIC` | Exotic ligatures are created.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Determines 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.
`TextElement` | Determines 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`).

Related API Elements

LigatureLevel

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

More examples

Locking and cloning ElementFormat

### 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 value | Description
--- | ---
`TextRotation.ROTATE_0` | Glyphs are not rotated.
`TextRotation.ROTATE_90` | Glyphs are rotated 90 degrees clockwise.
`TextRotation.ROTATE_180` | Glyphs are rotated 180 degrees.
`TextRotation.ROTATE_270` | Glyphs are rotated 270 degrees clockwise.
`TextRotation.AUTO` | Specifies 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.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

More examples

Rotating text

Related API Elements

TextRotation
ContentElement.textRotation
TextBlock.lineRotation

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Determines the tracking applied to the left side of the graphic.
`GroupElement` | Has no effect.
`TextElement` | Determines the tracking applied to the left side of characters in the text element.

Example:

Copy

              //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`).

More examples

Kerning and tracking

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

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Determines the tracking applied to the right side of the graphic.
`GroupElement` | Has no effect.
`TextElement` | Determines the tracking applied to the right side of characters in the text element.

Example:

Copy

              //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`).

More examples

Kerning and tracking

### 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 value | Description
--- | ---
`TypographicCase.DEFAULT` | Specifies that normal case is used for all characters.
`TypographicCase.TITLE` | Specifies that uppercase characters use title glyphs on output.
`TypographicCase.CAPS` | Specifies that spacing is adjusted for uppercase characters on output.
`TypographicCase.SMALL_CAPS` | Specifies that uppercase characters use small caps glyphs on output.
`TypographicCase.UPPERCASE` | Specifies that all characters use uppercase glyphs on output.
`TypographicCase.LOWERCASE` | Specifies that all characters use lowercase glyphs on output.
`TypographicCase.CAPS_AND_SMALL_CAPS` | Specifies that all lowercase characters use small caps glyphs on output.

Subclass | Effect of setting property
--- | ---
`GraphicElement` | Has no effect.
`GroupElement` | Has no effect.
`TextElement` | Determines 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`).

More examples

Typographic Case

Related API Elements

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

More examples

Locking and cloning ElementFormat
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.

Copy

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

Related API Elements

FontDescription
FontMetrics
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.
Copy

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

            }
        }
    }

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

Copy

    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;

            }
        }
    }

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