LibreOffice Calc 中程式設計的 Add-In

warning

依下列說明的 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 so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable . To be recognized by LibreOffice, the 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

無論在何種情況下,管理函式 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


functions

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

For all 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 . 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

...

下一個項目


Please support us!