CharacterRange object¶

app.project.item(index).layer(index).text.sourceText.value.characterRange(characterIndexStart, [signedCharacterIndexEnd])

Note

This functionality was added in After Effects (Beta) 24.2 and is subject to change while it remains in Beta.

Description

The CharacterRange object is an accessor to a character range of the TextDocument object instance it was created from.

Unlike the TextDocument object, which looks at only the first character when returning character attributes, here the character range can span zero or more characters. As a consequence, two or more characters may not have the same attribute value and this mixed state will be signaled by returning undefined.

The characterStart attribute is the first character index of the range.
The characterEnd attribue will report the (last + 1) character index of the range, such that (characterEnd - characterStart) represents the number of characters in the range.

It is acceptable for most attributes for the effective range to be zero - otherwise known as an insertion point.

When accessed, the CharacterRange object will check that characterStart and effective characterEnd of the range remains valid for the current span of the related TextDocument object. This is the same rule as applied when the CharacterRange was created, but because the length of the related TextDocument object can change through the addition or removal of characters, the characterStart and effective characterEnd may no longer be valid. In this situation an exception will be thrown on access, either read or write. The isRangeValid attribute will return false if the effective range is no longer valid.

Note that if the TextDocument object length changes, the CharacterRange object range could become valid again.

Differences from TextDocument

Because CharacterRange is an accessor of TextDocument object, most methods and attributes of TextDocument are available when working with CharacterRange. The attributes and methods that are unique to CharacterRange or exhibit unique behaviors are included on this page.

The following attributes and methods are not available on instances of CharacterRange:

Attributes

Methods

baselineLocs

characterRange

boxText

paragraphCharacterIndexesAt

boxTextPos

paragraphRange

boxTextSize

lineOrientation

paragraphCount

pointText

Examples

This increases the font size of the first character in the TextDocument, and set the rest of the characters to fontSize 40.

var textDocument = app.project.item(index).layer(index).property("Source Text").value;
var characterRange = textDocument.characterRange(0,1);

characterRange.fontSize = characterRange.fontSize + 5;
textDocument.characterRange(1,-1).fontSize = 40;

Attributes¶

CharacterRange.characterEnd¶

CharacterRange.characterEnd

Description

The Text layer range calculated character end value.

Throws an exception on access if the effective value would exceed the bounds of the related TextDocument object.

Type

Unsigned integer; read-only.

CharacterRange.characterStart¶

CharacterRange.characterStart

Description

The Text layer range calculated character start value.

Throws an exception on access if the effective value would exceed the bounds of the related TextDocument object.

Type

Unsigned integer; read-only.

CharacterRange.fillColor¶

CharacterRange.fillColor

Description

The Text layer range CharacterRange attribute Fill Color, as an array of [r, g, b] floating-point values.

For example, in an 8-bpc project, a red value of 255 would be 1.0, and in a 32-bpc project, an overbright blue value can be something like 3.2.

Setting this value will also set applyFill to true across the affected characters.

If this attribute has a mixed value for the range of characters, it will be read as undefined.

Warning

In contrast to the same attribute on the TextDocument API, we will not throw an exception on read if applyFill is not true.

Type

Array [r, g, b] of floating-point values; read/write.

CharacterRange.isRangeValid¶

CharacterRange.isRangeValid

Description

Returns true if the current range is within the bounds of the related TextDocument object, false otherwise.

Type

Boolean; read-only.

CharacterRange.kerning¶

CharacterRange.kerning

Description

The Text layer range character attribute kerning option.

This effectively reports the manual kerning value, and not the calculated kerning value from auto kerning.

If autoKernType in the range is set to AutoKernType.METRIC_KERN, AutoKernType.OPTICAL_KERN, or is mixed, then this attribute will be returned as undefined.
If autoKernType in the range is set to AutoKernType.NO_AUTO_KERN, and this attribute has a mixed value, it will be read as undefined.

Setting this value will also set AutoKernType.NO_AUTO_KERN to true across the affected characters.

Type

Integer value; read/write.

CharacterRange.strokeColor¶

CharacterRange.strokeColor

Description

The Text layer CharacterRange stroke color character property, as an array of [r, g, b] floating-point values.

For example, in an 8-bpc project, a red value of 255 would be 1.0, and in a 32-bpc project, an overbright blue value can be something like 3.2.

If this attribute has a mixed value, it will be read as undefined.

Setting this value will also set applyStroke to true across the affected characters.

Warning

In contrast to the same attribute on the TextDocument API, we will not throw an exception on read if applyStroke is not true.

Type

Array [r, g, b] of floating-point values; read/write.

CharacterRange.strokeOverFill¶

CharacterRange.strokeOverFill

Description

The Text layer CharacterRange Stroke Over Fill character property.

Indicates the rendering order for the fill and stroke for characters in the range. When true, the stroke appears over the fill.

If this attribute has a mixed value, it will be read as undefined.

Warning

The Text layer can override per-character attribute setting via the All Strokes First or All Fills First setting on the CharPanel.

The value returned here represents what is applied to the characters, without regard to the possible Text layer override.

Type

Boolean; read/write.

CharacterRange.text¶

CharacterRange.text

Description

The text value for the Text layer range.

On read, the same number of characters as the span of the range will be returned. If the span is zero (an insertion point) it return an empty string.

On write, the characters in the range will be replaced with whatever string value is supplied. If an empty string, then the characters in the range will be effectively deleted.

To insert characters without deleting any existing, call TextDocument.characterRange() with the same value for start as end to get an insertion point range.

Type

String; read/write.

Methods¶

CharacterRange.toString()¶

CharacterRange.toString()

Description

Returns a string with the parameters used to create the CharacterRange instance, e.g. "CharacterRange(0,-1)".

This may be safely called on an instance where isRangeValid returns false.

Parameters

None.

Returns

String;