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