Contents

# LibreOffice Calc 中程式設計的 Add-In

依下列說明的 Add-In 延伸 Calc 的方法已過時。介面仍有效且支援，請確定與現有的 Add-In 相容，但是為程式設計新的 Add-In 您應該使用新 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.

## Add-In 概念

每個 Add-In 程式庫都提供了數個函式。有些函式用於管理。您幾乎可以任意命名自己的函式，但必須符合參數傳遞的相關規則。不同平台採用的命名規約、呼叫規約各不相同。

### Functions of Shared Library AddIn DLL

無論在何種情況下，管理函式 GetFunctionCount 和 GetFunctionData 必須存在。使用這兩個函式，可以確定函式、參數類型和傳回值。傳回值支援雙精度類型和字串類型。而參數支援雙精度型陣列、字串型陣列和儲存格陣列。

參數則利用參照移轉。因此數值的變更基本上是可行的。但 LibreOffice Calc 並不支援此功能，因為這些在試算表計算上並沒有意義。

執行階段期間可以重新載入程式庫，而且可以透過管理函式分析程式庫的內容。對於每一個函式，都提供了有關參數數目和類型、內部和外部參數名稱以及管理號碼的資訊。

這些函式會同時啟動且立即回傳結果。即時函式 (非同步函式) 雖然可行，但基於它的複雜性，無法在此多作註釋。

## 界面的一般說明

附加至 LibreOffice Calc 的 Add-In 函式中，最大參數數目為 16，即一個傳回值和最多 15 個函式輸入參數。

資料類型定義如下：

資料類型 | 定義
--- | ---
CALLTYPE | Windows 下：FAR PASCAL (_far _pascal) 否則：預設 (作業系統特定標準)
USHORT | 2 位元組不含正負號的整數
DOUBLE | 8 位元組視平台而定的格式
Paramtype | 視平台而定如同整數 PTR_DOUBLE =0 於 double 上的指標 PTR_STRING =1 於零期限字串上的指標 PTR_DOUBLE_ARR =2 於 Double Array 上的指標 PTR_STRING_ARR =3 於 String Array 上的指標 PTR_CELL_ARR =4 於 Cell Array 上的指標 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()

確定有關某個 Add-In 函式的所有重要資訊。

語法

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 大小執行的 char Array。

### GetParameterDescription()

提供 Add-In 函式及其參數的簡短描述。此函式作為一個選項，可用於顯示在 [函式精靈] 中的函式與參數描述。

語法

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 會根據介於三種不同 Array 之間的資料類型做區分。

### Double Array

您可以將含「數字」/「DOUBLE」類型數值的儲存格區域作為參數移轉。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 位元組「Double/小數點」類型的 IEEE 變量
30 | ... | 下一個項目

### String Array

一個包含「文字」資料類型數值的儲存格區域，會作為 String Array 移轉。在 LibreOffice Calc 中，String Array 定義如下：

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 | 下列 String 長度，包含最終的 0 位元組。當包含最終的 0 位元組的長度得出一個非偶數的數值時，則會在這個 String 中會加入第二個 0 位元組，以得到一個偶數。因此會以 ((StrLen+2)&~1) 計算 Len。
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 | 類型 | 儲存格內容的類型，0 == Double，1 == String
24 | Value or Len | 當 Type == 0：「Double/小數點」類型的 8 位元組 IEEE 變量 當 Type == 1：下列 String 的長度，則包含最終的 0 位元組。當包含最終的 0 位元組的長度得出一個非偶數的數值時，則會在這個 String 中會加入第二個 0 位元組，以得到一個偶數。因此會以 ((StrLen+2)&~1) 計算 Len。
26 if Type==1 | String | 當 Type == 1：含最終的 0 位元組的字元順序
32 or 26+Len | ... | 下一個項目