LibreOffice Calc 中程式設計的 Add-In
依下列說明的 Add-In 延伸 Calc 的方法已過時。介面仍有效且支援,請確定與現有的 Add-In 相容,但是為程式設計新的 Add-In 您應該使用新 API 函式。
Add-In 是可以擴充 LibreOffice Calc的外部程式設計模塊,這些模塊提供一些附加函式,以供處理試算表時使用。這些列在 [函式精靈] 的 Add-In 分類中。如果您要自行編寫 Add-In,請瞭解其中哪些函式必須由公用程式庫外部 DLL 匯出,以便成功地附加 Add-In。
LibreOffice 會在配置時所定義的 Add-in 資料夾中搜尋適合的共用程式庫 DLL。共用程式庫 DLL 必須具有特定特性,LibreOffice 才可加以辨識,如下所示。此資訊可讓您為 LibreOffice Calc 的「函式精靈」編寫自己的 Add-In 程式。
Add-In 概念
每個 Add-In 程式庫都提供了數個函式。有些函式用於管理。您幾乎可以任意命名自己的函式,但必須符合參數傳遞的相關規則。不同平台採用的命名規約、呼叫規約各不相同。
公用程式庫 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 |
公用程式庫 DLL 函式
您將在下面找到那些在 公用程式庫 外部 DLL 呼叫的函式描述。
對於所有 公用程式庫 DLL 函式,下列內容適用:
void CALLTYPE fn(out, in1, in2, ...)
輸出值:結果值
輸入:任意類型的數字 (double&、char*、double*、char**、儲存格範圍),其中儲存格範圍可以是 double、string 或儲存格類型的陣列。
GetFunctionCount()
傳回參照參數中不含管理函式的函式數目。每一個函式都含有一個介於 0 和 nCount-1 之間的唯一編號。GetFunctionData 和 GetParameterDescription 函式之後會需要這個編號。
語法
void CALLTYPE GetFunctionCount(USHORT& nCount)
參數
USHORT &nCount:
輸出值:應包含 Add-In 函式數目的變量參照。例如,若 LibreOffice Calc 可使用 Add-In 所提供的 5 個函式,那麼 nCount=5。
GetFunctionData()
確定有關某個 Add-In 函式的所有重要資訊。
語法
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
參數
USHORT& nNo:
輸入值:包含 0 到 nCount-1 之間的函式編號。
char* pFuncName:
輸出:程式設計師看到的函式,也就是公用程式庫 DLL 中指定的名稱。此名稱不能決定 [函式精靈] 中使用的名稱。
USHORT& nParamCount:
輸出值:Add-In 函式的參數數目。這個數目必需大於 0,因為會一直有一個結果值,最大值為 16。
Paramtype* peType:
輸出值:Array 上含有正好 16 個 Paramtype 類型變量的指標。第一個 nParamCount 條目會以對應的參數類型填入。
char* pInternalName:
匯出:函式名稱如使用者所見,也如同 [函式精靈] 中顯示。可以包含變元音。
參數 pFuncName 和 pInternalName 是在 LibreOffice Calc 中以 256 大小執行的 char Array。
GetParameterDescription()
提供 Add-In 函式及其參數的簡短描述。此函式作為一個選項,可用於顯示在 [函式精靈] 中的函式與參數描述。
語法
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
參數
USHORT& nNo:
輸入值:在程式庫內介於 0 和 nCount-1 之間的函式編號。
USHORT& nParam:
輸入值:指定要提供哪些參數的描述,參數從 1 開始。若 nParam 為 0,則應以 pDesc 產生函式描述,pName 在這種情況下是沒有意義的。
char* pName:
輸出值:採用參數的名稱或是類型,例如,「數字」或「字串」或「日期」等。在 LibreOffice Calc 中當作 char[256] 執行。
char* pDesc:
輸出值:採用參數的描述,例如,「宇宙應計算出的數值」。在 LibreOffice Calc 中當作 char[256] 執行。
pName 與 pDesc 是 char 陣列;LibreOffice Calc 中實作的大小是 256 個字元。請注意 [函式精靈] 中的可用空間有所限制,無法完全使用到 256 個字元。
儲存格區域
下列表格說明了,外部程式模塊必須提供哪些資料結構,以作為移轉儲存格參照使用。LibreOffice Calc 會根據介於三種不同 Array 之間的資料類型做區分。
Double Array
您可以將含「數字」/「DOUBLE」類型數值的儲存格區域作為參數移轉。Double Array 在 LibreOffice Calc 中定義如下:
偏移 |
名稱 |
描述 |
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 定義如下:
偏移 |
名稱 |
描述 |
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 中,儲存格陣列的定義如下:
偏移 |
名稱 |
描述 |
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 |
... |
下一個項目 |