comet.CTextModel

class comet.CTextModel

CTextModel is used for accessing and modifying the document text.

Text model addressing

Usually, the active text model of a script is automatically defined and available to the script - it is therefore not necessary to address the current text selection or its frame. The necessary calculations are performed by the script environment itself.

The text indices used in the scripts always refer to the currently active area of a script, such as a placeholder, and not to the entire text frame. The index 0 therefore does not refer to the first character of the current text frame but to the first character of the placeholder.

When it becomes necessary to access the global text model of a frame, use CFrame.getTextModel() to obtain the entire frame model.

Placeholder

In text placeholders the text model is automatically determined by the text. The text indices are determined by the beginning and end of the placeholder.

If the placeholder is linked to a graphic frame, no text model is available.

Panel actions

For panel actions the current text model is defined if the text tool is active or if the respective frame for which the script is executed is a text frame.

If the panel action is executed for a graphics frame, no text model is available.

XML elements

Scripts can be specified as the value of XML attributes of a document. In this case, the XML tag whose attribute value is the script may include a text or graphics frame that displays the contents of the XML tag. When the script is executed, the associated XML element is automatically passed to the script. This element can be used to determine the associated text model during script execution and is available to subsequent functions.

If an XML element is not linked to a frame but to a piece of text, the index positions automatically refer to this text selection. Position 0 is thus the text start for the XML element, not that of the text.

Methods

CTextModel.replace(text, start=0, length=- 1, autoLoad=True, flags=0)

Replace the text content of this text model.

Inserting formatted text like TaggedText or HTML is also possible.

Parameters

  • text (str) – The text to insert.

  • start (int) – Insert position in the text.

  • length (int) –

    Number of characters replace.

    Default is comet.kEnd == until the end.

  • autoLoad (bool) –

    When inserting TaggedText, should placeholders be loaded?

    Ignored

  • flags (int) –

    Instructions for preparing TaggedText.

    • 0 : Off

    • 2 : Fix parastyles of all cells

    • 4 : Fix parastyles of complete text

    • 8 : Check tables

    • 16 : Replace <in> tags by <w2inline> tags

    • 32 : Repair hyperlinks

    Please note:
    For normal text, the parameter has no meaning.

    As of v4.1.6 R25777 the w2inline replacement always is done automatically. Since w2inline is a character attribute and can only be evaluated if a paragraph style is defined, the paragraphs will also be corrected in all non-empty table cells. Changes to your TaggedText are not required for this.

    If the option Plug-Ins -> Comet -> Read PlaceHolders from TaggedText is disabled, the flags 2, 4 and 16 do not have any meaning and are ignored.

    Flags 2 and 4 have no meaning, missing or empty paragraph styles are always calculated and used here.

    Ignored

Return type

None

Raises
Available

CScript

textmodel::replace

CTextModel.getFrame(index=0)

Determine the text frame at a specified text position. If the text position is in overset, the last frame of the frame chain is returned.

Parameters

index (int) – The text index to search the frame for. In text placeholders the index is relative to the placeholder.

Returns

The frame the index is in

Return type

CFrame

Available

CScript

textmodel::get_frame

CTextModel.getStart()

Get the global start index of this text model. When the owner of this text model is a frame (placeholder), the result is always 0. For text placeholders the result is the text index where the placeholder starts

Returns

The global start index

Return type

int

Available

CScript

textmodel::start

CTextModel.getLength()

Get the global length of this text model. When the owner of this text model is a frame (placeholder), the result is always the entire text length. For text placeholders the result is the end index - start index.

Returns

The length of this model

Return type

int

Available

CScript

textmodel::length

CTextModel.getText(index=0, length=- 1, format=0)

Get the text content of this text model.

Parameters
Returns

The text

Return type

str

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter length is out of bounds

    • When parameter format has invalid value

  • CometError – On internal error

Available

CScript

textmodel::gettext

CTextModel.getFontSize(index)

Get the font size at the designated text index.

Parameters

index (int) – The index to get the font size at

Returns

Tuple containing:

  • int : Start index

  • int : Length

  • float : Font size in pt

