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

InDesign® comet_pdf® Returns the frame this table is contained in

Illustrator® Returns the table group

Returns:

The table frame

Return type:

CFrame

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf®

CTable.getTextPosition()

Get the text position and length of a table.

The function returns text position and length of the contents of the table.

InDesign® 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:

InDesign® comet_pdf®

CScript:

table::get_textpos

CTable.getAnchorPosition()

Get the text position and length of the table anchor.

InDesign® 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:

InDesign® comet_pdf®

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:

InDesign® comet_pdf® Illustrator®

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

    Illustrator® 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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::remove_rows

CTable.convertToHeaderRows(count)

Convert normal table rows into header rows.

The first normal table row is always used as the starting row.

After the conversion, the table must still contain at least one normal row.

The function restricts the range of rows to be converted as required.

Parameters:

count (int) –

Number of normal rows that are to be converted into header rows.

If required, the number is limited to body rows - 1.

Return type:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

table::convert_to_headerrows

CTable.convertToBodyRows(index, count)

Convert headers or footers into body rows.

The conversion must always be carried out in such a way that the header and footer row areas are not broken.

Parameters:

  • index (int) – First line (0-based) to be converted.

  • count (int) – Number of rows to be converted to body rows.

Return type:

None

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter index is < 0

    • When parameter count is <= 0

  • CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

table::convert_to_bodyrows

CTable.convertToFooterRows(count)

Convert body rows into footer rows.

The row that is count above the first footer row is always used as the starting row.

The function restricts the range of rows to be converted as required.

Parameters:

count (int) – Number of rows to be converted to footer rows.

Return type:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

table::convert_to_footerrows

CTable.getColumnCount()

Returns the number of columns in the table

Returns:

The number of columns

Return type:

int

Raises:

CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

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

    Illustrator® 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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::remove_cols

CTable.getRowHeight(index, count=1)

Returns the height of a contiguous range of table rows.

comet_pdf® 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:

InDesign® comet_pdf® Illustrator®

CScript:

table::get_row_height

CTable.setRowHeight(index, height, count=1, minHeight=-1.0, maxHeight=-1.0)

Change the height of table rows.

InDesign® 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

    Illustrator® Ignored

  • maxHeight (float) –

    New maximum height

    • -1.0: Ignore

    Illustrator® 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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::resize_cols

Examples:

Resize the first column of the first table of the script frame to 10.0pt.

#!py
import comet

def main() -> int:
    #Get the first table of the script frame
    tables: list[comet.CTable] = comet.table.find(frames = [comet.gFrame])

    if not tables:
        #No tables found
        return 0

    table: comet.CTable = tables[0]

    table.setColumnWidth(0, 10.0)

    return 0
CTable.fitColumn(index, canShrink=False, keepLineHeights=False, precision=0.1, maxWidth=100.0, retries=30)

Adjust the width of a column so that no cell in the column has a text overset.

If no cell has a text overset, the column width can also be reduced.

The function can only be used for tables that are in the visible area of a text frame. Tables in the text overset cannot be adjusted. In this case, the function will raise a CometError with code 1259 (tableInOversetErr).

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, different results may occur if the column widths are adjusted in a different order!

Due to the slightly different text widths in InDesign® and comet_pdf, the column widths obtained in InDesign® and comet_pdf may vary slightly.

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) –

    Reduce column widths only so far that no cell in the table becomes taller (only evaluated if canShrink = True)?

    • True: Keep cell heights while shrinking column widths.

    • False: Cells can become taller.

    Cells with more than one paragraph may need a taller row too to avoid oversets. In this case the function will raise a CometError with code 1277 (cannotRemoveOversetErr).

    comet_pdf® Ignored

  • precision (float) –

    Precision to fit in pt.

    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.

    comet_pdf® Automatically uses the default of 0.1 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, a CometError with code 1278 (maxWidthTooSmallErr) is raised.

  • 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 with code 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:

InDesign® comet_pdf®

CScript:

table::fit_col

CTable.getStyle()

Determines the active table style.

InDesign® comet_pdf® 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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::apply_style

CTable.mergeCells(left, top, right, bottom, copyPolicy=0, delimiterText='', autoExtend=False)

Merge a table area to a cell.

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.

    comet_pdf® Illustrator® 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.

    InDesign® comet_pdf® 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:

InDesign® comet_pdf® Illustrator®

CScript:

table::merge

CTable.mergeEqual(direction=0, checkPageBreaks=False, compareWhat=0, left=0, top=0, right=-1, bottom=-1, xJustifyH=-1, yJustifyH=-1, xJustifyV=-1, yJustifyV=-1, flags=0)

Merge cells with the same content.

