Handle Types Reference — oosxl 0.1.0 documentation

# 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

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:

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

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:

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

type WorksheetHandle

  Opaque handle representing an Excel worksheet.

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

  Usage Example:

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

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:

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

type RichtextHandle

  Opaque handle representing rich text content.

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

  Usage Example:

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

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:

      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:

    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:

    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:

- Document API

- Workbook API

- Worksheet API

- Style API

- Rich Text API

- Table Definition API

Styled using the Piccolo Theme