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
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- 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
- Available
- CScript
- 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
- Available
- CScript
- 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
- Available
- CScript
- CTextModel.getText(index=0, length=- 1, format=0)¶
Get the text content of this text model.
- Parameters
index (int) – The start index
length (int) –
The length of the text to get.
Default is
comet.kEnd
== entire lengthformat (int) –
The format to export the text in. One of Text formats
Default is
comet.kExportPlain
Parameter is ignored, value is always
comet.kExportPlain
- Returns
The text
- Return type
- Raises
TypeError – When parameter types are invalid
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
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTextModel.setFontSize(index, length, size)¶
Set the font size at the designated text index and length.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
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
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTextModel.setFont(index, length, family, face)¶
Set the font family and font face at the designated text index and length.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter family is empty
When parameter face is empty
CometError – On internal error
- Available
- CScript
- 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:
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CTextModel.setTracking(index, length, value)¶
Set the tracking value text index and length.
- 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:
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CTextModel.setLeading(index, length, value)¶
Set the tracking value text index and length.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- 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
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTextModel.getColor(index, what=0)¶
Get the text color at the designated text index.
- Parameters
- Returns
The color information.
Tuple containing:
- Return type
- 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
- Return type
- Raises
TypeError – When parameter types are invalid
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
- 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:
int
: Start indexint
: Lengthstr
:Justification setting.
One of Horizontal Justification
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- 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
- Raises
TypeError – When parameter types are invalid
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
- Returns
Tuple containing:
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTextModel.setParaStyle(index, length, style)¶
Set the paragraph style at the designated text index and for all paragraphs containted between index and length.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter style is empty
CometError – On internal error
- Available
- CScript
- CTextModel.getCharStyle(index, fullPath=False)¶
Get the character style at the designated text index.
- Parameters
- Returns
Tuple containing:
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTextModel.setCharStyle(index, length, style)¶
Set the character style at the designated text index and length.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
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
- 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
- Returns
The found inline frames
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- 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.
borderOptions (None | dict[str, bool | int | CColor]) –
Dictionary containg options for how the crossref border is displayed.
None
: Ignore
Depending on the keys, the following values are expected per key:
’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’
Type:
CColor
Value: Color for the border. Valid models are
comet.kColorModelRGB
andcomet.kColorModelCMYK
Default: Orange
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
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript