LibreOffice Calc 中用于编程的加载宏
下面所述的通过插件扩展 Calc 的方法已过时。但界面仍然有效并且受支持,以确保与现有插件兼容,但如果要编写新插件代码,应使用新的API 函数。
LibreOffice Calc 可以使用加载宏进行扩展。加载宏是一个外部编程模块,它可以提供一些对工作表进行处理的附加函数。这些函数列在插件类别的函数向导中。如果要自己编写插件程序,请了解其中哪些函数必须由共享库外部 DLL 输出,以便成功地附加加载宏。
LibreOffice 为定义在配置中的附加文件夹查找合适的共享库DLL。要使共享库DLL能被 LibreOffice 识别,它必须具有下述的某些属性。可使用这些信息为 LibreOffice Calc 的函数向导编写自己的附加程序。
加载宏概念
每个加载宏库中都提供了多个函数。有些函数用于管理目的。您可以任意选择自己的函数名称。但必须符合参数传递的相关规则。不同的平台采用的命名规则或调用规则各不相同。
共享库加载宏 DLL 的函数
至少必须存在管理函数 GetFunctionCount 和 GetFunctionData。使用这些函数,可以确定函数以及参数类型和返回值。对于返回值,支持双精度和字符串类型。对于参数,也支持其他的单元格区域双精度数组、字符串数组和单元格数组。
参数通过引用传递。这样基本上就可以更改一个值。然而 LibreOffice Calc 却不支持这一点,因为这在一个工作表内部是没有意义的。
程序库可以在运行时重新装入,并通过管理函数分析其内容。对每个函数来说,都含有关于参数的数目和类型、内部和外部函数名称以及管理编号的信息。
函数被同步调出并立即返回结果。虽然还有实时函数(异步函数),但是由于它们的复杂性,在此不再作进一步的说明。
有关界面的一般信息
附加在 LibreOffice Calc 中的加载宏函数的参数数量最多为 16:包括一个返回值和最多 15 个输入的函数参数。
数据类型按如下方法定义:
数据类型 |
定义 |
CALLTYPE |
在 Windows 系统下:FAR PASCAL (_far _pascal) 其他:默认(操作系统指定默认) |
USHORT |
2 字节无符号整数 |
双精度 |
8 字节平台附属格式 |
参数类型 |
特定于平台,比如 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 |
共享库 DLL 函数
下面是一个共享库外部 DLL 调用的函数的说明。
对于所有共享库 DLL 函数,应用如下:
void CALLTYPE fn(out, in1, in2, ...)
Output: 结果值
输入:double&、char*、double*、char**、单元格区域类型的任意数值,其中,单元格区域可以是 double、string 或单元格类型的数组。
GetFunctionCount()
返回不带有引用参数的管理函数的函数编号。每一个函数有一个 0 到 nCount-1 之间的明确编号。这个编号以后对函数GetFunctionData和GetParameterDescription是必需的。
语法
void CALLTYPE GetFunctionCount(USHORT& nCount)
参数
USHORT &nCount:
Output: 应当包含加载宏函数数目变量的引用。例如加载宏有 5 个函数供 LibreOffice Calc 使用,那么 nCount=5。
GetFunctionData()
确定某个加载宏函数的所有重要信息。
语法
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
参数
USHORT& nNo:
Input: 函数编号包括在 0 到 nCount-1 之间。
char* pFuncName:
输出:程序员看到的函数名称,也就是共享库 DLL 中指定的名称。此名称不确定在函数向导中使用的名称。
USHORT& nParamCount:
Output: Add In 函数的参数数目。这个数目必须大于 0,因为始终有一个结果值,最大值为 16。
Paramtype* peType:
Output: 指针指向一个带有 16 个参数类型变量的数组。第一个 nParamCount 条目填入相关的参数类型。
char* pInternalName:
输出:用户看到的函数名称,也就是函数向导中显示的名称。可以含有变音字符。
参数 pFuncName 和 pInternalName 是字符数组,在 LibreOffice Calc 中最多为 256 个。
GetParameterDescription()
提供加载宏函数及其参数的简短说明。此函数可用于在函数向导中显示某个函数及其参数说明。
语法
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
参数
USHORT& nNo:
Input: 程序库内部的函数号,在 0 到 nCount-1 之间。
USHORT& nParam:
Input: 指定该说明应提供哪些参数,参数从 1 开始。如果 nParam 为 0,则该说明自身要在 pDesc 中提供,此情况下 pName 无意义。
char* pName:
Output: 接受参数的名称或类型,例如单词“数字”、“字串”或“日期”之类,在 LibreOffice Calc 中当作256个字符。
char* pDesc:
Output: 接受对参数的说明,例如"应用于通用计算的数值"。在 LibreOffice Calc 中可用256个字符。
pName 和 pDesc 都是 char 数组;在 LibreOffice Calc 中执行,大小为 256。请注意:函数向导中的可用空间有限,256 个字符不能全部用完。
单元格区域
下面的工作表说明了一个外部程序模块必须供哪些数据结构使用,以便传递单元格。LibreOffice Calc 根据数据类型区分 3 个不同的数组。
Double Array
您可将带数字/双字节类型数值的单元格区域作为参数来传递。Double Array(双精度数组)在 LibreOffice Calc 中用下列方法定义:
Offset |
名称 |
说明 |
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 |
名称 |
说明 |
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 |
名称 |
说明 |
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 |
... |
下一个元素 |