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

CFrame

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

int

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

tuple[int, int]

Raises

CometError – On internal error

Available

CScript

table::get_textpos

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

tuple[int, int]

Raises

CometError – On internal error

Available

CScript

table::get_anchorpos

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

int

Raises
Available

See also

getColumnCount()

CScript

table::rows

CTable.insertRows(index, count=1, before=False, height=0.0, clearTags=True)

Insert rows into the table

Parameters

  • index (int) – The row index to insert rows at

  • count (int) – How many rows to insert

  • height (float) – Row height. When the value is 0.0, a default height is determined.

  • clearTags (bool) –

    Clear all place holders at the inserted cells?

    It is strongly recommended to set this to True

    Ignored

Paral bool before

Insert before index (True) or after (False)?

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

insertColumns()

CScript

table::insert_rows

CTable.removeRows(index, count)

Delete rows from this table.

This function can also delete header and footer rows.

Parameters

  • index (int) – The row index to remove rows at

  • count (int) –

    How many rows to remove

    • >0: Number of rows to delete

    • -1: All following rows including index

Return type

None

Raises
Available

CScript

table::remove_rows

CTable.getColumnCount()

Returns the number of columns in the table

Returns

The number of columns

Return type

int

Raises

CometError – On internal error

Available

See also

getRowCount()

CScript

table::columns

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

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

insertRows()

CScript

table::insert_cols

CTable.removeColumns(index, count)

Delete columns from this table.

Parameters

  • index (int) – The row index to remove columns at

  • count (int) –

    How many columns to remove

    • >0: Number of columns to delete

    • -1: All following columns including index

Return type

None

Raises
Available

CScript

table::remove_cols

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

  • index (int) – Start row index (0-based)

  • count (int) –

    How many rows should be queried?

    • -1: All following rows

Returns

The total height of the rows in the selected area

Return type

float

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter count has an invalid value

  • CometError – On internal error

Available

CScript

table::get_row_height

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

  • index (int) – Start row index (0-based)

  • height (float) – The new row height in pt

  • count (int) –

    How many rows should be changed?

    • -1: All following rows

  • minHeight (float) –

    New minimal height

    • -1.0: Ignore

    Ignored

  • maxHeight (float) –

    New maximum height

    • -1.0: Ignore

    Ignored

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

table::resize_rows

CTable.getColumnWidth(index, count=1)

Returns the width of a contiguous range of table columns.

Parameters

  • index (int) – Start column index (0-based)

  • count (int) –

    How many column should be queried?

    • -1: All following rows

Returns

The total width of the column in the selected area

Return type

float

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is out of bounds

    • When parameter count has an invalid value

  • CometError – On internal error

Available

CScript

table::get_col_width

CTable.setColumnWidth(index, width, count=1)

Change the width of table columns.

Parameters

  • index (int) – Start column index (0-based)

  • width (float) – The new row width in pt

  • count (int) –

    How many columns should be changed?

    • -1: All following columns

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

table::resize_cols

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?

    • True: shrink columns larger than its content

    • False: not allowed, only broaden

  • keepLineHeights (bool) –

    Take care on line heights while shrinking column? (only evaluated if canShrink = True)

    • True: Keep cell heights while shrinking

    • False: Cells can become higher

    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

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

table::fit_col

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

str

Raises

CometError – On internal error

Available

CScript

table::get_style

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

  • styleName (str) – Which style to apply

  • removeTableOverrides (bool) – Should local table overrides be removed?

  • removeCellStyles (bool) – Should cell styles be removed?

Return type

None

Raises
Available

CScript

table::apply_style

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

    • True: Self-extending area

    • False: Raise CometError

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError – When parameters left, top, right or bottom are out of bounds

  • CometError –

    • On internal error

    • When autoExtend is False and the area is not mergeable

Available

CScript

table::merge

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
Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

table::stroke

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

str

Raises
Available

See also

CFrame.getText()

CScript

table::get_text

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

None

Raises

TypeError – When parameter types are invalid

Available

CScript

table::set_text

CTable.getCellTextPosition(column, row)

Determine the text position and length 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

Returns

The cell’s text position and length as a tuple: (position, length)