Return type

tuple[int, int, float]

Raises
Available

CScript

textmodel::get_fontsize

CTextModel.setFontSize(index, length, size)

Set the font size at the designated text index and length.

Parameters

  • index (int) – The index to start setting the size for

  • length (int) – The length to apply to.

  • size (float) – The font size to set in pt

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter size has invalid value

    • When parameter length is out of bounds

    • When parameter index is out of bounds

  • CometError – On internal error

Available

CScript

textmodel::set_fontsize

CTextModel.getFont(index)

Get the font family and font face at the designated text index.

Parameters

index (int) – The index to get the font at

Returns

tuple[font family, font face, length]

Return type

tuple[str, str, int]

Raises
Available

CScript

textmodel::get_font

CTextModel.setFont(index, length, family, face)

Set the font family and font face at the designated text index and length.

Parameters

  • index (int) – The index to start setting the size for

  • length (int) – The length to apply to.

  • family (str) – The font family to set

  • face (str) – The font face to set

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter family is empty

    • When parameter face is empty

  • CometError – On internal error

Available

CScript

textmodel::set_font

CTextModel.getTracking(index)

Get the tracking value at the designated text index.

Parameters

index (int) – The index to get the tracking value at

Returns

Tuple containing:

  • int : Start index

  • int : Length

  • int : Tracking value

Return type

tuple[int, int, int]

Raises
Available

CTextModel.setTracking(index, length, value)

Set the tracking value text index and length.

Parameters

  • index (int) – The index to start setting the size for

  • length (int) – The length to apply to.

  • value (int) – The tracking value to set

Return type

None

Raises
Available

CTextModel.getLeading(index)

Get the leading value at the designated text index.

Parameters

index (int) – The index to get the leading value at

Returns

Tuple containing:

  • int : Start index

  • int : Length

  • int : Leading value in pt

Return type

tuple[int, int, float]

Raises
Available

CTextModel.setLeading(index, length, value)

Set the tracking value text index and length.

Parameters

  • index (int) – The index to start setting the size for

  • length (int) – The length to apply to

  • value (float | bool) –

    The leading value to set.

    The parameter type can be:

    • float

      The leading value in pt.

      This disables automatic leading.

    • bool

      True: Enable automatic leading.

      False: Disable automatic leading.

Return type

None

Raises
Available

CTextModel.getListType(index)

Get the paragraph list type at the designated text index.

Parameters

index (int) – The index to get the list type for

Returns

The list type at the designated index. One of List types

Return type

int

Raises
Available

CScript

textmodel::get_para_listtype

CTextModel.getColor(index, what=0)

Get the text color at the designated text index.

Parameters

  • index (int) – The index to get the text color for

  • what (int) –

    Which color attribute to get

    • 0 : Text

    • 1 : Stroke

    • 2 : Underline

    • 3 : Underline gap

    • 4 : Strike through

    • 5 : Strike through gap

Returns

The color information.

Tuple containing:

  • int : Start index

  • int : Length

  • CColor : Color

  • float : Tint in range[0.0, 100.0]

  • CSwatch | None : Swatch object when this color is set by a swatch, else None

  • bool : Is process color?

Return type

tuple[int, int, CColor, float, CSwatch | None, bool]

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameter what has invalid value

Available

CTextModel.setColor(index, length, color, tint=100.0)

Set the text color as an override.

Parameters

  • index (int) – The start index

  • length (int) – The length to apply to.

  • color –

    The text color to set.

    The parameter type can be:

  • tint (float) –

    The tint to apply in range[0.0, 100.0]

    Ignored

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter tint is out of bounds

    • When color values are out of bounds

  • CometError – On internal error

Available

CScript

textmodel::set_color

CTextModel.getHorizontalJustification(index)

Get the horizontal justification setting at the designated text index.

This is a paragraph level setting.

Parameters

index (int) – The index to get the justification setting for.

Returns

Tuple containing:

Return type

tuple[int, int, str]

Raises
Available

CTextModel.setHorizontalJustification(index, length, value)

