目录

# LibreOffice Calc 中用于编程的加载宏

下面所述的通过插件扩展 Calc 的方法已过时。但界面仍然有效并且受支持，以确保与现有插件兼容，但如果要编写新插件代码，应使用新的API 函数。

LibreOffice Calc can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the shared library external DLL so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared library DLL. To be recognized by LibreOffice, the shared library DLL must have certain properties, as explained in the following. This information allows you to program your own Add-In for Function Wizard of LibreOffice Calc.

## 加载宏概念

每个加载宏库中都提供了多个函数。有些函数用于管理目的。您可以任意选择自己的函数名称。但必须符合参数传递的相关规则。不同的平台采用的命名规则或调用规则各不相同。

### Functions of Shared Library AddIn DLL

至少必须存在管理函数 GetFunctionCount 和 GetFunctionData。使用这些函数，可以确定函数以及参数类型和返回值。对于返回值，支持双精度和字符串类型。对于参数，也支持其他的单元格区域双精度数组、字符串数组和单元格数组。

参数通过引用传递。这样基本上就可以更改一个值。然而 LibreOffice Calc 却不支持这一点，因为这在一个工作表内部是没有意义的。

程序库可以在运行时重新装入，并通过管理函数分析其内容。对每个函数来说，都含有关于参数的数目和类型、内部和外部函数名称以及管理编号的信息。

函数被同步调出并立即返回结果。虽然还有实时函数 (异步函数)，但是由于它们的复杂性，在此不再作进一步的说明。

## 有关界面的常规信息

附加在 LibreOffice Calc 中的加载宏函数的参数数量最多为 16: 包括一个返回值和最多 15 个输入的函数参数。

数据类型按如下方法定义:

「数据类型」 | 「定义」
--- | ---
CALLTYPE | 在 Windows 系统下: FAR PASCAL (_far _pascal) 其他: 默认 (操作系统指定默认)
USHORT | 2 字节无符号整数
DOUBLE | 8 字节平台附属格式
Paramtype | 特定于平台，比如 int PTR_DOUBLE =0 指针指向一个双精度 PTR_STRING =1 指针指向一个以 0 结束的符号串 PTR_DOUBLE_ARR =2 指针指向一个 Double Array PTR_STRING_ARR =3 指向一个 String Array PTR_CELL_ARR =4 指针指向一个单元格数组 NONE =5

## Shared Library DLL functions

Following you will find a description of those functions, which are called at the Shared Library external DLL.

For all Shared Library DLL functions, the following applies:

void CALLTYPE fn(out, in1, in2, ...)

Output: Resulting value

Input: Any number of types (double&, char*, double*, char**, Cell area), where the Cell area is an array of types double array, string array, or cell array.

### GetFunctionCount()

返回不带有引用参数的管理函数的函数编号。每一个函数有一个 0 到 nCount-1 之间的明确编号。这个编号以后对函数GetFunctionData和GetParameterDescription是必需的。

「语法」

void CALLTYPE GetFunctionCount(USHORT& nCount)

「参数」

USHORT &nCount:

Output: Reference to a variable, which is supposed to contain the number of Add-In functions. For example: If the Add-In provides 5 functions for LibreOffice Calc, then nCount=5.

### GetFunctionData()

确定某个加载宏函数的所有重要信息。

「语法」

void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)

「参数」

USHORT& nNo:

Input: Function number between 0 and nCount-1, inclusively.

char* pFuncName:

Output: Function name as seen by the programmer, as it is named in the Shared Library DLL. This name does not determine the name used in the Function Wizard.

USHORT& nParamCount:

Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.

Paramtype* peType:

Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.

char* pInternalName:

Output: Function name as seen by the user, as it appears in the Function Wizard. May contain umlauts.

参数 pFuncName 和 pInternalName 是字符数组，在 LibreOffice Calc 中最多为 256 个。

### GetParameterDescription()

提供加载宏函数及其参数的简短说明。此函数可用于在「函数向导」中显示某个函数及其参数说明。

「语法」

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

「参数」

USHORT& nNo:

Input: Number of the function in the library; between 0 and nCount-1.

USHORT& nParam:

Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.

char* pName:

Output: Takes up the parameter name or type, for example, the word "Number" or "String" or "Date", and so on. Implemented in LibreOffice Calc as char[256].

char* pDesc:

Output: Takes up the description of the parameter, for example, "Value, at which the universe is to be calculated." Implemented in LibreOffice Calc as char[256].

