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
Frame and page relative results are not supported. Results will always be table relative.
- 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.broadenToFrame(column, columnAware=False, columns=[])¶
Fit the table to the frame width by changing the width of one/all column(s).
If the table is a sub-table of another table, the text frame is not used as the boundary.
In this case, the cell minus its cell inset is used to determine the new table width.
- Parameters
column (int) –
0-based column index whose width is to be changed.
-1 : Distribute the necessary width change relative to previous column widths over all columns.
- -2Distribute the necessary width change evenly over all columns.
If the table is shrunk, minimum widths of 3.0pt are enforced! This can lead to the case that the table never fits completely into the frame!
columnAware (bool) –
In multi-column texts, adjust to current column width?
List of 0-based column indices. If the list is not empty and the parameter column is < 0, only the columns specified in the list are modified. All other columns keep their current width.
The width change of the specified columns is done according to the value of column: Relative to the old width (-1) or uniformly (-2).
- Return type
- Raises
TypeError – When parameter types are invalid
ValueError – When parameter index is out of bounds
CometError – On internal error
- Available
- CScript
- CTable.compressColumnWise(firstColumn=0, columnSpan=1, flattenLastChunk=False, copyColumnHeader=False, fitColumns=1, delimitRowHeight=0.0)¶
Compress a wide table into the text frame. Tables can be compressed several times. If the text frame is narrower than the leading columns or narrower than the leading columns and a first column block of columnSpan columns, the table will be compressed so that it has exactly one column block - which then extends beyond the frame border. In this case, an exception of type
CometError
is raised, containing error code wrongColumnsForCompressErr (1266).If the compression results in empty rows at the end of the table, they are deleted.
The command can only be applied to tables that are not in the overset of their containing text frame.
Starting at the firstColumn column, all columns in the table are first made as narrow as possible. Then all columns that protrude beyond the text frame are appended to the bottom of the table. Thereby it is tried to fill the newly created rows with the protruding columns if possible. Only when the last column of the new rows is filled, further rows are created in the table. When transferring the columns, the header and footer lines of the table are skipped.
With the parameter columnSpan you can define how many columns should form a block. Blocks run over the same rows in any case. However, firstColumn does not have to be followed by a multiple of columnSpan, in these cases the last block of the compressed table is incomplete.
If the (last) overlapping blocks do not fill all columns of the new row(s), the entries of the columns can also be displayed on one row. To do this, set flattenLastChunk to
True
. Of course, this only works if the table does not have more body rows than columns behind firstColumn fit into the frame.Finally, you can use copyColumnHeader =
True
to cause the contents of the columns before firstColumn to be copied to the newly created table rows.After the table has been rebuilt, all columns are trimmed again. This step is necessary because cells that were copied from behind into a front column can be larger than the target column and then an overset would occur in these cells again. This can cause the table to overlap the text frame again. If this problem occurs, the table would actually have to be compressed again - which unfortunately changes the information about the original table required for
getKeyString()
in such a way thatgetKeyString()
can no longer work reliably. There is no solution for this problem at the moment!- Parameters
firstColumn (int) – Start the table reconstruction at this column
columnSpan (int) – How many columns each form a block that must not be separated by table rows?
flattenLastChunk (bool) –
True
: If necessary and if possible, the cells of the last columns are not moved underneath each other, but next to each other in one row.
copyColumnHeader (bool) – Transfer contents of the “guide cells” to the new lines?
fitColumns (int) –
How to perform the column fitting.
One of Table column compression
-
Shrink columns to their minimum before rebuilding table, broaden columns to fit the text frame after rebuilding.
-
Shrink columns to their minimum before rebuilding table.
-
Broaden columns to fit the text frame after rebuilding.
comet.kBroadenNever
:Leave the column widths untouched.
-
delimitRowHeight (float) –
Create a transparent delimiter row of the given height
0.0: No delimiting row
< 0.0: Use current row height
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.decompressColumnWise()¶
Undo a table compression by
compressColumnWise()
orwoodoo()
. Changes in column widths between the lastcompressColumnWise()
anddecompressColumnWise()
will be overwritten.- Return type
- Raises
CometError – On internal error
- Available
- CScript
- CTable.woodoo(adjustToFrame=True)¶
Reorder a 4 column table to make it as small as possible and still fit into the surrounding frame, see the following images:
Before
After
Just Woodoo. The counterspell is called
oodoow()
, which returns the table to its original state. There are some restrictions :woodoo works only with 4-column tables.
Only the first and third column are checked.
The cells of columns 1 and 3 have the same cell style. But the columns may have different cell styles.
The table may become taller. To be able to determine text oversets in the cells, the entire table must be visible (No table cells may disappear in the overset.). For this purpose, the frame is made taller in the meantime if necessary - but this can only be done up to the lower end of the working area (minus a safety margin of 32 points). So woodoo must not make the table so tall that it would protrude downwards beyond the working area.
If a table has already been compressed with
woodoo()
orcompressColumnWise()
, it will first be automatically restored to its original state.To make things easier, the general counterspell
decompressColumnWise()
can also be used as an antidote. And vice versa,oodoow()
also returns tables packed withcompressColumnWise()
to their original state.- Parameters
adjustToFrame (bool) –
Adjust table to frame at the end?
False
: NoTrue
: Yes.The first and third columns of the table are widened so that the right outer edge of the frame exactly matches the right boundary line of the table. (Frame width, type and color must be defined in the cell styles of the cells!) For tables that remain wider than the frame, the parameter has no effect.
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.oodoow()¶
Tables that have been compressed with
woodoo()
are restored to their original state. Manual changes of column widths and cell styles betweenwoodoo()
andoodoow()
are overwritten.- Raises
CometError – On internal error
- Available
- CScript
- CTable.getKeyStr(infoType=1)¶
Determine a key for a table. The table is traversed row by row and the desired information is determined and appended to the result string. The key is independent of whether the table was processed with
compressColumnWise()
orwoodoo()
.- Parameters
infoType (int) –
What information should the key contain?
0 : Row Column …
1 : PlaceholderID ID ID2 …
2 : PlaceholderID ID ID2 ID3 …
3 : PlaceholderID ID ID2 ID3 “StringID” …
4 : “Cell Text” …
- Returns
The calculated key str.
- Return type
- Raises
TypeError – When parameter types are invalid
CometError – On internal error
- Available
- CScript
- CTable.remove()¶
Deletes this table from its document. All subsequent calls to this table’s functions will fail.
- Returns
None
- Raises
CometError – On internal error
- Available
- CScript