# Table Definition API Reference

## Overview

The Table Definition API provides functions to manage Excel tables (formerly known as List Objects), including table properties, column management, total rows, and styling options.

## Table Properties

const char *td_name(TabledefHandle td)

  Get the table name.

  Parameters:

    - td – Table definition handle.

  Returns:

    Table name.

void td_range(TabledefHandle td, int *beginRow, int *beginCol, int *endRow, int *endCol)

  Get the table range coordinates.

  Parameters:

    - td – Table definition handle.

    - beginRow – Pointer to store start row index.

    - beginCol – Pointer to store start column index.

    - endRow – Pointer to store end row index.

    - endCol – Pointer to store end column index.

const char *td_display_name(TabledefHandle td)

  Get the table display name.

  Parameters:

    - td – Table definition handle.

  Returns:

    Table display name.

void td_set_display_name(TabledefHandle td, const char *name)

  Set the table display name.

  Parameters:

    - td – Table definition handle.

    - name – New display name.

const char *td_comment(TabledefHandle td)

  Get the table comment.

  Parameters:

    - td – Table definition handle.

  Returns:

    Table comment.

void td_set_comment(TabledefHandle td, const char *comment)

  Set the table comment.

  Parameters:

    - td – Table definition handle.

    - comment – Table comment.

## Column Management

const char *td_col_name(TabledefHandle td, int idx)

  Get column name by index.

  Parameters:

    - td – Table definition handle.

    - idx – Column index.

  Returns:

    Column name.

int td_set_col_name(TabledefHandle td, int idx, const char *name)

  Set column name.

  Parameters:

    - td – Table definition handle.

    - idx – Column index.

    - name – New column name.

  Returns:

    1 on success, 0 on failure.

int td_insert_col(TabledefHandle td, int idx, const char *colName)

  Insert a new column into the table.

  Parameters:

    - td – Table definition handle.

    - idx – Position to insert the column.

    - colName – Name for the new column.

  Returns:

    1 on success, 0 on failure.

void td_delete_col_by_index(TabledefHandle td, int idx)

  Delete column by index.

  Parameters:

    - td – Table definition handle.

    - idx – Column index to delete.

void td_delete_col(TabledefHandle td, const char *colName)

  Delete column by name.

  Parameters:

    - td – Table definition handle.

    - colName – Column name to delete.

## Total Row Settings

void td_set_totals_row_label(TabledefHandle td, const char *label)

  Set the total row label.

  Parameters:

    - td – Table definition handle.

    - label – Total row label.

void td_set_display_total(TabledefHandle td, int show)

  Set whether to display the total row.

  Parameters:

    - td – Table definition handle.

    - show – 1 to show total row, 0 to hide.

int td_totals_row_func(TabledefHandle td, int column_idx)

  Get the total row function for a column.

  Parameters:

    - td – Table definition handle.

    - column_idx – Column index.

  Returns:

    Total function type (see `TotalsFuncEnum`).

void td_set_totals_row_func(TabledefHandle td, int colIndex, int func)

  Set the total row function for a column.

  Parameters:

    - td – Table definition handle.

    - colIndex – Column index.

    - func – Total function type (see `TotalsFuncEnum`).

## Table Styling

const char *td_style_name(TabledefHandle td)

  Get the table style name.

  Parameters:

    - td – Table definition handle.

  Returns:

    Table style name.

  - Built-in Table Styles

void td_set_style_name(TabledefHandle td, const char *style_name)

  Set the table style by name.

  Parameters:

    - td – Table definition handle.

    - style_name – Table style name.

void td_set_preset_style(TabledefHandle td, int id)

  Set table preset style.

  Parameters:

    - td – Table definition handle.

    - id – Preset style ID.

int td_row_strips(TabledefHandle td)

  Check if row banding (stripes) is enabled.

  Parameters:

    - td – Table definition handle.

  Returns:

    1 if row strips enabled, 0 otherwise.

void td_set_row_strips(TabledefHandle td, int strips)

  Set row banding (stripes).

  Parameters:

    - td – Table definition handle.

    - strips – 1 to enable row strips, 0 to disable.

## Enumerations

See Enumerations Reference for related enumerations used by these functions, particularly TotalsFuncEnum.

## Usage Notes

- Tables provide structured data management with built-in filtering, sorting, and formatting

- Total row functions can perform automatic calculations like sum, average, count, etc.

- Table styles control the visual appearance including colors, borders, and banding

- Column operations automatically adjust the table range and maintain data integrity

## Integration with Worksheets

Table definitions are typically created and accessed through worksheet functions:

    // Add table to worksheet
    TabledefHandle table = ws_add_tabledef(worksheet, "SalesData", 1, 1, 10, 5);

    // Configure table properties
    td_set_display_name(table, "Monthly Sales");
    td_set_display_total(table, 1);

    // Set total functions for specific columns
    td_set_totals_row_func(table, 3, TOTALS_FUNC_SUM);  // Sum for column 3 (sales amount)
    td_set_totals_row_func(table, 4, TOTALS_FUNC_AVERAGE);  // Average for column 4 (units sold)

Styled using the Piccolo Theme