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 constants.kEnd == until the end.

  • autoLoad (bool) –

    When inserting TaggedText, should placeholders be loaded?

    Illustrator® 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.

    InDesign® 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.

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

    Illustrator® Ignored

Return type:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::replace

Examples:

Replace the text of the current text model entirely.

comet.gTextModel.replace('Hello world')

Load the current placeholder from a pubserver connection and replace the text content.

#!py
import comet

#If the pubserver returns an empty string, a warning is inserted instead
def main() -> int:
    #Load the text from the pubserver
    text = placeholder.loadServer()
    if not text:
        text = 'ERROR: No data found'
    comet.gTextModel.replace(text)

    return 0
CTextModel.insertProducts(products, start=0, length=-1, flags=0, defaultTemplate=0, prefix='', postfix='', purgeSequence=False, sequenceName='')

Build products into the text. The command is the text counterpart to document::build_products. Whereas with build_products the products are built up in the document, here the products are inserted into the text flow. Either an inline frame is created from the product templates or the text content of the individual template frames is inserted. (This setting is made in the ‘Build rules’ panel for the frames before they are saved in a template).

The function is a variant of product building and can therefore not be called inside another building process like comet.product.establish().

Parameters:

  • products (list[CProduct]) – List of products to be inserted

  • start (int) –

  • length (int) –

    Number of characters to delete before inserting.

  • flags (int) –

    Control of the import. The value is specified as the sum (bit field) of the following constants, for example comet.constants.kCheckIfNotExists + comet.constants.kPreferDefaultPageItem.

  • defaultTemplate (int) – If a product does not have a defined template, this template is used. If the comet.constants.kPreferDefaultPageItem flag is also set, this template is used for all products.

  • prefix (str) –

    Insert this text before each non-empty product. The text may be unformatted, InDesign® tagged text or %!TT text. To insert a simple paragraph, you can specify <para> as an abbreviation for %!TT<ParaStyle:><nl:>.

    • ’<para>’ : New paragraph.

  • postfix (str) –

    Insert this text after each non-empty product. The text may be unformatted, InDesign® tagged text or %!TT text. To insert a simple paragraph, you can specify <para> as an abbreviation for %!TT<ParaStyle:><nl:>.

    • ’<para>’ : End of paragraph

  • purgeSequence (bool) –

    Build each product in its own sequence

    • False: Entire build in one sequence. The build can be undone with an undo. Larger imports may be interrupted by a dialog that uselessly informs you that the sequence is too large and therefore cannot be undone.

    • True: Each product is processed in its own “purged” sequence. With undo, each product is removed from the document individually.

  • sequenceName (str) – Name of a single import sequence, is only used with purgeSequence == True. The parameter value must contain exactly one ‘%d’, which is replaced by the current import counter, e.g. ‘Import %d. Product’. If the value is empty, the default string is used.

Return type:

None

Raises:

  • TypeError –

    • When parameter types are invalid

    • When parameter products is empty

  • CometError – On internal error

Available:

InDesign®

CScript:
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::get_frame

Examples:

Get the owning frame of the environment text model.

frame: comet.CFrame = comet.gTextModel.getFrame()
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::start

Examples:

Get the starting index of the environment text model.

position: int = comet.gTextModel.getStart()
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::length

Examples:

Get the length of the text this text model owns.

position: int = comet.gTextModel.getLength()
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::gettext

Examples:

Get the textmodel’s full text as InDesign TaggedText

text: str = comet.gTextModel.getText(format = comet.kExportTT)
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:

Return type:

tuple[int, int, float]

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::get_fontsize

Examples:

Get the position, length and size in pt of the environment text model at index 0.

position, length, size = comet.gTextModel.getFontSize(index = 0)
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:

InDesign® Illustrator®

CScript:

textmodel::set_fontsize

Examples:

Set the font size for the entire environment textmodel to 8.5 pt.

comet.gTextModel.setFontSize(index = 0, length = -1, size = 8.5)
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:

InDesign® Illustrator®

CScript:

textmodel::get_font

Examples:

Get the font family, face and run length of the environment text model at index 0.

fontFamily, fontFace, length = comet.gTextModel.getFont(index = 0)
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:

InDesign® Illustrator®

CScript:

textmodel::set_font

Examples:

Set the font for the entire environment textmodel to ‘Helvetica Neue’ with a font face of ‘Bold’.

comet.gTextModel.setFont(index = 0, length = -1, family = 'Helvetica Neue', face = 'Bold')
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:

Illustrator®

Examples:

Get the tracking of the environment text model at index 0.

position, length, value = comet.gTextModel.getTracking(index = 0)
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:

Illustrator®

Examples:

Set the tracking for the entire environment textmodel to 10.

comet.gTextModel.setTracking(index = 0, length = -1, value = 10)
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

  • float : Leading value in pt

Return type:

tuple[int, int, float]

Raises:
Available:

Illustrator®

Examples:

Get the leading of the environment text model at index 0.

position, length, value = comet.gTextModel.getLeading(index = 0)
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:

Illustrator®

Examples:

Set the leading for the entire environment textmodel to 10.5.

comet.gTextModel.setLeading(index = 0, length = -1, value = 10.5)
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:

InDesign®

CScript:

textmodel::get_para_listtype

Examples:

Get the list type of the environment text model at index 0.

listType: int = comet.gTextModel.getListType(index = 0)
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:

InDesign® Illustrator®

Examples:

Get the CMYK color values of the environment text model.