pName 和 pDesc 都是 char 数组；在 LibreOffice Calc 中执行，大小为 256。请注意:「函数向导」中的可用空间有限，256 个字符不能全部用完。

## 单元格区域

下面的工作表说明了一个外部程序模块必须供哪些数据结构使用，以便传递单元格。LibreOffice Calc 根据数据类型区分 3 个不同的数组。

### Double Array

您可将带数字/双字节类型数值的单元格区域作为参数来传递。Double Array(双精度数组)在 LibreOffice Calc 中用下列方法定义:

Offset | Name | Description
--- | --- | ---
0 | Col1 | 单元格区域左上角的列号。计数从 0 开始。
2 | Row1 | 单元格区域左上角的行号，从 0 开始计数。
4 | Tab1 | 单元格区域左上角的表格号，从 0 开始计数。
6 | Col2 | 单元格区域右下角的列号。从 0 开始计数。
8 | Row2 | 单元格区右下角的行号; 从 0 开始计数。
10 | Tab2 | 单元格区右下角的表格编号; 从 0 开始计数。
12 | Count | 下接的单元数目。空单元格不予计数和传递。
14 | Col | 元素的列号。从 0 开始计数。
16 | 行 | 元素的行号，从 0 开始计数。
18 | Tab | 元素的表格号，从 0 开始计数。
20 | Error | 错误编号，其中 0 值为「无错误」。如果元素来自于一个公式单元格，则错误值通过公式来确定。
22 | Value | 双精度/浮点类型 8 字节 IEEE 变量
30 | ... | 下一个元素

### String Array

包含文本数据类型值的单元格区域，被当作字符串数组传递。字符串数组在 LibreOffice Calc 中定义如下:

Offset | Name | Description
--- | --- | ---
0 | Col1 | 单元格区域左上角的列号。计数从 0 开始。
2 | Row1 | 单元格区域左上角的行号，从 0 开始计数。
4 | Tab1 | 单元格区域左上角的表格号，从 0 开始计数。
6 | Col2 | 单元格区域右下角的列号。从 0 开始计数。
8 | Row2 | 单元格区右下角的行号; 从 0 开始计数。
10 | Tab2 | 单元格区右下角的表格编号; 从 0 开始计数。
12 | Count | 下接的单元数目。空单元格不予计数和传递。
14 | Col | 元素的列号。从 0 开始计数。
16 | 行 | 元素的行号，从 0 开始计数。
18 | Tab | 元素的表格号，从 0 开始计数。
20 | Error | 错误编号，其中 0 值为「无错误」。如果元素来自于一个公式单元格，则错误值通过公式来确定。
22 | Len | 下列字符串的长度，包括结尾的 0 字节。如果该长度包括结尾的 0 字节给出一个奇数值，则给该字符串增加一个第二个 0 字节，以便取得一个偶数值。这样，Len 使用((StrLen+2)&~1)来计算。
24 | String | 字符串带结尾的字节 0
24+Len | ... | 下一个元素

### Cell Array

单元格数组用于调用含有文字与数字的单元格区域。在 LibreOffice Calc 中，单元格数组定义如下:

Offset | Name | Description
--- | --- | ---
0 | Col1 | 单元格区域左上角的列号。计数从 0 开始。
2 | Row1 | 单元格区域左上角的行号，从 0 开始计数。
4 | Tab1 | 单元格区域左上角的表格号，从 0 开始计数。
6 | Col2 | 单元格区域右下角的列号。从 0 开始计数。
8 | Row2 | 单元格区右下角的行号; 从 0 开始计数。
10 | Tab2 | 单元格区右下角的表格编号; 从 0 开始计数。
12 | Count | 下接的单元数目。空单元格不予计数和传递。
14 | Col | 元素的列号。从 0 开始计数。
16 | 行 | 元素的行号，从 0 开始计数。
18 | Tab | 元素的表格号，从 0 开始计数。
20 | Error | 错误编号，其中 0 值为「无错误」。如果元素来自于一个公式单元格，则错误值通过公式来确定。
22 | Type | 单元格内容的类型，0 == 双字节，1 == 字符串
24 | Value or Len | 如果 type == 0: 双字节/浮点类型 8 字节 IEEE 变量 如果 Type == 1: 下列字符串的长度，包括终止的零字符。如果这个长度包括终止的零字符产生一个奇数数值，则为了得到一个偶数数值，应给此字符串新增第二个空字符。因此 Len 通过((StrLen+2)&~1)计算得出。
26 if Type==1 | String | 如果 Type == 1: 字符行带有终止的零字节
32 or 26+Len | ... | 下一个元素