句柄类型参考 — oosxl 0.1.0 文档

# 句柄类型参考

## 概述

本头文件定义了 oosxl 库中使用的不透明句柄类型。这些句柄提供对内部 C++ 对象的类型安全引用，同时保持清晰的 C 接口。

## 句柄类型

type DocumentHandle

  表示 Excel 文档的不透明句柄。

  此句柄由文档创建和加载函数返回，并作为所有文档操作的根对象。

  使用示例:

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

type WorkbookHandle

  表示 Excel 工作簿的不透明句柄。

  工作簿包含一个或多个工作表，并管理工作簿级别的设置，如计算模式和日期系统。

  使用示例:

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

type WorksheetHandle

  表示 Excel 工作表的不透明句柄。

  工作表包含实际的单元格数据、格式化和工作表特定设置。

  使用示例:

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

type StyleHandle

  表示单元格样式的不透明句柄。

  样式控制单元格的视觉外观，包括字体、颜色、边框、对齐方式和数字格式。

  使用示例:

      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

  表示富文本内容的不透明句柄。

  富文本允许在单个单元格内使用多种格式化样式，实现复杂的文本呈现。

  使用示例:

      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

  表示 Excel 表格(列表对象)的不透明句柄。

  表格提供结构化数据管理，具有内置的筛选、排序和自动格式化功能。

  使用示例:

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

## 内存管理

DocumentHandle 必须正确管理以避免内存泄漏：

- 创建: DocumentHandle 由 doc_create() 或 doc_load() 函数创建

- 使用: DocumentHandle 可以在应用程序生命周期内使用

- 销毁: DocumentHandle 必须使用相应的释放函数释放

正确的清理顺序:

    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

## 句柄生命周期

- 文档句柄拥有其包含的工作簿、工作表和其他对象

- 释放文档句柄会自动释放所有子对象

- 样式和富文本句柄如果是独立的，建议显式释放

- 尝试使用已释放的句柄会导致未定义行为

## 空句柄

NULL 句柄值表示:

- 创建失败(内存不足、无效参数)

- 对象未找到(无效索引、缺少名称)

- 已释放的对象

始终检查 NULL 句柄：

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

## 类型安全

句柄系统提供编译时类型安全：

- 每种句柄类型都是不同的，不能意外互换

- 编译器会捕获类型不匹配

- 不透明结构防止直接访问内部实现

## 相关函数

参见与每种句柄类型对应的 API 参考:

- Document API

- Workbook API

- Worksheet API

- Style API

- Rich Text API

- Table Definition API

Styled using the Piccolo Theme