#Get the cmyk values for the text at position 0.
#This example assumes that the color uses the CMYK color space.
#If the color uses another color space, the function will fail on runtime.
def main() -> int:
    res: tuple[int, int, comet.CColor, float, comet.CSwatch | None, bool] = comet.gTextModel.getColor(index = 0, what = 0)
    try:
        color: comet.CColor = res[2]
        c, m, y, k = tuple(x * 100 for x in color.getValues())
    except:
        return 1

    return 0
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:

    • CColor

      Color

      InDesign® RGB and CMYK color models are supported

      Illustrator® Gray, RGB and CMYK color models are supported

    • CSwatch

      Swatch

    • tuple [int, int, int]

      RGB color. Values must in range[0 , 255]

    • tuple [float, float, float, float]

      CMYK color. Values must in range[0.0 , 1.0]

  • tint (float) –

    The tint to apply in range[0.0, 100.0]

    Illustrator® 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:

InDesign® Illustrator®

CScript:

textmodel::set_color

Examples:

Set the text color of the environment textmodel to use the swatch color of the swatch ‘Example Red’.

comet.gTextModel.setColor(index = 0, length = -1, color = comet.gDocument.getSwatch('Example Red'))
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, int]

Raises:
Available:

Illustrator®

Examples:

Get the horizontal justification of the environment text model at index 0.

position, length, value = comet.gTextModel.getHorizontalJustification(index = 0)
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:

Illustrator®

Examples:

Set the horizontal justification for the entire environment textmodel to center.

comet.gTextModel.setHorizontalJustification(index = 0, length = -1, value = comet.kJustifyCenter)
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::get_parastyle

Examples:

Get the paragraph style of the environment text model at index 0.

position, length, value = comet.gTextModel.getParaStyle(index = 0)
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::set_parastyle

Examples:

Set the paragraph style for the entire environment textmodel to ‘body’ in style group ‘main page’.

comet.gTextModel.setParaStyle(index = 0, length = -1, style = 'main page:body')

Set the paragraph style for the entire environment textmodel to ‘inline image’ which is not part of a style group.

comet.gTextModel.setParaStyle(index = 0, length = -1, style = 'inline image')
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:

InDesign® comet_pdf® Illustrator®

CScript:

textmodel::get_charstyle

Examples:

Get the character style of the environment text model at index 0.

position, length, value = comet.gTextModel.getCharStyle(index = 0)
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 parameter length is out of bounds

    • When parameter style is empty

  • CometError – On internal error

Available:

InDesign® Illustrator®

CScript:

textmodel::set_charstyle

Examples:

Set the character style for the entire environment textmodel to ‘strong’.

comet.gTextModel.setCharStyle(index = 0, length = -1, style = 'strong')
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 constants.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:

InDesign® comet_pdf®

CScript:

itemlist::inlines

Examples:

Get all inline frames of the environment text model.

inlines: list[comet.CFrame] = comet.gTextModel.getInlines(index = 0, length = -1)
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:

InDesign®

CScript:
CTextModel.copy(start=0, length=-1)

Copy a text to an internal clipboard.

The text is copied with all formatting, tables, inlines, … is copied.

The copied content can be inserted again with paste().

The clipboard data only be pasted once. It is invalid after insertion. Pasting the data again will raise an exception.

Parameters:

  • start (int) – From which text position should the text be copied?

  • length (int) –

    Length of text to be copied.

    Default is constants.kEnd == until the end.

Returns:

The copied data.

Return type:

CScrap

Raises:
Available:

InDesign®

CScript:

textmodel::copy

CTextModel.cut(start=0, length=-1)

Same as copy(), but content is cut from the source model instead of copied. Copy a text to an internal clipboard.

Available:

InDesign®

CScript:

textmodel::cut

CTextModel.paste(data, index=0)

Insert a content copied by copy() or cut() into a text.

The input CScrap object can only be used for pasting once. It is left in an invalid state after insertion. and subsequent calls to paste() will fail with an exception.

If you want to insert content several times, you must create a corresponding number of scraps.

Scraps can require a lot of memory. Use them sparingly!

Parameters:

  • data (CScrap) – The content to insert.

  • index (int) – The text index to insert the content at.

Return type:

None

Available:

InDesign®

Raises:

  • TypeError – When parameter types are invalid

  • ValueError – When parameter index is < 0

  • CometError –

    • When parameter data is invalid

    • On internal error

CScript:

textmodel::paste

CTextModel.redraw(index=-1)

Redraw the text. These calls are very expensive and should only be made when absolutely necessary.

Parameters:

index (int) –

Draw the text up to this index.

Default is constants.kEnd = until the end.

Return type:

None

Available:

InDesign®

Raises:

TypeError – When parameter types are invalid

CScript:

textmodel::force_redraw

Search for placeholders in this text model.

Parameters:

  • index (int) – The text index to begin searching at.

  • length (int) –

    The text length to search through from index.

    Default is constants.kEnd = until the end.

  • checkCoordinates (bool) –

    Whether to calculate the coordinates of the placeholder start.

    Turning this option on is very computationally intensive!

  • placeholderIDs (list[int]) –

    List of placeholderIDs to restrict collecting to.

    • Empty list: Impose no restrictions

Returns:

The found links.

Return type:

list[CLink]

Available:

InDesign® comet_pdf®

See also:

link.collect()

Raises:

TypeError – When parameter types are invalid

CScript:

linklist::text_collect

Special methods

CTextModel.__repr__()

String representation.

Returns:

InDesign® comet_pdf®

<CTextModel> Owner UID: Owner UID | Start: Start | Length: Length

Illustrator®

<CTextModel> Owner Name: Owner Name | Start: Start | Length: Length

Example
<CTextModel> Owner UID: 1031 | Start: 0 | Length: 19

Return type:

str