Character range

CharacterRange ¶

Bases: _TextRange

A contiguous character span of a [TextDocument][].

Created via TextDocument.character_range(character_start, signed_character_end). Most TextDocument styling attributes are readable on the range; when the range spans style runs with differing values the attribute reads None (ExtendScript undefined). Bounds re-resolve on every access, so a range created valid raises ValueError once the document shrinks beneath it.

Zero-span ranges (character_start == character_end) are valid and report the style at that caret position with an empty text.

See: https://ae-scripting.docsforadobe.dev/text/characterrange/

Attributes¶

all_caps ¶

all_caps: bool | None

True if the range has All Caps enabled; None when mixed. Read-only.

apply_fill ¶

apply_fill = bool('char', '56')

When True, the range shows a fill; None when mixed. Read / Write.

apply_stroke ¶

apply_stroke = bool('char', '57', default=False)

When True, the range shows a stroke; None when mixed. Read / Write.

auto_hyphenate ¶

auto_hyphenate = bool('para', '9')

The paragraphs' auto-hyphenate option; None when mixed. Read / Write.

auto_kern_type ¶

auto_kern_type: AutoKernType | None

The range's auto kern type option; None when mixed. Read / Write.

Setting a non-manual kern type clears the manual kerning values over the range; AE drops the kern-run array entirely when no values remain (probed X_AKT_SET).

auto_leading ¶

auto_leading: bool | None

The range's auto-leading option; None when mixed. Read / Write.

Enabling auto-leading also resets the explicit leading key to AE's sentinel (probed X_AL_SET).

baseline_direction ¶

baseline_direction = enum(
    BaselineDirection,
    "char",
    "35",
    default=BASELINE_WITH_STREAM,
)

The range's baseline direction; None when mixed. Read / Write.

baseline_shift ¶

baseline_shift = float('char', '9')

The range's baseline shift in pixels; None when mixed. Read / Write.

character_end ¶

character_end: int

The range's last character index + 1. Read-only.

character_start ¶

character_start: int

The range's first character index. Read-only.

composer_engine ¶

composer_engine: ComposerEngine | None

The document's composer engine (document-wide). Read-only.

digit_set ¶

digit_set = enum(
    DigitSet, "char", "70", default=DEFAULT_DIGITS
)

The range's digit set option; None when mixed. Read / Write.

direction ¶

direction = enum(
    ParagraphDirection,
    "para",
    "33",
    default=DIRECTION_LEFT_TO_RIGHT,
)

The paragraphs' direction; None when mixed. Read / Write.

end_indent ¶

end_indent = float('para', '3', default=0.0)

The paragraphs' end indent; None when mixed. Read / Write.

every_line_composer ¶

every_line_composer = bool('para', '29', default=False)

The paragraphs' Every-Line Composer option; None when mixed. Read / Write.

faux_bold ¶

faux_bold = bool('char', '2')

True if faux bold is enabled across the range. Read / Write.

faux_italic ¶

faux_italic = bool('char', '3')

True if faux italic is enabled across the range. Read / Write.

fill_color ¶

fill_color = cast(
    "RangeField[list[float]]",
    RangeField(
        "char",
        "53",
        transform=_parse_color,
        gate="56",
        reverse=_build_color_paint,
        validate=validate_rgb_color,
    ),
)

The range's fill color as [r, g, b]. Read / Write.

Only characters with apply_fill participate in the read; None when no character in the range has a fill or the colors are mixed. Setting writes the paint only - like the stroke, it does not enable apply_fill.

first_line_indent ¶

first_line_indent = float('para', '1', default=0.0)

The paragraphs' first line indent; None when mixed. Read / Write.

font ¶

font: str | None

The range's font PostScript name; None when mixed. Read / Write.

Setting a font absent from the document's font array prepends it and reindexes existing references, matching AE.

font_baseline_option ¶

font_baseline_option = enum(
    FontBaselineOption, "char", "13"
)

The range's font baseline option; None when mixed. Read / Write.

font_caps_option ¶

font_caps_option = enum(FontCapsOption, 'char', '12')

The range's font caps option; None when mixed. Read / Write.

font_object ¶

font_object: FontObject | None

The range's [FontObject][]; None when mixed. Read-only.

font_size ¶

font_size = float(
    "char", "1", validate=validate_positive_nonzero_number
)

The range's font size in pixels; None when mixed. Read / Write.

hanging_roman ¶

hanging_roman = bool('para', '21', default=False)

The paragraphs' Roman Hanging Punctuation; None when mixed. Read / Write.

horizontal_scale ¶

horizontal_scale = float('char', '6')

The range's horizontal scale; None when mixed. Read / Write.