Set the horizontal justification setting at the designated text index.

This is a paragraph level setting.

Parameters

  • index (int) – The index to start setting the justification for.

  • length (int) – The length to apply to.

  • value (int) –

    The setting to apply.

    One of Horizontal Justification

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter value has invalid value

  • CometError – On internal error

Available

CTextModel.getParaStyle(index, fullPath=False)

Get the paragraph style at the designated text index.

Parameters

  • index (int) – The index to get the paragraph style for.

  • fullPath (bool) – Get the full path of the style (True) or only the actual name (False).

Returns

Tuple containing:

  • int : Start index

  • int : Length

  • str : Style name

Return type

tuple[int, int, str]

Raises
Available

CScript

textmodel::get_parastyle

CTextModel.setParaStyle(index, length, style)

Set the paragraph style at the designated text index and for all paragraphs containted between index and length.

Parameters

  • index (int) – The start index

  • length (int) – The length to apply to

  • style (str) – The full style name

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter style is empty

  • CometError – On internal error

Available

CScript

textmodel::set_parastyle

CTextModel.getCharStyle(index, fullPath=False)

Get the character style at the designated text index.

Parameters

  • index (int) – The index to get the character style for

  • fullPath (bool) – Get the full path of the style (True) or only the actual name (False)

Returns

Tuple containing:

  • int : Start index

  • int : Length

  • str : Style name

Return type

tuple[int, int, str]

Raises
Available

CScript

textmodel::get_charstyle

CTextModel.setCharStyle(index, length, style)

Set the character style at the designated text index and length.

Parameters

  • index (int) – The start index

  • length (int) – The length to apply to

  • style (str) – The full style name

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When paramter length is out of bounds

    • When parameter style is empty

  • CometError – On internal error

Available

CScript

textmodel::set_charstyle

CTextModel.getInlines(index, length)

Get the inline and anchored frames of a text area.

If you also want the inlines in table cells, you have to use comet.kTotalEnd for the length here.

Parameters

  • index (int) – The index to start searching at

  • length (int) – The length so search for

Returns

The found inline frames

Return type

list[CFrame]

Raises
Available

CScript

itemlist::inlines

CTextModel.insertCrossRef(index, name, classID=0, recordID=None, borderOptions=None, length=0)

Insert a cross reference destination into a text.

This destination must not overlap different Comet placeholders.

A cross reference destination will insert one (invisible, but existing) character into the text.

A detailed description about Comet cross references can be found here

Parameters

  • index (int) – Position of the cross reference destination.

  • name (str) –

    Name of the reference.

    Empty str: Use the default name

  • classID (int) – Class ID of the object

  • recordID (None | CIDType | tuple[int, int, int, str]) –

    Comet object ID.

    The parameter type can be:

  • borderOptions (None | dict[str, bool | int | CColor]) –

    Dictionary containg options for how the crossref border is displayed.

    Depending on the keys, the following values are expected per key:

    ’kBorderVisible’

    • Type: bool

    • Value: Whether the border is visible in the document

    • Default: False

    ’kBorderWidth’

    • Type: int

    • Value: Width of the border in range[1, 3]

      • 1: Thin

      • 2: Middle

      • 3: Bold

    • Default: 1

    ’kBorderHilight’

    • Type: int

    • Value: Frame type in range[1, 3]

      • 1: Draw reference inverted (Not supported in InDesign®, but visible in PDF export.)

      • 2: Inset

      • 3: Outline

    • Default: 3

    ’kBorderStyle’

    • Type: int

    • Value: Frame border style in range[0, 1]. InDesign® only supports the following two values:

      • 0: Continuous

      • 1: Dashed

    • Default: 1

    ’kBorderColor’

  • length (int) –

    Length of the reference.

    It is strongly advised to choose 0 as the length of the reference!

    The length of the reference is the number of document characters occupied by the reference.

    The actual length is greater by one, because the reference itself also occupies a text character.

    The value 0 thus creates a reference of the length 1, which does not enclose any further characters.

Return type

None

Raises
Available

CScript