Tables

Add tables of cells, and arrange a text area in columns.

Table

class creator_studio_doc_format.core.Table(*, preset_identifier='', identifier=None, geometry=None, aspect_ratio_locked=False, description=None, title=None, caption=None, table_name_border_enabled=False, number_of_columns, number_of_rows, number_of_header_rows=0, number_of_header_columns=0, number_of_footer_rows=0, default_column_width=98, default_row_height=20, visual_properties=None, column_headers=None, content=None, merges=None, conditional_style_sets=None, custom_formats=None, transformation=None, **extra_data)[source]

A table of cells, nested two levels deep.

content holds the table’s rows, ordered top to bottom, and each row’s cells holds that row’s cells, ordered left to right. The first number_of_header_rows rows are header rows, and the last number_of_footer_rows are footer rows. Rows and cells that carry nothing may be omitted, so Table.Row.row_index and Table.Cell.column_index mark where a run resumes after a gap. On a slide, a table whose title is absent, has no text, or reads Unnamed or Unnamed Table gets a default name such as Table 1 as its built-in title, and Keynote renames tables there that share a name the same way until each has its own; which of them keeps the name isn’t defined, and Keynote reports no warning.

field identifier : str | None = None

An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.

field geometry : Geometry | None = None

The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.

field aspect_ratio_locked : bool = False

A Boolean value that indicates whether the object’s width-to-height ratio is locked when the object resizes. The lock doesn’t constrain the geometry property. If this property is absent, images, movies, and groups default to true, and other objects to false.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field title : Label | None = None

The object’s title.

field caption : Label | None = None

The object’s caption, which Keynote always places below the object. If a caption is off, you still write it out with Label.is_visible set to false, so having a value doesn’t mean the caption shows.

field table_name_border_enabled : bool = False

Whether a border is drawn around the table’s name (title) box. The border uses the header row’s border stroke, Table.VisualProperties.header_row_stroke_properties.border_stroke.

field number_of_columns : int [Required]

The total number of columns in the table, including header, body, and hidden columns. A count below 1, or above the largest supported column count, is adjusted to the nearest supported count rather than rejected.

field number_of_rows : int [Required]

The total number of rows in the table, including header, body, footer, hidden, and filtered rows. A count below 1, or above the largest supported row count, is adjusted to the nearest supported count rather than rejected.

field number_of_header_rows : int = 0

The number of header rows at the top of the table, which are styled separately from body rows and typically contain column titles. A negative count, or one greater than number_of_rows, is adjusted to fit rather than rejected.

field number_of_header_columns : int = 0

The number of header columns at the leading edge of the table, which are styled separately from body columns and typically contain row labels. A negative count, or one greater than number_of_columns, is adjusted to fit rather than rejected.

The number of footer rows at the bottom of the table, which are styled separately from body rows and typically contain totals or summaries. A negative count is treated as zero, and if number_of_header_rows plus number_of_footer_rows would exceed number_of_rows, the footer count is reduced to fit rather than rejected.

field default_column_width : float = 98

The default column width, in points, which must be greater than 0. It’s used for any column that doesn’t override it with Table.ColumnHeader.column_width.

field default_row_height : float = 20

The default row height, in points, which must be greater than 0. It’s used for any row that doesn’t override it with Table.Row.row_height.

field visual_properties : VisualProperties | None = None

The default styles for the whole table. These are table-level properties, such as strokes and alternating row fills, plus default cell and text properties for each region (body, header rows, header columns, and footer rows). Cell- and column-level overrides take precedence over these defaults.

field column_headers : list[ColumnHeader] | None = None

The metadata for each column, including its stable column ID, its display title, its default cell format, style, and text, and an optional column width override. It provides the column identity that formula references and merges use. There’s one entry for each column, in left-to-right order, so an entry’s position here is that column’s position in every row’s cells.

field content : list[Row] | None = None

The table’s rows as displayed, including header and footer rows; trailing blank rows can be omitted. Hidden and filtered rows are included, marked by their Table.Row.visibility_state.

field merges : list[CellRange] | None = None

The cell ranges that are each visually merged into a single cell. The content is in the top-left cell, and the other cells in the range are blank. Each range names its corners by this table’s row and column IDs. If a corner names a row or column the table doesn’t have, or a range’s end comes before its start, Keynote drops the whole table, with a warning, instead of loading the table without that merge.

field conditional_style_sets : list[ConditionalStyleSet] | None = None

The shared sets of conditional highlighting rules. Cells reference a set by ID in Table.Cell.conditional_style_set_identifier, so the same rules can be reused across many cells without duplication.

field custom_formats : list[CustomFormat] | None = None

The shared custom-format definitions. Cells whose cell_format.format_type is custom reference one of these by ID in cell_format.custom_format_identifier, so the same format definition can be reused across many cells without duplication.

field transformation : TransformationInfo | None = None

The filter and sort rules applied to this table, in filter_set and sort; content holds the result.

ColumnMetrics

class creator_studio_doc_format.core.ColumnMetrics(*, preset_identifier='', equal=None, single=None, unequal=None, **extra_data)[source]

The arrangement of a text area into columns, and the width of the gutters between them.

field equal : EqualColumnsDescription | None = None

All the columns are the same width, and so are all the gutters.

field single : Literal[True] | None = None

A single column.

field unequal : UnequalColumnsDescription | None = None

Each of the column and gutter widths is specified.

EqualColumnsDescription

class creator_studio_doc_format.core.EqualColumnsDescription(*, preset_identifier='', count, gutter_width=None, **extra_data)[source]

An arrangement of a text area into columns of equal width.

Only count and gutter_width are specified; each column takes an equal share of the width the gutters leave. The gutters together are clamped to 75% of the text width, so a large gutter_width is silently narrowed.

field count : int [Required]

The number of columns.

Constraints:
  • ge = 1

  • le = 10

field gutter_width : float | None = None

The width of the gutter between adjacent columns, the same between every pair, as a percentage of the width available for text inside the container (its width less its padding). It’s only meaningful when count is greater than 1; the default is 5%.

Constraints:
  • ge = 0

  • le = 75

UnequalColumnsDescription

class creator_studio_doc_format.core.UnequalColumnsDescription(*, preset_identifier='', column_widths, gutter_widths=None, **extra_data)[source]

An arrangement of a text area into columns of specified widths.

Each of the column and gutter widths is specified, and together they must total 100.

field column_widths : list[float] [Required]

The width of each column, as a percentage of the width available for text inside the container (its width less its padding). The number of columns is the length of this array, and the column widths together with the gutter widths must total 100.

Constraints:
  • min_length = 1

  • max_length = 10

field gutter_widths : list[float] | None = None

The width of the gutter following each column, as a percentage of the width available for text inside the container (its width less its padding). The array’s length must be exactly one less than the number of column widths, or the content is rejected; if it’s omitted, there are no gutters, which is valid only for a single column.

Constraints:
  • min_length = 1

  • max_length = 9

Table structure

Rows and columns

Define a table’s rows and column headers, and the ranges of cells across them.

Cells

Set the values, formulas, and appearance of a table’s cells.

Formats and styles

Cell formats

Control how Keynote displays a cell’s value.

Table appearance

Set a table’s overall properties and the strokes around and between its cells.

Conditional styles

Style a cell when its value meets a condition.

Row filters and sorts

Filters, sorts, and pivot tables

Filter and sort a table’s rows, and find the types the format reserves for categorized and pivot tables.

See also

Add a table