Parameters:

  • direction (int) –

    In which direction should cells be merged?

    • 0: Column by column

    • 1: Row by row

    • 2: Both directions. This corresponds to two calls of the function, first row by row, then column by column.

  • checkPageBreaks (bool) –

    Should frame breaks be taken into account when joining cells or not?

    • True:

      Yes. In this case, only cell ranges that are in the same frame of the text chain are merged.

      The frame breaks of the table are therefore retained.

    • False: No

  • compareWhat (int) –

    How should it be determined whether table cells are the same?

    • 0: Compare TaggedText

    • 1: Check placeholders. In this case, cells are only the same if the placeholders they contain are the same.

      Created/Modified attributes of the placeholders are ignored in this check.

    • 2: Compare the plain text of the cells.

    • 3: Compare plain text as net weight of the cells.

  • left (int) – Start column of the area to be edited (0-based).

  • top (int) – Start row of the area to be edited (0-based).

  • right (int) –

    Column end of the area to be edited (0-based). The value is the first column that is no longer to be edited.

    • -1: End of the table

  • bottom (int) –

    Row end of the area to be edited (0-based). The value is the first line that is no longer to be edited

    • -1: End of the table

  • xJustifyH (int) –

    Horizontal alignment of the cell content when merging cells of the same row.

    Possible values

    • -1: leave unchanged

    • 0: left

    • 1: centered

    • 2: right

    • 3: System setting

    • 4: Justified, last line left

    • 5: Justification, last line centered

    • 6: Justified, last line right

    • 7: automatic

    • 8: to the spine

    • 9: away from spine

  • yJustifyH (int) –

    Vertical alignment of the cell content when merging cells of the same row.

    Possible values

    • -1: leave unchanged

    • 0: top

    • 1: middle

    • 2: bottom

  • xJustifyV (int) –

    Horizontal alignment of the cell content when joining cells of the same column.

    Possible values

    • -1: leave unchanged

    • 0: left

    • 1: centered

    • 2: right

    • 3: System setting

    • 4: Justified, last line left

    • 5: Justification, last line centered

    • 6: Justified, last line right

    • 7: automatic

    • 8: to the spine

    • 9: away from spine

  • yJustifyV (int) –

    Vertical alignment of the cell content when merging cells of the same column.

    Possible values

    • -1: leave unchanged

    • 0: top

    • 1: middle

    • 2: bottom

  • flags (int) –

    Bit field for adapting the behavior of the function

    • 1: Cells that have already been merged may be included in new merges.

      If the option is not set, cells below a cell range with the same content are not added to the cell range.

    • 2 : Search also below/behind the start cell for cell ranges with the same content.

      When joining the columns

      aaa | aaa | bbb | bbb | ccc

      without the option, only the columns

      aaa | aaa

      are merged; if this option is activated, the columns

      bbb | bbb

      are also merged.

Returns:

Number of newly created cell merges after executing the function.

Return type:

int

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter direction has invalid value

    • When parameter compareWhat has invalid value

    • When parameter xJustifyH has invalid value

    • When parameter yJustifyH has invalid value

    • When parameter xJustifyV has invalid value

    • When parameter yJustifyV has invalid value

  • CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

table::merge_equal

CTable.mergeEqualInFrame(frame, compareWhat=0, left=0, right=-1, xJustifyH=-1, yJustifyH=-1, xJustifyV=-1, yJustifyV=-1, flags=0)

Merge cells with the same content in a given frame.

In contrast to mergeEqual(), only cells that are in the given frame are merged.

comet_pdf® This function is available but behaves like mergeEqual().

If these rows are shrunken in height by the merge, further possible cells from the subsequent frames are automatically included in the merge.

Parameters:

  • frame (CFrame) –

    The frame to perform the merge in.

    Must be a frame containing the table.

  • compareWhat (int) –

    How should it be determined whether table cells are the same?

    • 0: Compare TaggedText

    • 1: Check placeholders. In this case, cells are only the same if the placeholders they contain are the same.

      Created/Modified attributes of the placeholders are ignored in this check.

    • 2: Compare the plain text of the cells.

    • 3: Compare plain text as net weight of the cells.

  • left (int) – Start column of the area to be edited (0-based).

  • top (int) – Start row of the area to be edited (0-based).

  • right (int) –

    Column end of the area to be edited (0-based). The value is the first column that is no longer to be edited.

    • -1: End of the table

  • bottom (int) –

    Row end of the area to be edited (0-based). The value is the first line that is no longer to be edited

    • -1: End of the table

  • xJustifyH (int) –

    Horizontal alignment of the cell content when merging cells of the same row.

    Possible values

    • -1: leave unchanged

    • 0: left

    • 1: centered

    • 2: right

    • 3: System setting

    • 4: Justified, last line left

    • 5: Justification, last line centered

    • 6: Justified, last line right

    • 7: automatic

    • 8: to the spine

    • 9: away from spine

  • yJustifyH (int) –

    Vertical alignment of the cell content when merging cells of the same row.

    Possible values

    • -1: leave unchanged

    • 0: top

    • 1: middle

    • 2: bottom

  • xJustifyV (int) –

    Horizontal alignment of the cell content when joining cells of the same column.

    Possible values

    • -1: leave unchanged

    • 0: left

    • 1: centered

    • 2: right

    • 3: System setting

    • 4: Justified, last line left

    • 5: Justification, last line centered

    • 6: Justified, last line right

    • 7: automatic

    • 8: to the spine

    • 9: away from spine

  • yJustifyV (int) –

    Vertical alignment of the cell content when merging cells of the same column.

    Possible values

    • -1: leave unchanged

    • 0: top

    • 1: middle

    • 2: bottom

  • flags (int) –

    Bit field for adapting the behavior of the function

    • 1: Cells that have already been merged may be included in new merges.

      If the option is not set, cells below a cell range with the same content are not added to the cell range.

    • 2 : Search also below/behind the start cell for cell ranges with the same content.

      When joining the columns

      aaa | aaa | bbb | bbb | ccc

      without the option, only the columns

      aaa | aaa

      are merged; if this option is activated, the columns

      bbb | bbb

      are also merged.

