.. _handle-api:

Handle Types Reference
======================

Overview
--------

This header file defines the opaque handle types used
throughout the oosxl library. These handles provide
type-safe references to internal C++ objects
while maintaining a clean C interface.

Handle Types
------------

.. c:type:: DocumentHandle

    Opaque handle representing an Excel document.

    This handle is returned by document creation and loading functions, and serves as the root object for all document operations.

    **Usage Example:**

    .. code-block:: c

        DocumentHandle doc = doc_create();
        // ... work with document
        doc_release(doc);

.. c:type:: WorkbookHandle

    Opaque handle representing an Excel workbook.

    A workbook contains one or more worksheets and manages workbook-level settings like calculation mode and date system.

    **Usage Example:**

    .. code-block:: c

        DocumentHandle doc = doc_create();
        WorkbookHandle workbook = doc_get_workbook(doc);
        // ... work with workbook
        doc_release(doc);

.. c:type:: WorksheetHandle

    Opaque handle representing an Excel worksheet.

    Worksheets contain the actual cell data, formatting, and worksheet-specific settings.

    **Usage Example:**

    .. code-block:: c

        WorksheetHandle sheet = wb_add_worksheet(workbook, "Sheet1");
        ws_set_text(sheet, 0, 0, "Hello World");
        // ... work with worksheet

.. c:type:: StyleHandle

    Opaque handle representing a cell formatting style.

    Styles control the visual appearance of cells including fonts, colors, borders, alignment, and number formatting.

    **Usage Example:**

    .. code-block:: c

        StyleHandle style = wb_make_normal_style(workbook);
        style_set_font_color(style, 0xFF0000); // Red text
        style_set_bold(style, 1); // Bold font
        ws_set_cell_style(sheet, 0, 0, style);
        style_release(style);

.. c:type:: RichtextHandle

    Opaque handle representing rich text content.

    Rich text allows multiple formatting styles within a single cell, enabling complex text presentations.

    **Usage Example:**

    .. code-block:: c

        RichtextHandle rt = wb_make_richtext(workbook);
        rt_append(rt, "Normal text", normal_style);
        rt_append(rt, "Bold text", bold_style);
        ws_set_richtext(sheet, 0, 0, rt);
        rt_release(rt);

.. c:type:: TabledefHandle

    Opaque handle representing an Excel table (List Object).

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

    **Usage Example:**

    .. code-block:: c

        TabledefHandle table = ws_add_tabledef(sheet, "Table1", 0, 0, 10, 5);
        td_set_display_name(table, "Sales Data");
        // ... configure table

Memory Management
-----------------

Documenthandle must be properly managed to avoid memory leaks:

- **Creation**: DocumentHandle are created by doc_create()
  or doc_load() functions
- **Usage**: DocumentHandle can be used throughout
  the application lifetime
- **Destruction**: DocumentHandle must be released
  using doc_release() functions

**Proper cleanup sequence:**

.. code-block:: c

    DocumentHandle doc = doc_create();
    WorkbookHandle workbook = doc_get_workbook(doc);
    WorksheetHandle sheet = wb_add_worksheet(workbook, "Sheet1");
    StyleHandle style = wb_make_normal_style(workbook);
    RichtextHandle rt = wb_make_richtext(workbook);

    // ... use objects

    rt_release(rt);
    style_release(style);

    // Release the DocumentHandle
    doc_release(doc); // Releases workbook and worksheet automatically

Handle Lifetime
---------------

- Document handles own their contained workbooks, worksheets, and other objects
- Releasing a document handle automatically releases all child objects
- The style and rich text handle created by the wb_make_normal_style()
  and wb_make_richtext() functions are independent and should be explicitly
  released when no longer in use to save memory
- Attempting to use a released handle results in undefined behavior

Null Handles
------------

A NULL handle value indicates:

- Creation failure (insufficient memory, invalid parameters)
- Object not found (invalid index, missing name)
- Already released object

**Always check for NULL handles:**

.. code-block:: c

    DocumentHandle doc = doc_load("nonexistent.xlsx");
    if (doc == NULL) {
        printf("Failed to load document\n");
        return;
    }

Type Safety
-----------

The handle system provides compile-time type safety:

- Each handle type is distinct and cannot be accidentally interchanged
- The compiler will catch type mismatches
- Opaque structure prevents direct access to internal implementation

Related Functions
-----------------

See the corresponding API references for functions
that work with each handle type:

- :ref:`Document API <document-c-api>`
- :ref:`Workbook API <workbook-c-api>`
- :ref:`Worksheet API <worksheet-c-api>`
- :ref:`Style API <style-api>`
- :ref:`Rich Text API <richtext-api>`
- :ref:`Table Definition API <tabledef-api>`
