.. _tabledef-api:

Tabledef Interface
====================

The Tabledef interface represents Excel tables (also known as List Objects)
that provide structured data management with features like automatic filtering,
sorting, and total rows.

Classes
-------

.. cpp:class:: oo::iTabledef

   Interface for managing Excel tables with structured data, formatting, and calculation features.

   Basic Properties
   ~~~~~~~~~~~~~~~~

   .. cpp:function:: const char* name() const

      Get the table name.

      :returns: Table name

   .. cpp:function:: void range(int* beginRow, int* beginCol, int* endRow, int* endCol) const

      Get the table range coordinates.

      :param beginRow: Pointer to store starting row index
      :param beginCol: Pointer to store starting column index
      :param endRow: Pointer to store ending row index
      :param endCol: Pointer to store ending column index

   Display and Identification
   ~~~~~~~~~~~~~~~~~~~~~~~~~~

   .. cpp:function:: const char* display_name() const

      Get the table display name.

      :returns: Display name shown in Excel UI

   .. cpp:function:: void set_display_name(const char* name)

      Set the table display name.

      :param name: New display name

   .. cpp:function:: const char* comment() const

      Get the table comment/description.

      :returns: Table comment text

   .. cpp:function:: void set_comment(const char* comment)

      Set the table comment/description.

      :param comment: New comment text

   Column Management
   ~~~~~~~~~~~~~~~~~

   .. cpp:function:: const char* col_name(int idx) const

      Get column name by index.

      :param idx: Column index (0-based)
      :returns: Column name

   .. cpp:function:: bool set_col_name(int idx, const char* name)

      Set column name.

      :param idx: Column index (0-based)
      :param name: New column name
      :returns: true if successful

   .. cpp:function:: bool insert_col(int idx, const char* colName)

      Insert a new column into the table.

      :param idx: Position to insert (0-based)
      :param colName: Name for the new column
      :returns: true if successful

   .. cpp:function:: void delete_col_by_index(int idx)

      Delete a column by index.

      :param idx: Column index to delete (0-based)

   .. cpp:function:: void delete_col(const char* colName)

      Delete a column by name.

      :param colName: Column name to delete

   Totals Row
   ~~~~~~~~~~

   .. cpp:function:: void set_totals_row_label(const char* label)

      Set the label for the totals row.

      :param label: Label text for totals row

   .. cpp:function:: void set_display_total(bool show = true)

      Show or hide the totals row.

      :param show: true to show totals row, false to hide

   .. cpp:function:: TotalsFuncEnum totals_row_func(int column_idx) const

      Get the totals function for a column.

      :param column_idx: Column index (0-based)
      :returns: Totals function type

   .. cpp:function:: void set_totals_row_func(int colIndex, TotalsFuncEnum func)

      Set the totals function for a column.

      :param colIndex: Column index (0-based)
      :param func: Totals function to apply

   Table Styling
   ~~~~~~~~~~~~~

   .. cpp:function:: const char* style_name() const

      Get the table style name.

      :returns: Table style name

      .. toctree::
         :maxdepth: 1

         preset_table_styles.rst

   .. cpp:function:: void set_style_name(const char* style_name)

      Set the table style by name.

      :param style_name: Table style name

   .. cpp:function:: void set_preset_style(int id)

      Set a predefined table style with identification code.

      :param id: Preset style identifier

      .. toctree::
         :maxdepth: 1

         preset_table_styles.rst

   .. cpp:function:: bool row_strips() const

      Check if banded rows are enabled.

      :returns: true if banded rows are shown

   .. cpp:function:: void set_row_strips(bool strips = true)

      Enable or disable banded rows.

      :param strips: true to show banded rows, false for solid fill

Usage Example
-------------

.. code-block:: cpp

   #include "oosxl.hxx"

   // Get or create a table
   oo::iTabledef* table = worksheet->add_tabledef("SalesData", 1, 0, 10, 3);

   // Set column names
   table->set_col_name(0, "Date");
   table->set_col_name(1, "Product");
   table->set_col_name(2, "Quantity");
   table->set_col_name(3, "Revenue");

   // Configure totals row
   table->set_display_total(true);
   table->set_totals_row_func(2, TOTALS_FUNC_SUM);  // Sum for Quantity
   table->set_totals_row_func(3, TOTALS_FUNC_SUM);  // Sum for Revenue

   // Apply table style
   table->set_style_name("TableStyleMedium4");
   table->set_row_strips(true);

   // Set table properties
   table->set_display_name("Quarterly Sales Data");
   table->set_comment("Sales data for Q1 2023");

Totals Functions Reference
--------------------------

.. list-table:: Available Totals Functions
   :widths: 30 70
   :header-rows: 1

   * - Function
     - Description
   * - TOTALS_FUNC_NONE
     - No total calculation
   * - TOTALS_FUNC_SUM
     - Arithmetic sum of values
   * - TOTALS_FUNC_AVERAGE
     - Arithmetic mean of values
   * - TOTALS_FUNC_COUNT
     - Count of non-empty cells
   * - TOTALS_FUNC_COUNT_NUMS
     - Count of cells containing numbers
   * - TOTALS_FUNC_CUSTOM
     - Custom formula provided separately
   * - TOTALS_FUNC_MIN
     - Smallest value in the column
   * - TOTALS_FUNC_MAX
     - Largest value in the column
   * - TOTALS_FUNC_STDDEV
     - Estimated standard deviation
   * - TOTALS_FUNC_VAR
     - Estimated variance

Notes
-----

- Table names must be unique within a workbook
- Column operations automatically adjust the table range
- Totals row functions only work with appropriate data types
- Table styles follow Excel's built-in table style names
- Inserting/deleting columns affects all rows in the table
