comet.CTable¶
- class comet.CTable¶
This section describes all functions for the comet.CTable class.
See also
- Module
comet.table
General table related functions
Methods¶
- CTable.getFrame()¶
Returns the frame this table is contained in
Returns the table group
- Returns
The table frame
- Return type
- Raises
CometError – On internal error
- Available
- CTable.getUID()¶
Get the UID of this table as an int.
- Returns
The UID of this table
- Return type
- Raises
CometError – On internal error
- Available
- CTable.getTextPosition()¶
Get the text position and length of a table.
The function returns text position and length of the contents of the table.
The contents of table cells are stored by InDesign® behind the actual text as return-separated text. In the actual text there is only an anchor that refers to the cell text.
To get the position of the table anchor use
getAnchorPosition()
- Returns
The table content position and length as (position, length)
- Return type
- Raises
CometError – On internal error
- Available
- CScript
- CTable.getAnchorPosition()¶
Get the text position and length of the table anchor.
The contents of table cells are stored by InDesign® behind the actual text as return-separated text. In the actual text there is only an anchor that refers to the cell text.
To get the text position of the table content use
getTextPosition()
- Returns
The table anchor position and length as (position, length)
- Return type
- Raises
CometError – On internal error
- Available
- CScript
- CTable.getRowCount(rowType=0)¶
Returns the number of rows in the table
- Parameters
rowType (int) –
Which type or row should be counted?
One of Row types
- Returns
The number of columns
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter rowType has invalid value
CometError – On internal error
- Available
- See also
- CScript
- CTable.insertRows(index, count=1, before=False, height=0.0, clearTags=True)¶
Insert rows into the table
- Parameters
- Paral bool before
Insert before index (True) or after (False)?
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter count is <= 0
When parameter height is <= 0.0
CometError – On internal error
- Available
- See also
- CScript
- CTable.removeRows(index, count)¶
Delete rows from this table.
This function can also delete header and footer rows.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTable.getColumnCount()¶
Returns the number of columns in the table
- Returns
The number of columns
- Return type
- Raises
CometError – On internal error
- Available
- See also
- CScript
- CTable.insertColumns(index, count=1, before=False, width=0.0, clearTags=True)¶
Insert columns into the table
- Parameters
index (int) – The column index to insert columns at
count (int) – How many columns to insert
before (bool) – Insert before index (True) or after (False)?
width (float) – Column width. When the value is 0.0, a default width is determined.
clearTags (bool) –
Clear all place holders at the inserted cells?
It is strongly recommended to set this to True
Ignored
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter count is <= 0
When parameter width is <= 0.0
CometError – On internal error
- Available
- See also
- CScript
- CTable.removeColumns(index, count)¶
Delete columns from this table.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTable.getRowHeight(index, count=1)¶
Returns the height of a contiguous range of table rows.
Using comet_pdf the function returns the row height at creation time or from the last call to resizeRows.
This height may differ from the height in the resulting PDF
- Parameters
- Returns
The total height of the rows in the selected area
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter count has an invalid value
CometError – On internal error
- Available
- CScript
- CTable.setRowHeight(index, height, count=1, minHeight=- 1.0, maxHeight=- 1.0)¶
Change the height of table rows.
Besides the current row height, the maximum and minimum rows height may be changed.
InDesign® uses this specification to optimise the appearance of the table.
If the new row height lies outside the current value of minimum and maximum these limits will be changed accordingly.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter height has an invalid value
When parameter count has an invalid value
CometError – On internal error
- Available
- CScript
- CTable.getColumnWidth(index, count=1)¶
Returns the width of a contiguous range of table columns.
- Parameters
- Returns
The total width of the column in the selected area
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter count has an invalid value
CometError – On internal error
- Available
- CScript
- CTable.setColumnWidth(index, width, count=1)¶
Change the width of table columns.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter height has an invalid value
When parameter count has an invalid value
CometError – On internal error
- Available
- CScript
- CTable.fitColumn(index, canShrink=False, keepLineHeights=False, precision=0.1, maxWidth=100.0, retries=30)¶
Fit columns to have no text overset in any of its cells. If there is no text overset, you can shrink the column width to its optimum.
Warning
The function only works on tables not in the textmodels overset. Applying the function on tables in the overset will cause the function to raise a CometError.
ATTENTION: If the table contains merged cells, the resulting column withs may append from the order of the calls to fitColumn!
Caused by the slight differences between the text lengths in InDesign® and comet_pdf the resulting column widths may differ a little bit too.
- Parameters
index (int) – column index (0-based)
canShrink (bool) –
Shrinking columns allowed?
keepLineHeights (bool) –
Take care on line heights while shrinking column? (only evaluated if canShrink = True)
Cells with more than one paragraph may need a heigher row too to avoid oversets. in this case the function will raise CometError 1277 (cannotRemoveOversetErr).
Ignored
precision (float) –
Precision to fit. Notice that smaller values will increase the calculation time by factor 2 for every power of 10.
<0.001: Use the old method (v3.3 R3636) to fit the column. maxWidth and retries are ignored in this case.
Uses the default 0.1 automatically if the value is smaller than 0.001.
maxWidth (float) – Maximum width of the column. The value is only used for columns having an overset in at least one cell. Notice that values near the resulting width can speed up the function dramatically. If the maximum is reached but the cell has still an overset, the error 1278 (maxWidthTooSmallErr) is returned.
retries (int) –
Number of attempts.
Especially when using non-installed fonts, changes in column width can show surprising results. To be able to catch such unexpected results, the function has an emergency exit and raises CometError 1279 (emergencyExitErr) in this case.
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter index is out of bounds
When parameter height has an invalid value
When parameter count has an invalid value
CometError – On internal error
- Available
- CScript
- CTable.getStyle()¶
Determines the active table style.
Since styles can be sorted into folders, ‘:’ is used as a separator.
- Returns
The active table style
- Return type
- Raises
CometError – On internal error
- Available
- CScript
- CTable.setStyle(styleName, removeTableOverrides=False, removeCellStyles=False)¶
Applies a table style defined in the document by name.
When styleName is empty, the default style is applied.
- Parameters
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter styleName has invalid value
CometError – On internal error
- Available
- CScript
- CTable.mergeCells(left, top, right, bottom, copyPolicy=0, delimiterText='', autoExtend=False)¶
Merge a table area to a cell.
Warning
If the cells of entire rows and/or columns are merged, the number of rows/columns of the table will become smaller. This will change the following line/column numbers!
- Parameters
left (int) – Column (0-based)
top (int) – Row (0-based)
right (int) –
First column, which is not to be edited any further (0-based)
-1: All further columns of the table
bottom (int) –
First row, which is not to be edited any further (0-based)
-1: All further rows of the table
copyPolicy (int) –
How to deal with the ‘old’ cell content?
0: InDesign® standard behavior. Add the content of the merged cell paragraph delimited to the merged cell.
1 and 2: Content is added to the merged cell too but delimited by text given in delimiterText. Using 1 we are walking from left to right to every row. Using 2 we are walking from top to bottom through every column. If visited cells having the same content, the content is taken only once.
Values 1 and 2 are not supported for now.
delimiterText (str) –
Text between the content of the merged cells.
In case of copyPolicy == 0 this text is ignored of course.
May be TaggedText.
autoExtend (bool) –
Behavior on area errors
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameters left, top, right or bottom are out of bounds
On internal error
When autoExtend is False and the area is not mergeable
- Available
- CScript
- CTable.setStroke(fields, sides, data)¶
Set stroke attributes of either entire columns/rows or for a cell area. The operation mode depends on the value in the fields parameter. The data parameter determines which attributes and values to set.
- Parameters
fields (tuple[int, int, int] | tuple[int, int, int, int]) –
The area to set the stroke attributes for.
The behavior of this function depends on the data provided.
Depending on the parameter types and counts in this tuple, the behavior changes as follows:
Apply stroke attributes to entire columns/rows. The values are:
mode : Columns or rows - one of Line types
index : 0-Based column or row index to start applying at
- countAmount of columns or rows to change.
-1: All further rows of the table
Apply stroke attributes to a cell area. The values are:
left: Column (0-based)
top: Row (0-based)
- right: First column, which is not to be edited any further (0-based)
-1: All further columns of the table
- bottom: First row, which is not to be edited any further (0-based)
-1: All further rows of the table
sides (int) –
The sides to set the stroke attributes for.
Sum of Stroke selectors
data (dict) –
The attributes to apply.
Keys in this dictionary are of type Stroke attributes
Depending on the keys, the following values are expected per key:
Type:
float
Value: Stroke weight in pt
Type:
str
Value: Name of a defined color in the document or base color
Type:
int
, one of Stroke typesValue: The stroke type to set
Ignored
Type:
float
Value: Tint in range (0.0, 100.0)
Type:
bool
Value: Whether to overprint the stroke
Ignored
Type:
str
Value: Name of the color defined in the document or a base color for the gap in the edges
Ignored
Type:
float
Value: Tint in range (0.0, 100.0) for the gap in the edges
Ignored
comet.kStrokeAttrGapOverprint
:Type:
bool
Value: Whether to overprint the gap color
Ignored
- Return type
- Raises
TypeError – When parameter types are invalid
When fields describes an area with contradictory start and end values
When parameter data is invalid or any provided values inside are invalid
CometError – On internal error
- Available
- CScript
- CTable.getCellText(column, row, format=0)¶
Determine the text content of a cell
- Parameters
column (int) –
0-based column
-1 or > column count: Last column
row (int) –
0-based row
-1 or > row count: Last row
format (int) –
The export format.
See Text formats.
Only supported format is
comet.kExportPlain
- Returns
The cell’s text
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- See also
- CScript
- CTable.setCellText(column, row, content, position=0, length=- 1)¶
Set the text content of a cell.
- Parameters
column (int) –
0-based column
-1 or > column count: Last column
row (int) –
0-based row
-1 or > row count: Last row
content (str) –
The content to insert.
May be prefixed TaggedText
May be prefixed HTML
position (int) – Insert position inside the cell
length (int) –
How many characters to remove before inserting.
Default is
comet.kEnd
== until the end.
- Return type
- Raises
TypeError – When parameter types are invalid
- Available
- CScript
- CTable.getCellTextPosition(column, row)¶
Determine the text position and length of a table cell.
- Parameters
- Returns
The cell’s text position and length as a tuple: (position, length)
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.getCellSize(column, row, areaType=0)¶
Determine the size of a table cell.
- Parameters
- Returns
The cell size as a tuple: (width, height)
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.getCellBox(column, row, areaType=0)¶
Determine the frame of a table cell.
- Parameters
column (int) –
0-based column
-1 or > column count: Last column
row (int) –
0-based row
-1 or > row count: Last row
areaType (int) –
The reference frame of the result coordinates.
Table relative
0: The cell itself
6: The cell without its strokes
1: The cell content
Frame relative
2: The cell itself
4: The cell without its strokes
7: The cell content
Page relative
3: The cell itself
5: The cell without its strokes
8: The cell content
Please note, that comet_pdf and Illustrator do not support frame and page relative results and will return the table relative area always.
- Returns
The cell box
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter relativeTo has invalid value
CometError – On internal error
- Available
- CScript
- CTable.getCellFrame(column, row)¶
Determine the frame a cell is in.
This always returns the parent table group frame.
The function also returns meaningful results for cells in overset. In this case the last frame of the text chain is returned.
- Parameters
- Returns
The frame containing the cell
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CTable.setCellFill(left, top, right, bottom, color, tint)¶
Set the background color for table cells.
- Parameters
left (int) – Column (0-based)
top (int) – Row (0-based)
right (int) –
First column, which is not to be edited any further (0-based)
-1: All further columns of the table
bottom (int) –
First row, which is not to be edited any further (0-based)
-1: All further rows of the table
color (CColor | CSwatch | str | tuple[int, int, int] | tuple[float, float, float, float]) –
The color data to apply.
The parameter type can be:
tint (float) –
The opacity of the fill in range[0.0, 100.0].
-1.0: Leave unchanged
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter left, top, right, bottom are out of bounds
When parameter color is invalid or any provided values inside are invalid
CometError – On internal error
- Available
- CScript
- CTable.getCellInsets(column, row)¶
Determine the inset of a table cell.
- Parameters
- Returns
The cell insets as a tuple: (left, top, right, bottom)
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.setCellInsets(fields, sides, inset)¶
Set the insets of a range of cells by applying an override.
- Parameters
fields (tuple[int, int, int] | tuple[int, int, int, int]) –
The area to set the cell insets for.
Depending on the parameter types and counts in this tuple, the behavior changes as follows:
Apply cell insets to entire columns/rows. The values are:
mode : Columns or rows - one of Line types
index : 0-Based column or row index to start applying at
- countAmount of columns or rows to change.
-1: All further rows of the table
Apply cell insets to a cell area. The values are:
left: Column (0-based)
top: Row (0-based)
- right: First column, which is not to be edited any further (0-based)
-1: All further columns of the table
- bottom: First row, which is not to be edited any further (0-based)
-1: All further rows of the table
sides (int) –
Which sides to set the values for.
Sum of Sides
inset (float) – The new inset value
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter inset has negative value
When fields describes an area with contradictory start and end values
CometError – On internal error
- Available
- CScript
- CTable.getCellStyle(column, row)¶
Determine the cell style of the given cell
- Parameters
- Returns
The applied cell style
When the style if part of a hierarchy, the name is delimited by ‘:’
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.setCellStyle(left, top, right, bottom, cellStyle, removeOverrides=False, applyParaStyle=False)¶
Apply a cell style to a given cell range by applying an override.
With an empty style name you can remove current cell styles from the given cell range.
- Parameters
left (int) – Column (0-based)
top (int) – Row (0-based)
right (int) –
First column, which is not to be edited any further (0-based)
-1: All further columns of the table
bottom (int) –
First row, which is not to be edited any further (0-based)
-1: All further rows of the table
cellStyle (str) –
The style to apply.
’’ : remove the current style
If the style is part of a style hierarchy, use the complete ‘:’ delimited path here!
removeOverrides (bool) –
Remove local overrides?
Ignored
applyParaStyle (bool) –
Should the cell style apply the configured paragraph style?
Ignored
- Return type
- Raises
TypeError – When parameter types are invalid
When parameter left, top, right, bottom are out of bounds
When parameter cellStyle designates invalid style
CometError – On internal error
- Available
- CScript
- CTable.getCellType(column, row)¶
Determine whether a cell is a text cell of a graphic cell
- Parameters
- Returns
The cell type
One of Cell types
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.cellHasOverset(column, row)¶
Determine whether a cell in this table has an overset.
- Parameters
- Returns
Whether the cell is overset
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.remove()¶
Deletes this table from it’s document. All subsequent calls to this table’s functions will fail.
- Returns
None
- Raises
CometError – On internal error
- Available
- CScript