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

table::remove