app.project.item(index).layer(index).text.sourceText.value.characterRange(characterIndexStart, [signedCharacterIndexEnd])Note
This functionality was added in After Effects 24.3
Description
The CharacterRange object is an accessor to a character range of the :ref:`TextDocument` instance it was created from.
Unlike the :ref:`TextDocument`, 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 :ref:`characterStart<CharacterRange.characterStart>` attribute is the first character index of the range.
- The :ref:`characterEnd<CharacterRange.characterEnd>` attribute will report the (last + 1) character index of the range, such that (:ref:`characterEnd<CharacterRange.characterEnd>` - :ref:`characterStart<CharacterRange.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 :ref:`characterStart<CharacterRange.characterStart>` and effective :ref:`characterEnd<CharacterRange.characterEnd>` of the range remains valid for the current span of the related :ref:`TextDocument`. This is the same rule as applied when the CharacterRange was created, but because the length of the related :ref:`TextDocument` can change through the addition or removal of characters, the :ref:`characterStart<CharacterRange.characterStart>` and effective :ref:`characterEnd<CharacterRange.characterEnd>` may no longer be valid. In this situation an exception will be thrown on access, either read or write. The :ref:`isRangeValid<CharacterRange.isRangeValid>` attribute will return false if the effective range is no longer valid.
Note that if the :ref:`TextDocument` length changes, the :ref:`CharacterRange` range could become valid again.
Differences from TextDocument
Because CharacterRange is an accessor of :ref:`TextDocument`, 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;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 :ref:`TextDocument`.
Type
Unsigned integer; read-only.
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 :ref:`TextDocument`.
Type
Unsigned integer; read-only.
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
Description
Returns true if the current range is within the bounds of the related :ref:`TextDocument`, false otherwise.
Type
Boolean; read-only.
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 :ref:`autoKernType<TextDocument.autoKernType>` in the range is set to
AutoKernType.METRIC_KERN,AutoKernType.OPTICAL_KERN, or is mixed, then this attribute will be returned asundefined. - If :ref:`autoKernType<TextDocument.autoKernType>` in the range is set to
AutoKernType.NO_AUTO_KERN, and this attribute has a mixed value, it will be read asundefined.
Setting this value will also set AutoKernType.NO_AUTO_KERN to true across the affected characters.
Type
Integer value; read/write.
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 :ref:`applyStroke<TextDocument.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 :ref:`applyStroke<TextDocument.applyStroke>` is not true.
Type
Array [r, g, b] of floating-point values; read/write.
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
Type
Boolean; read/write.
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 :ref:`TextDocument.characterRange` with the same value for start as end to get an insertion point range.
Type
String; read/write.
CharacterRange.pasteFrom(characterRange)
Note
This functionality was added in After Effects (Beta) 25.0 and is subject to change while it remains in Beta.
Description
Copies, using paste semantics, from the characterRange parameter to the callee :ref:`CharacterRange`. The two instances may be the same, and the spans may be different.
Checks will be made that both :ref:`CharacterRange` instances are valid.
The internal steps of the operation are:
- Delete the text from the target instance.
- Paste the text from the source instance.
As the span of the :ref:`CharacterRange` is not adjusted by this call, when the source :ref:`CharacterRange` instance has a shorter span than the target :ref:`CharacterRange` instance, the target instance may become invalid.
Parameters
characterRange |
A :ref:`CharacterRange` whose text and styling will be pasted in place of the callee :ref:`CharacterRange`. |
Returns
None.
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; read-only.