is_range_valid ¶

is_range_valid: bool

True while the range lies within the document bounds. Read-only.

justification ¶

justification = enum(ParagraphJustification, 'para', '0')

The justification of paragraphs in the range; None when mixed. Read / Write.

kerning ¶

kerning: int | None

The range's manual kerning value. Read / Write.

AE reads undefined unless auto-kerning is uniformly disabled AND a manual value is stored for every character in the range (probed X_TEXT_KERN: spliced-in characters under NO_AUTO_KERN without values read undefined). Values live in dedicated kerning runs (doc["0"]["8"]) and read None when mixed. Setting a value affects characters [max(0, start - 1), end) - AE's pair shift - disables auto-kerning for them, and stores the leading-edge value at doc["0"]["7"] when the range starts at 0.

leading ¶

leading: float | None

The range's spacing between lines. Read / Write.

AE reads undefined while auto-leading is active (or mixed) anywhere in the range; the explicit value only surfaces when auto-leading is uniformly disabled. Setting an explicit value also disables auto-leading over the range (probed W_LEAD); setting None clears the explicit value without touching auto-leading.

leading_type ¶

leading_type = enum(
    LeadingType, "para", "8", default=ROMAN_LEADING_TYPE
)

The paragraphs' leading type; None when mixed. Read / Write.

ligature ¶

ligature = bool('char', '18', default=False)

True when ligature is used across the range. Read / Write.

line_join_type ¶

line_join_type = enum(
    LineJoinType, "char", "62", default=LINE_JOIN_MITER
)

The range's line join type for strokes; None when mixed. Read / Write.

no_break ¶

no_break = bool('char', '52', default=False)

True when no-break is applied across the range. Read / Write.

small_caps ¶

small_caps: bool | None

True if the range has Small Caps enabled; None when mixed. Read-only.

space_after ¶

space_after = float('para', '5', default=0.0)

The paragraphs' space after; None when mixed. Read / Write.

space_before ¶

space_before = float('para', '4', default=0.0)

The paragraphs' space before; None when mixed. Read / Write.

start_indent ¶

start_indent = float('para', '2', default=0.0)

The paragraphs' start indent; None when mixed. Read / Write.

stroke_color ¶

stroke_color = cast(
    "RangeField[list[float]]",
    RangeField(
        "char",
        "54",
        transform=_parse_color,
        gate="57",
        reverse=_build_color_paint,
        validate=validate_rgb_color,
    ),
)

The range's stroke color as [r, g, b]. Read / Write.

Only characters with apply_stroke participate in the read; None when no character in the range has a stroke or the colors are mixed. Setting writes the paint only - AE does NOT enable apply_stroke (probed W_STROKE_GATE; the Scripting Guide claims otherwise).

stroke_over_fill ¶

stroke_over_fill = bool('char', '58', default=True)

When True, the stroke appears over the fill; None when mixed. Read / Write.

stroke_width ¶

stroke_width = float(
    "char",
    "63",
    default=1.0,
    validate=validate_positive_nonzero_number,
)

The range's stroke thickness; None when mixed. Read / Write.

subscript ¶

subscript: bool | None

True if the range is subscript; None when mixed. Read-only.

superscript ¶

superscript: bool | None

True if the range is superscript; None when mixed. Read-only.

text ¶

text: str

The text within the range. Read / Write.

Line breaks are normalized to \n like TextDocument.text (ExtendScript returns raw \r). A range splitting a surrogate pair yields a lone surrogate, as in AE. Writing replaces the ranged characters: the replacement takes the first replaced character's style, and this range keeps its creation indices (re-resolving against the new text, exactly like AE).

tracking ¶

tracking = int('char', '8')

The range's spacing between characters; None when mixed. Read / Write.

tsume ¶

tsume = float(
    "char",
    "36",
    default=0.0,
    validate=validate_normalized_float,
)

The range's tsume value (0.0 to 1.0); None when mixed. Read / Write.

vertical_scale ¶

vertical_scale = float('char', '7')

The range's vertical scale; None when mixed. Read / Write.

Functions¶

paste_from ¶

paste_from(source_range: CharacterRange) -> None

Paste the source range's text and character styling here.

Mirrors ExtendScript's pasteFrom() (AE 25.1+, probed via the W_PASTE_* / X_PASTE_KERN fixtures): the ranged characters are replaced by the source span's text with its character style runs and manual-kern values transplanted. Cross-document pastes remap font references into this document's font array, prepending missing fonts like AE. This range keeps its creation indices and may become invalid when the pasted text is shorter.

Parameters:

source_range (CharacterRange) –

The [CharacterRange][] to copy from (may belong to another document or project).