.. _workbook-c-api:

Workbook API Reference
======================

Overview
--------

The Workbook API provides functions to manage Excel workbooks,
including date system settings, calculation modes,
worksheet management, named styles, and defined names.

Workbook Properties
-------------------

.. c:function:: int wb_is_date1904(WorkbookHandle book)

    Check if the workbook uses the 1904 date system.

    :param book: Handle to the workbook instance.
    :return: 1 if using 1904 date system, 0 otherwise.

.. c:function:: void wb_set_date1904(WorkbookHandle book, int set)

    Set the workbook to use 1904 date system.

    :param book: Handle to the workbook instance.
    :param set: 1 to enable 1904 date system, 0 to disable.

.. c:function:: int wb_is_a1_ref_mode(WorkbookHandle book)

    Check if the workbook uses A1 reference style.

    :param book: Handle to the workbook instance.
    :return: 1 if using A1 reference style, 0 otherwise.

.. c:function:: void wb_set_a1_ref_mode(WorkbookHandle book, int mode)

    Set the workbook reference style.

    :param book: Handle to the workbook instance.
    :param mode: 1 for A1 reference style, 0 for R1C1 style.

.. c:function:: int wb_get_calc_mode(WorkbookHandle book)

    Get the calculation mode.

    :param book: Handle to the workbook instance.
    :return: Calculation mode (see :cpp:enum:`CalcTypeEnum`).

.. c:function:: void wb_set_calc_mode(WorkbookHandle book, int type)

    Set the calculation mode.

    :param book: Handle to the workbook instance.
    :param type: Calculation type (see :cpp:enum:`CalcTypeEnum`).

Worksheet Management
--------------------

.. c:function:: WorksheetHandle wb_add_worksheet(WorkbookHandle book, const char* name)

    Add a new worksheet to the workbook.

    :param book: Handle to the workbook instance.
    :param name: Name of the new worksheet.
    :return: Handle to the created worksheet.

.. c:function:: WorksheetHandle wb_insert_worksheet(WorkbookHandle book, int index, const char* name)

    Insert a worksheet at specified position.

    :param book: Handle to the workbook instance.
    :param index: Position to insert the worksheet.
    :param name: Name of the new worksheet.
    :return: Handle to the created worksheet.

.. c:function:: void wb_shift_sheet(WorkbookHandle book, int srcIndex, int dstIndex)

    Move a worksheet to a different position.

    :param book: Handle to the workbook instance.
    :param srcIndex: Source worksheet index.
    :param dstIndex: Destination worksheet index.

.. c:function:: void wb_delete_sheet(WorkbookHandle book, int index)

    Delete a worksheet from the workbook.

    :param book: Handle to the workbook instance.
    :param index: Index of worksheet to delete.

.. c:function:: int wb_sheet_count(WorkbookHandle book)

    Get the number of worksheets in the workbook.

    :param book: Handle to the workbook instance.
    :return: Number of worksheets.

.. c:function:: WorksheetHandle wb_get_sheet(WorkbookHandle book, int index)

    Get a worksheet by index.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :return: Handle to the worksheet.

.. c:function:: int wb_sheet_type(WorkbookHandle book, int index)

    Get the type of a worksheet.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :return: Sheet type (see :cpp:enum:`SheetTypeEnum`).

.. c:function:: int wb_get_sheet_state(WorkbookHandle book, int index)

    Get the visibility state of a worksheet.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :return: Sheet state (see :cpp:enum:`SheetStateEnum`).

.. c:function:: void wb_set_sheet_state(WorkbookHandle book, int index, int state)

    Set the visibility state of a worksheet.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :param state: Sheet state (see :cpp:enum:`SheetStateEnum`).

.. c:function:: const char* wb_sheet_name(WorkbookHandle book, int index)

    Get the name of a worksheet.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :return: Worksheet name.

.. c:function:: void wb_rename_sheet(WorkbookHandle book, int index, const char* newname)

    Rename a worksheet.

    :param book: Handle to the workbook instance.
    :param index: Worksheet index.
    :param newname: New name for the worksheet.

.. c:function:: int wb_get_active_sheet(WorkbookHandle book)

    Get the index of the active worksheet.

    :param book: Handle to the workbook instance.
    :return: Index of active worksheet.

.. c:function:: int wb_set_active_sheet(WorkbookHandle book, int tab)

    Set the active worksheet.

    :param book: Handle to the workbook instance.
    :param tab: Worksheet index to activate.
    :return: 1 on success, 0 on failure.

Defined Names
-------------

.. c:function:: int wb_set_defined_name(WorkbookHandle book, const char* name, const char* expr, const char* local_name)

    Set a defined name in the workbook.

    :param book: Handle to the workbook instance.
    :param name: Name to define.
    :param expr: Formula expression.
    :param local_name: Local sheet name (optional).
    :return: 1 on success, 0 on failure.

.. c:function:: int defined_name_num(WorkbookHandle book)

    Get number of defined names in the workbook.

    :param book: Handle to the workbook instance.
    :returns: Number of defined names.

.. c:function:: const char* ws_get_defined_name(WorkbookHandle book, int index, int* is_local = 0)

    Get the defined name.

    :param book: Handle to the workbook instance.
    :param index: Index of defined names.
    :param is_local: Is it a locally defined name.
    :returns: Defined name.

.. c:function:: const char* ws_get_local_name(WorkbookHandle book, int index)

    Retrieve the worksheet name to which the defined name belongs.

    :param book: Handle to the workbook instance.
    :param index: Index of defined names.
    :returns: Worksheet name.

.. c:function:: const char* ws_get_defined_name_expr(WorkbookHandle book, int index)

    Get the expression for a defined name.

    :param book: Handle to the workbook instance.
    :param index: Index of defined names.
    :returns: Expression string.

.. c:function:: void ws_delete_defined_name(WorkbookHandle book, int index)

    Delete a defined name.

    :param book: Handle to the workbook instance.
    :param index: Index of defined names.

Style Management
----------------

.. c:function:: StyleHandle wb_get_named_style(WorkbookHandle book, const char* name)

    Get a named style from the workbook.

    :param book: Handle to the workbook instance.
    :param name: Style name(For the name of the built-in style, please refer to :ref:`Built_in_cell_styles`).
    :return: Handle to the style.

.. c:function:: StyleHandle wb_add_custom_style(WorkbookHandle book, const char* name, StyleHandle style)

    Add a custom named style to the workbook.

    :param book: Handle to the workbook instance.
    :param name: Name for the custom style.
    :param style: Style handle to add.
    :return: Handle to the added style.

.. c:function:: int wb_modify_named_style(WorkbookHandle book, const char* name, StyleHandle style)

    Modify an existing named style.

    :param book: Handle to the workbook instance.
    :param name: Name of the style to modify(For the name of the built-in style, please refer to :ref:`Built_in_cell_styles`).
    :param style: New style properties.
    :return: 1 on success, 0 on failure.

.. c:function:: StyleHandle wb_make_normal_style(WorkbookHandle book)

    Create a normal style for the workbook.

    :param book: Handle to the workbook instance.
    :return: Handle to the created normal style.

Rich Text
---------

.. c:function:: RichtextHandle wb_make_richtext(WorkbookHandle book)

    Create a rich text object.

    :param book: Handle to the workbook instance.
    :return: Handle to the created rich text object.

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

See :ref:`enum-api` for related enumerations
used by these functions.
