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.

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)