Text document

TextDocument ¶

Stores a value for a TextLayer's Source Text property.

Example

from py_aep import parse

app = parse("project.aep")
comp = app.project.compositions[0]
text_doc = comp.text_layers[0].text.source_text.value
print(text_doc.text)

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

Attributes¶

all_caps ¶

all_caps: bool | None

True if a Text layer has All Caps enabled. Read-only.

apply_fill ¶

apply_fill = bool('_char_style', '56', default=None)

When True, the Text layer shows a fill. Read / Write.

apply_stroke ¶

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

When True, the Text layer shows a stroke. Read / Write.

auto_hyphenate ¶

auto_hyphenate = bool('_para_style', '9', default=None)

The Text layer's auto hyphenate option. Read / Write.

auto_kern_type ¶

auto_kern_type: AutoKernType | None

The Text layer's auto kern type option. Read / Write.

Setting a non-manual kern type also clears the manual kerning values document-wide, dropping the kern-run array and the leading-edge value like the range setter (probed X_AKT_SET).

auto_leading ¶

auto_leading: bool | None

The Text layer's auto leading option. Read / Write.

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

baseline_direction ¶

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

The Text layer's baseline direction. Read / Write.

baseline_shift ¶

baseline_shift = float('_char_style', '9', default=None)

This Text layer's baseline shift in pixels. Read / Write.

box_auto_fit_policy ¶

box_auto_fit_policy: BoxAutoFitPolicy

The box's auto-fit policy. Read / Write.

box_first_baseline_alignment ¶

box_first_baseline_alignment: BoxFirstBaselineAlignment

The box's first-baseline alignment. Read / Write.

box_first_baseline_alignment_minimum ¶

box_first_baseline_alignment_minimum: float

The minimum for MINIMUM_VALUE_* first-baseline alignment. R/W.

box_inset_spacing ¶

box_inset_spacing: float

The box's inset (padding) spacing in pixels. Read / Write.

box_overflow ¶

box_overflow: bool | None

True if the text overflows the box. Read-only.

A composition covers fewer characters than the stored text exactly when the text overflows (probed via samples/models/text/box_overflow.aep). Reads the persisted AE cache while the document is untouched and the calibrated composer after layout-affecting py-side writes (see composition_stale). None for point text (ExtendScript reads undefined there) and for documents without a cache.

box_text ¶

box_text: bool

True if this is a box (paragraph) text layer. Read-only.

Box text stores the bounding-box vertex array in the frame; point text omits it.

box_text_pos ¶

box_text_pos: list[float] | None

The top-left position of the text box as [x, y]. Read / Write.

None for point text. Setting moves the box while keeping its size; requires box (paragraph) text.

box_text_size ¶

box_text_size: list[float] | None

The size of the text box as [width, height]. Read / Write.

None for point text. Setting dimensions on point text converts it into a box (paragraph) text layer; on box text it resizes the box while keeping its top-left corner fixed.

box_vertical_alignment ¶

box_vertical_alignment: BoxVerticalAlignment

The box's vertical text alignment. Read / Write.

composed_line_count ¶

composed_line_count: int | None

The number of composed lines in the Text layer. Read-only.

