.. _tabledef-c-api:

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

.. c:function:: const char* td_name(TabledefHandle td)

    Get the table name.

    :param td: Table definition handle.
    :return: Table name.

.. c:function:: void td_range(TabledefHandle td, int* beginRow, int* beginCol, int* endRow, int* endCol)

    Get the table range coordinates.

    :param td: Table definition handle.
    :param beginRow: Pointer to store start row index.
    :param beginCol: Pointer to store start column index.
    :param endRow: Pointer to store end row index.
    :param endCol: Pointer to store end column index.

.. c:function:: const char* td_display_name(TabledefHandle td)

    Get the table display name.

    :param td: Table definition handle.
    :return: Table display name.

.. c:function:: void td_set_display_name(TabledefHandle td, const char* name)

    Set the table display name.

    :param td: Table definition handle.
    :param name: New display name.

.. c:function:: const char* td_comment(TabledefHandle td)

    Get the table comment.

    :param td: Table definition handle.
    :return: Table comment.

.. c:function:: void td_set_comment(TabledefHandle td, const char* comment)

    Set the table comment.

    :param td: Table definition handle.
    :param comment: Table comment.

Column Management
-----------------

.. c:function:: const char* td_col_name(TabledefHandle td, int idx)

    Get column name by index.

    :param td: Table definition handle.
    :param idx: Column index.
    :return: Column name.

.. c:function:: int td_set_col_name(TabledefHandle td, int idx, const char* name)

    Set column name.

    :param td: Table definition handle.
    :param idx: Column index.
    :param name: New column name.
    :return: 1 on success, 0 on failure.

.. c:function:: int td_insert_col(TabledefHandle td, int idx, const char* colName)

    Insert a new column into the table.

    :param td: Table definition handle.
    :param idx: Position to insert the column.
    :param colName: Name for the new column.
    :return: 1 on success, 0 on failure.

.. c:function:: void td_delete_col_by_index(TabledefHandle td, int idx)

    Delete column by index.

    :param td: Table definition handle.
    :param idx: Column index to delete.

.. c:function:: void td_delete_col(TabledefHandle td, const char* colName)

    Delete column by name.

    :param td: Table definition handle.
    :param colName: Column name to delete.

Total Row Settings
------------------

.. c:function:: void td_set_totals_row_label(TabledefHandle td, const char* label)

    Set the total row label.

    :param td: Table definition handle.
    :param label: Total row label.

.. c:function:: void td_set_display_total(TabledefHandle td, int show)

    Set whether to display the total row.

    :param td: Table definition handle.
    :param show: 1 to show total row, 0 to hide.

.. c:function:: int td_totals_row_func(TabledefHandle td, int column_idx)

    Get the total row function for a column.

    :param td: Table definition handle.
    :param column_idx: Column index.
    :return: Total function type (see :cpp:enum:`TotalsFuncEnum`).

.. c:function:: void td_set_totals_row_func(TabledefHandle td, int colIndex, int func)

    Set the total row function for a column.

    :param td: Table definition handle.
    :param colIndex: Column index.
    :param func: Total function type (see :cpp:enum:`TotalsFuncEnum`).

Table Styling
-------------

.. c:function:: const char* td_style_name(TabledefHandle td)

    Get the table style name.

    :param td: Table definition handle.
    :return: Table style name.

    .. toctree::
       :maxdepth: 1

       ../cpp/preset_table_styles.rst

.. c:function:: void td_set_style_name(TabledefHandle td, const char* style_name)

    Set the table style by name.

    :param td: Table definition handle.
    :param style_name: Table style name.

.. c:function:: void td_set_preset_style(TabledefHandle td, int id)

    Set table preset style.

    :param td: Table definition handle.
    :param id: Preset style ID.

.. c:function:: int td_row_strips(TabledefHandle td)

    Check if row banding (stripes) is enabled.

    :param td: Table definition handle.
    :return: 1 if row strips enabled, 0 otherwise.

.. c:function:: void td_set_row_strips(TabledefHandle td, int strips)

    Set row banding (stripes).

    :param td: Table definition handle.
    :param strips: 1 to enable row strips, 0 to disable.

Enumerations
------------

See :ref:`enum-api` 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:

.. code-block:: c

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