Inhalte
Index 🔎︎

# Add-in zu LibreOffice Calc programmieren

Die im Folgenden beschriebene Methode, Calc durch Add-ins zu erweitern, ist veraltet. Die Schnittstellen sind jedoch noch gültig und werden weiterhin unterstützt, um die Kompatibilität zu existierenden Add-ins sicherzustellen, für die Programmierung neuer Add-ins sollten Sie jedoch die neuen API Funktionen nutzen.

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 libraryexternal DLL so that the Add-In can be successfully attached.

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

## Das Add-in-Konzept

Jede Add-in-Bibliothek liefert bestimmte Funktionen. Einige Funktionen dienen zu Verwaltungszwecken. Sie können eigene Funktionen nahezu beliebig benennen. Es müssen jedoch auch bestimmte Regeln der Parameterübergabe befolgt werden. Für die verschiedenen Plattformen gelten leicht unterschiedliche Benennungs- und Aufrufkonventionen.

### Functions of Shared LibraryAddIn DLL

Es müssen mindestens die Verwaltungsfunktionen GetFunctionCount und GetFunctionData vorhanden sein. Mit ihnen lassen sich sowohl die Funktionen als auch Parametertypen und Rückgabewerte ermitteln. Für Rückgabewerte werden die Datentypen Double und String unterstützt. Für Parameter sind zusätzlich die Zellbereiche Double Array, String Array und Cell Array möglich.

Parameter werden als Bezüge übergeben. Daher ist grundsätzlich eine Veränderung der Werte möglich. Dieses wird von LibreOffice Calc jedoch nicht unterstützt, da es innerhalb eines Tabellendokuments nicht sinnvoll ist.

Bibliotheken können zur Laufzeit nachgeladen und ihr Inhalt mithilfe der Verwaltungsfunktionen analysiert werden. Für jede Funktion stehen Informationen über Anzahl und Typ der Parameter sowie der interne und externe Funktionsname und eine Verwaltungsnummer zur Verfügung.

Die Funktionen werden synchron aufgerufen und liefern ihr Ergebnis unverzüglich zurück. Realtimefunktionen (asynchrone Funktionen) sind zwar auch möglich, können aufgrund ihrer Komplexität hier aber nicht weiter erläutert werden.

## Allgemeines zum Interface

Eine in LibreOffice Calc integrierte Add-in-Funktion kann maximal 16 Parameter umfassen: einen Ergebniswert und bis zu 15 Eingabeparameter.

Die Datentypen sind folgendermaßen definiert:

Datentypen | Definition
CALLTYPE | unter Windows: FAR PASCAL (_far _pascal) sonst: default (betriebssystemspezifischer Standard)
USHORT | 2 Byte unsigned Integer
DOUBLE | 8 Byte plattformabhängiges Format
Paramtype | plattformabhängig wie int PTR_DOUBLE =0 Zeiger auf einen double PTR_STRING =1 Zeiger auf eine Null-terminierte Zeichenkette PTR_DOUBLE_ARR =2 Zeiger auf ein Double Array PTR_STRING_ARR =3 Zeiger auf ein String Array PTR_CELL_ARR =4 Zeiger auf ein Cell Array NONE =5

## Shared LibraryDLL functions

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

For all Shared LibraryDLL 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()

Ergibt die Anzahl der Funktionen ohne die Verwaltungsfunktionen im Referenzparameter. Jede Funktion hat eine eindeutige Nummer zwischen 0 und nCount-1. Diese Nummer wird später für die Funktionen GetFunctionData und GetParameterDescription benötigt.

Syntax

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parameter

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()

Ermittelt alle wichtigen Informationen über eine Add-in-Funktion.

Syntax

void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)

Parameter

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 LibraryDLL. 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.

Die Parameter pFuncName und pInternalName sind char Arrays, die in LibreOffice Calc mit der Größe 256 implementiert sind.

### GetParameterDescription()

Liefert eine kurze Beschreibung der Add-in-Funktion und ihrer Parameter. Diese Funktion kann optional eingesetzt werden, um im Funktions-Assistenten Beschreibungen der Funktionen und ihrer Parameter anzuzeigen.

Syntax

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Parameter

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 und pDesc sind in LibreOffice Calc implementierte Char-Arrays der Größe 256. Beachten Sie bitte, dass der im Funktions-Assistenten verfügbare Platz beschränkt ist und die 256 Zeichen nicht voll genutzt werden können.

## Zellbereiche

Folgende Tabellen geben Auskunft darüber, welche Datenstrukturen ein externes Programm-Modul zur Verfügung stellen muss, um Zellbereiche zu übergeben. LibreOffice Calc unterscheidet je nach Datentyp zwischen drei verschiedenen Arrays.

### Double Array

Als Parameter können Sie einen Zellbereich mit Werten vom Typ Zahl/Double übergeben. Ein Double Array ist in LibreOffice Calc folgendermaßen definiert:

