目次

# 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 が存在する必要があります。これらの関数を使用すると、関数、パラメータの種類、および戻り値を判断できます。戻り値には、Double と String を使用できます。パラメーターには、Double と String 以外にも、Double 配列、String 配列、および セル配列 を使用できます。

パラメーターは参照として入力されます。そのため、基本的には値の変更が可能です。しかし、表計算プログラムにおいては適当でないため、LibreOffice Calc では値を変更することはできません。

ライブラリは実行時に読み込むことができます。このとき、管理用の関数を使用すると、ライブラリの内容を解析できます。どの関数でも、パラメーターの数と種類、内部関数名と外部関数名、および管理番号についての情報が使用できます。

関数が同時に呼び出されすぐに結果を返します。リアルタイム関数も可能ですが、複雑なためここでは詳しく説明しません。

## インタフェース全般

LibreOffice Calc に組み込むことができるアドイン関数のパラメーターは最大で 16 個です。そのうちの 1 個は戻り値用で、残りの 15 個は入力用です。

データの種類は次のように定義されています。

データの種類 | 定義
--- | ---
CALLTYPE | Windowsの場合: FARPASCAL(_far_pascal) それ以外の場合: default (各オペレーティングシステムの標準)
USHORT | 2 Byte unsigned Integer
DOUBLE | プラットフォームに応じた８バイトフォーマット
Paramtype | int と同様、プラットフォーム特有 double を指すポインター PTR_DOUBLE =0 ゼロ制限した文字列を指定するポインター PTR_STRING =1 Double 配列を指すポインター PTR_DOUBLE_ARR =2 String 配列を指すポインター PTR_STRING_ARR =3 Cell 配列を指すポインター 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 を実装した char Array です。

### 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 は、データの型によってセル範囲を３種に分類します。

### Double 配列

パラメーターに、数値/Double 型の値を含むセル範囲が指定できます。LibreOffice Calc では、Double 配列は次のように定義されています:

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 | 種類がダブル/浮動小数点の８バイト IEEE 変数
30 | ... | 次の要素

### String 配列

データの型が文字列であるセル範囲は、String 配列として指定されます。LibreOffice Calc では、String 配列を次のように定義しています。

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 | 次の文字列の長さ (最後の０バイトを含む) 。文字列の最後の０バイトを含めた長さが奇数値になった場合は、偶数値になるように０バイトがもう１つ追加されます。そのため、Len は ((StrLen+2)&～1) で計算されます。
24 | String | 最後に０バイトが付いた文字列
24+Len | ... | 次の要素

### セル配列

セル配列を使用すると、テキストと数値を含むセル範囲を呼び出すことができます。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 の場合: ダブル/浮動小数点型の８バイト IEEE 変数 Type ==1 の場合: 次の文字列の長さ (最後の０バイトを含む) 。文字列の最後の０バイトを含めた長さが奇数値になった場合は、偶数値になるように０バイトがもう１つ追加されます。そのため、Len は ((StrLen+2)&～1) で計算されます。
26 if Type==1 | String | Type ==1 の場合: 最後に０バイトが付いた文字列
32 or 26+Len | ... | 次の要素