Point text derives its lines from the paragraphs (always fresh). Box text reads the layout cache AE persisted at save time; after a layout-affecting py-side write the calibrated composed-line resolver recomposes it, otherwise the cached count stays (matching ExtendScript's un-reapplied values - see composition_stale). None for documents never parsed from a layer.

composed_line_ranges ¶

composed_line_ranges: list[dict[str, int]]

Character bounds of every composed line as {"start", "end"} records. Read-only.

Matches [composed_line_range][TextDocument.composed_line_range] bounds (ends clamped to the visible text, stale cached lines beyond it dropped) from one span derivation; empty for documents never parsed from a layer or without a layout cache. Like the other composed-line APIs, recomposes freshly when the calibrated composer covers the document, otherwise reflects the composition AE last persisted.

composer_engine ¶

composer_engine: ComposerEngine | None

The Text layer's composer engine type. Read-only.

composition_stale ¶

composition_stale: bool

True when the composed-line APIs may not reflect this document's current content. Read-only.

Point text is never stale (its composed lines are the paragraphs). Box text goes stale after a layout-affecting py-side write unless the composed-line resolver calibrated against this document's own persisted cache and can recompose its current state (see the resolvers.text_composition module).

The flag tracks writes made through THIS document object: a document re-parsed from a py-written file, or minted by Layer.duplicate, starts clean even when its persisted cache no longer matches its text.

digit_set ¶

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

The Text layer's digit set option. Read / Write.

direction ¶

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

The Text layer's paragraph direction. Read / Write.

end_indent ¶

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

The Text layer's paragraph end indent. Read / Write.

every_line_composer ¶

every_line_composer = bool(
    "_para_style", "29", default=False
)

The Text layer's Every-Line Composer option. Read / Write.

True when Every-Line Composer is used, False for Single-Line.

faux_bold ¶

faux_bold = bool('_char_style', '2', default=None)

True if a Text layer has faux bold enabled. Read / Write.

faux_italic ¶

faux_italic = bool('_char_style', '3', default=None)

True if a Text layer has faux italic enabled. Read / Write.

fill_color ¶

fill_color: list[float] | None

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

first_line_indent ¶

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

The Text layer's paragraph first line indent. Read / Write.

font ¶

font: str | None

The Text layer's font PostScript name. Read / Write.

font_baseline_option ¶

font_baseline_option = enum(
    FontBaselineOption, "_char_style", "13", default=None
)

The Text layer's font baseline option. Read / Write.

font_caps_option ¶

font_caps_option = enum(
    FontCapsOption, "_char_style", "12", default=None
)

The Text layer's font caps option. Read / Write.

font_object ¶

font_object: FontObject | None

The Text layer's [FontObject][]. Read-only.

font_size ¶

font_size = float(
    "_char_style",
    "1",
    default=None,
    validate=validate_positive_nonzero_number,
)

The Text layer's font size in pixels. Read / Write.

hanging_roman ¶

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

The Text layer's Roman Hanging Punctuation. Read / Write.

horizontal_scale ¶

horizontal_scale = float('_char_style', '6', default=None)

This Text layer's horizontal scale in pixels. Read / Write.

justification ¶

justification = enum(
    ParagraphJustification, "_para_style", "0", default=None
)

The paragraph justification for the Text layer. Read / Write.

kerning ¶

kerning: int

The Text layer's kerning value. Read-only.

Reads the leading-edge manual kern value AE stores at doc["0"]["7"] - written only when a kerning set includes pair position 0 (probed W_KERN_START). Documents without one read 0, which is also what ExtendScript exports for every probed document-level read; per-character values live in the kerning runs via character_range(...).kerning.

leading ¶

leading: float | None

The Text layer's spacing between lines. Read / Write.

When auto-leading is enabled, returns font_size * auto_leading_factor.

leading_type ¶

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

The Text layer's paragraph leading type. Read / Write.

ligature ¶

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

When True, ligature is used. Read / Write.

line_join_type ¶

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

The Text layer's line join type for strokes. Read / Write.

line_orientation ¶

line_orientation: LineOrientation

The Text layer's line orientation. Read / Write.

no_break ¶

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

When True, the no-break attribute is applied. Read / Write.

paragraph_count ¶

paragraph_count: int | None

The number of paragraphs in the text layer. Read-only.

paragraph_ranges ¶

paragraph_ranges: list[dict[str, int]]

Character bounds of every paragraph as {"start", "end"} records. Read-only.

Matches [paragraph_range][TextDocument.paragraph_range] bounds (paragraph spans clamped to the visible text) from one pass over the paragraph runs; empty for documents never parsed from a layer. Ground-truth validation compares this against ExtendScript's per-paragraph dump.

point_text ¶

point_text: bool

True if this is a point text layer. Read-only.

small_caps ¶

small_caps: bool | None

True if a Text layer has Small Caps enabled. Read-only.

space_after ¶

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

The Text layer's paragraph space after. Read / Write.

space_before ¶

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

The Text layer's paragraph space before. Read / Write.

start_indent ¶

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

The Text layer's paragraph start indent. Read / Write.

stroke_color ¶

stroke_color: list[float] | None

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

stroke_over_fill ¶

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

When True, the stroke appears over the fill. Read / Write.

stroke_width ¶

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

The Text layer's stroke thickness in pixels. Read / Write.

subscript ¶

subscript: bool | None

True if a Text layer has subscript enabled. Read-only.

superscript ¶

superscript: bool | None

True if a Text layer has superscript enabled. Read-only.

text ¶

text: str

The text value for the Source Text property. Read / Write.

tracking ¶

tracking = int('_char_style', '8', default=None)

The Text layer's spacing between characters. Read / Write.

tsume ¶

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

This Text layer's tsume value (0.0 to 1.0). Read / Write.

vertical_scale ¶

vertical_scale = float('_char_style', '7', default=None)

This Text layer's vertical scale in pixels. Read / Write.

Functions¶

character_range ¶

character_range(
    character_start: int,
    signed_character_end: int | None = None,
) -> CharacterRange

A [CharacterRange][] over part of this document.

Parameters:

character_start (int) –

First character index (UTF-16 units, 0 <= character_start <= text length).
signed_character_end (int | None, default: None ) –

Index past the last character. -1 resolves dynamically to the text length; when omitted, defaults to character_start + 1.

Raises:

ValueError –

When the indices are outside the document bounds (AE raises at creation time).

composed_line_character_indexes_at ¶

composed_line_character_indexes_at(
    character_index: int,
) -> dict[str, int]

The character bounds of the composed line containing an index.

Parameters:

character_index (int) –

A character index (UTF-16 units) within the text.

Returns:

dict[str, int] –

{"start": int, "end": int} for the containing composed line.

Raises:

ValueError –

When character_index is outside the text or the document has no composed-line cache.

composed_line_range ¶

composed_line_range(
    composed_line_index_start: int,
    signed_composed_line_index_end: int | None = None,
) -> ComposedLineRange

A [ComposedLineRange][] over part of this document.

Composed lines come from the layout cache AE persisted at save time, or from the calibrated composed-line resolver after py-side edits; see [ComposedLineRange][] for the semantics.

Parameters:

composed_line_index_start (int) –

First composed-line index (0 <= composed_line_index_start < composed line count).
signed_composed_line_index_end (int | None, default: None ) –

Index past the last line. -1 resolves dynamically to the line count; when omitted, defaults to composed_line_index_start + 1.

Raises:

ValueError –

When the indices are outside the cached composed lines (AE raises at creation time).

paragraph_character_indexes_at ¶

paragraph_character_indexes_at(
    character_index: int,
) -> dict[str, int]

The character bounds of the paragraph containing an index.

Parameters:

character_index (int) –

A character index (UTF-16 units) within the text.

Returns:

dict[str, int] –

{"start": int, "end": int} for the containing paragraph.

Raises:

ValueError –

When character_index is outside the text.

paragraph_range ¶

paragraph_range(
    paragraph_index_start: int,
    signed_paragraph_index_end: int | None = None,
) -> ParagraphRange

A [ParagraphRange][] over part of this document.

Parameters:

paragraph_index_start (int) –

First paragraph index (0 <= paragraph_index_start < paragraph count).
signed_paragraph_index_end (int | None, default: None ) –

Index past the last paragraph. -1 resolves dynamically to the paragraph count; when omitted, defaults to paragraph_index_start + 1.

Raises:

ValueError –

When the indices are outside the document bounds (AE raises at creation time).