Returns:

Number of newly created cell merges after executing the function.

Return type:

int

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter compareWhat has invalid value

    • When parameter xJustifyH has invalid value

    • When parameter yJustifyH has invalid value

    • When parameter xJustifyV has invalid value

    • When parameter yJustifyV has invalid value

  • CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

table::merge_equal_fr

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:

Illustrator®

CScript:

table::stroke

CTable.getSkipFirstHeader()

Are the header rows at the beginning of the table omitted?

Returns:

Whether the header rows at the beginning are omitted.

Return type:

bool

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

table::get_skip_first_header

CTable.setSkipFirstHeader(skip)

Omit the header rows at the beginning of the table?

Parameters:

skip (bool) –

  • True: Omit header rows at the beginning.

  • False: Don’t omit header rows at the beginning.

Return type:

None

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

table::set_skip_first_header

CTable.getSkipLastFooter()

Are the footer rows omitted at the end of the table?

Returns:

Whether the footer rows at the end are omitted.

Return type:

bool

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

table::get_skip_last_footer

CTable.setSkipLastFooter(skip)

Omit the footer rows at the end of the table?

Parameters:

skip (bool) –

  • True: Omit footer rows at the end.

  • False: Don’t omit footer rows at the end.

Return type:

None

Raises:

CometError – On internal error

Available:

InDesign®

CScript:

table::set_skip_last_footer

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.

    comet_pdf® Illustrator® Only supported format is constants.kExportPlain

Returns:

The cell’s text

Return type:

str

Raises:
Available:

InDesign® comet_pdf®

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.

    InDesign® comet_pdf® May be prefixed TaggedText

    InDesign® comet_pdf® Illustrator® May be prefixed HTML

  • position (int) – Insert position inside the cell

  • length (int) –

    How many characters to remove before inserting.

    Default is constants.kEnd == until the end.

Return type:

None

Raises:

TypeError – When parameter types are invalid

Available:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf®

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

    Illustrator® Ignored

Returns:

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

Return type:

tuple[float, float]

Raises:
Available:

InDesign® comet_pdf® Illustrator®

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

    comet_pdf® Illustrator® Frame and page relative results are not supported. Results will always be table relative.

Returns:

The cell box

Return type:

CRect

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

table::cell::get_box

CTable.getCellFrame(column, row)

Determine the frame a cell is in.

Illustrator® This always returns the parent table group frame.

InDesign® 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:

InDesign® Illustrator®

CTable.setCellFill(left, top, right, bottom, color, tint=-1.0)

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::colorize

Examples:

Set different cell fill colors of the first table of the script frame.

#!py
import comet

def main() -> int:
    #Get the first table of the script frame
    tables: list[comet.CTable] = comet.table.find(frames = [comet.gFrame])

    if not tables:
        #No tables found
        return 0

    table: comet.CTable = tables[0]

    #Set the cell fill at 0, 0 to RGB Red
    table.setCellFill(
        0, 0, 1, 1,
        color = (255, 0, 0)
    )

    #Set the cell fill at 1, 0 to CMYK Cyan
    table.setCellFill(
        1, 0, 2, 1,
        color = (1.0, 0.0, 0.0, 0.0)
    )

    #Set the cell fill at 2, 0 to the Swatch named 'CellFill'
    table.setCellFill(
        2, 0, 3, 1,
        color = 'CellFill'
    )

    return 0
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:

InDesign® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

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

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

Return type:

str

Raises:
Available:

InDesign® comet_pdf® Illustrator®

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

    InDesign® comet_pdf® If the style is part of a style hierarchy, use the complete ‘:’ delimited path here!

  • removeOverrides (bool) –

    Remove local overrides?

    Illustrator® Ignored

  • applyParaStyle (bool) –

    Should the cell style apply the configured paragraph style?

    Illustrator® 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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® Illustrator®

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:

InDesign® comet_pdf® Illustrator®

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:

InDesign® comet_pdf®

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:

InDesign®

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:

InDesign®

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:

InDesign®

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:

InDesign®

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:

InDesign®

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:

InDesign® comet_pdf® Illustrator®

CScript:

table::remove

Special methods

CTable.__repr__()

String representation.

Returns:

<CTable> UID: UID | Columns: Column count | Header rows: Header row count | Body rows: Body row count | Footer rows: Footer row count

Example
<CTable> UID: 477 | Columns: 4 | Header rows: 0 | Body rows: 2 | Footer rows: 0

Return type:

str