Return type

tuple[int, int]

Raises
Available

CScript

table::cell::get_textpos

CTable.getCellSize(column, row, areaType=0)

Determine the size 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) –

    Which cell size you wish to get?

    • 0 : The cell itself

    • 1 : Content

    • 2 : Cell without strokes

    Ignored

Returns

The cell size as a tuple: (width, height)

Return type

tuple[float, float]

Raises
Available

CScript

table::cell::get_size

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

CRect

Raises
Available

CScript

table::cell::get_box

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

  • column (int) –

    0-based column

    • -1 or > column count: Last column

  • row (int) –

    0-based row

    • -1 or > row count: Last row

Returns

The frame containing the cell

Return type

CFrame

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

    • CColor

      A color. Must of be RGB or CMYK type.

    • CSwatch

      A Swatch. This applies the swatch to the item.

    • str

      A Swatch name. This applies the swatch to the item.

    • tuple [int, int, int]

      Red, Green, Blue values in range[0, 255]

    • tuple [float, float, float, float]

      C, M, Y, K values in range[0.0, 1.0]

  • tint (float) –

    The opacity of the fill in range[0.0, 100.0].

    • -1.0: Leave unchanged

Return type

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • 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

table::colorize

CTable.getCellInsets(column, row)

Determine the inset 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

Returns

The cell insets as a tuple: (left, top, right, bottom)

Return type

tuple[float, float, float, float]

Raises
Available

CScript

table::cell::get_insets

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:

    (int, int, int)

    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

    (int, int, int, int)

    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

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter inset has negative value

    • When fields describes an area with contradictory start and end values

  • CometError – On internal error

Available

CScript

table::inset

CTable.getCellStyle(column, row)

Determine the cell style of the given cell

Parameters

  • column (int) –

    0-based column

    • -1 or > column count: Last column

  • row (int) –

    0-based row

    • -1 or > row count: Last row

Returns

The applied cell style

When the style if part of a hierarchy, the name is delimited by ‘:’

Return type

str

Raises
Available

CScript

table::cell::get_style

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

None

Raises

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter left, top, right, bottom are out of bounds

    • When parameter cellStyle designates invalid style

  • CometError – On internal error

Available

CScript

table::cell::apply_style

CTable.getCellType(column, row)

Determine whether a cell is a text cell of a graphic cell

Parameters

  • column (int) –

    0-based column

    • -1 or > column count: Last column

  • row (int) –

    0-based row

    • -1 or > row count: Last row

Returns

The cell type

One of Cell types

Return type

int

Raises
Available

CScript

table::cell::get_style

CTable.cellHasOverset(column, row)

Determine whether a cell in this table has an overset.

Parameters

  • column (int) –

    0-based column

    • -1 or > column count: Last column

  • row (int) –

    0-based row

    • -1 or > row count: Last row

Returns

Whether the cell is overset

Return type

bool

Raises
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?

  • columns (list[str]) –

    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

None

Raises
Available

CScript

table::broaden_to_frame

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 that getKeyString() 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

  • delimitRowHeight (float) –

    Create a transparent delimiter row of the given height

    • 0.0: No delimiting row

    • < 0.0: Use current row height

Return type

None

Raises
Available

CScript

table::compress_colwise

CTable.decompressColumnWise()

Undo a table compression by compressColumnWise() or woodoo(). Changes in column widths between the last compressColumnWise() and decompressColumnWise() will be overwritten.

Return type

None

Raises

CometError – On internal error

Available

CScript

table::decompress_colwise

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:

_images/woodoo1.gif

Before

_images/woodoo2.gif

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() or compressColumnWise(), 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 with compressColumnWise() to their original state.

Parameters

adjustToFrame (bool) –

Adjust table to frame at the end?

  • False: No

  • True: 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

None

Raises
Available

CScript

table::woodoo

CTable.oodoow()

Tables that have been compressed with woodoo() are restored to their original state. Manual changes of column widths and cell styles between woodoo() and oodoow() are overwritten.

Raises

CometError – On internal error

Available

CScript

table::oodoow

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() or woodoo().

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

str

Raises
Available

CScript

table::get_keystring

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

table::remove