Offset | Name | Description
0 | Col1 | Spaltennummer der linken oberen Ecke des Zellbereichs. Die Zählung beginnt bei 0.
2 | Row1 | Zeilennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
4 | Tab1 | Tabellennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
6 | Col2 | Spaltennummer der rechten unteren Ecke des Zellbereichs. Die Zählung beginnt bei 0.
8 | Row2 | Zeilennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
10 | Tab2 | Tabellennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
12 | Count | Anzahl der folgenden Elemente. Leere Zellen werden nicht mitgezählt und nicht übergeben.
14 | Col | Spaltennummer des Elements. Die Zählung beginnt bei 0.
16 | Zeile | Zeilennummer des Elements, ab 0 gezählt.
18 | Tab | Tabellennummer des Elements, ab 0 gezählt.
20 | Error | Fehlernummer, wobei der Wert 0 für "keinen Fehler" belegt ist. Wenn das Element aus einer Formel-Zelle stammt, wird der Fehlerwert durch die Formel bestimmt.
22 | Value | 8 Byte IEEE-Variable vom Typ Double/Fließkomma
30 | ... | Nächstes Element

### String Array

Ein Zellbereich, der Werte vom Datentyp Text enthält, wird als String Array übergeben. Ein String Array ist in LibreOffice Calc folgendermaßen definiert:

Offset | Name | Description
0 | Col1 | Spaltennummer der linken oberen Ecke des Zellbereichs. Die Zählung beginnt bei 0.
2 | Row1 | Zeilennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
4 | Tab1 | Tabellennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
6 | Col2 | Spaltennummer der rechten unteren Ecke des Zellbereichs. Die Zählung beginnt bei 0.
8 | Row2 | Zeilennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
10 | Tab2 | Tabellennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
12 | Count | Anzahl der folgenden Elemente. Leere Zellen werden nicht mitgezählt und nicht übergeben.
14 | Col | Spaltennummer des Elements. Die Zählung beginnt bei 0.
16 | Zeile | Zeilennummer des Elements, ab 0 gezählt.
18 | Tab | Tabellennummer des Elements, ab 0 gezählt.
20 | Error | Fehlernummer, wobei der Wert 0 für "keinen Fehler" belegt ist. Wenn das Element aus einer Formel-Zelle stammt, wird der Fehlerwert durch die Formel bestimmt.
22 | Len | Länge des folgenden Strings, inklusive abschließendem Null-Byte. Wenn die Länge inklusive abschließendem Null-Byte einen ungeraden Wert ergibt, wird dem String ein zweites Null-Byte hinzugefügt, um einen geraden Wert zu erhalten. Daher wird Len berechnet mit ((StrLen+2)&~1).
24 | String | Zeichenkette mit abschließendem Null-Byte
24+Len | ... | Nächstes Element

### Cell Array

Cell Arrays dienen zum Aufrufen von Zellbereichen, die sowohl Text als auch Zahlen enthalten. Ein Cell Array ist in LibreOffice Calc wie folgt definiert:

Offset | Name | Description
0 | Col1 | Spaltennummer der linken oberen Ecke des Zellbereichs. Die Zählung beginnt bei 0.
2 | Row1 | Zeilennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
4 | Tab1 | Tabellennummer der linken oberen Ecke des Zellbereichs, ab 0 gezählt.
6 | Col2 | Spaltennummer der rechten unteren Ecke des Zellbereichs. Die Zählung beginnt bei 0.
8 | Row2 | Zeilennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
10 | Tab2 | Tabellennummer der rechten unteren Ecke des Zellbereichs, ab 0 gezählt.
12 | Count | Anzahl der folgenden Elemente. Leere Zellen werden nicht mitgezählt und nicht übergeben.
14 | Col | Spaltennummer des Elements. Die Zählung beginnt bei 0.
16 | Zeile | Zeilennummer des Elements, ab 0 gezählt.
18 | Tab | Tabellennummer des Elements, ab 0 gezählt.
20 | Error | Fehlernummer, wobei der Wert 0 für "keinen Fehler" belegt ist. Wenn das Element aus einer Formel-Zelle stammt, wird der Fehlerwert durch die Formel bestimmt.
22 | Type | Typ des Zellinhalts, 0 == Double, 1 == String
24 | Value or Len | Wenn Type == 0: 8 Byte IEEE-Variable vom Typ Double/Fließkomma Wenn Type == 1: Länge des folgenden Strings, inklusive abschließendem Null-Byte. Wenn die Länge inklusive abschließendem Null-Byte einen ungeraden Wert ergibt, wird dem String ein zweites Null-Byte hinzugefügt, um einen geraden Wert zu erhalten. Daher wird Len berechnet mit ((StrLen+2)&~1).
26 if Type==1 | String | Wenn Type == 1: Zeichenkette mit abschließendem Null-Byte
32 or 26+Len | ... | Nächstes Element