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 kann um Add-ins, externe Programmiermodule mit zusätzlichen Funktionen für die Arbeit mit Tabellendokumenten, erweitert werden. Diese Funktionen finden Sie im Funktions-Assistenten unter der Kategorie Add-in. Wenn Sie selbst Add-ins programmieren möchten, erfahren Sie hier, welche Funktionen für eine erfolgreiche Implementierung von Add-ins aus der Shared Library (gemeinsamen Bibliothek)externen DLL exportiert werden müssen.
LibreOffice durchsucht den in der Konfiguration festgelegten Add-in-Ordner nach einer passenden shared library (gemeinsame Bibliothek) DLL. Um von LibreOffice erkannt zu werden, muss die shared libraryDLL bestimmte Eigenschaften aufweisen, wie im Folgenden erklärt wird. Mit diesen Informationen können Sie Ihr eigenes Add-in für den Funktions-Assistenten von LibreOffice Calc programmieren.
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.
Funktionen der Shared LibraryAdd-in-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-Funktionen
Im folgenden finden Sie eine Beschreibung der Funktionen, die an der Shared Libraryexternen DLL aufgerufen werden.
Für alle Shared LibraryDLL-Funktionen gilt:
void CALLTYPE fn(out, in1, in2, ...)
Output: Ergebniswert
Eingabe: Eine beliebige Anzahl von Typen (double&, char*, double*, char**, Zellbereich), wobei Zellbereich ein Array vom Typ Double Array, String Array oder Cell Array ist.
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: Bezug auf eine Variable, die die Anzahl der Add-in-Funktionen enthalten soll. Stellt das Add-in beispielsweise 5 Funktionen für LibreOffice Calc zur Verfügung, so ist 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: Funktionsnummer zwischen 0 und nCount-1 einschließlich.
char* pFuncName:
Output: Der bei der Programmierung verwendete Funktionsname, der die Funktion in der Shared LibraryDLL darstellt. Dieser Name legt nicht den Namen fest, der im Funktions-Assistenten verwendet wird.
USHORT& nParamCount:
Output: Anzahl der Parameter der Add-in-Funktion. Diese Anzahl muss größer 0 sein, da es immer einen Ergebniswert gibt, der Maximalwert ist 16.
Paramtype* peType:
Output: Zeiger auf ein Array mit genau 16 Variablen vom Typ Paramtype. Die ersten nParamCount Einträge werden mit dem Typ des entsprechenen Parameters gefüllt.
char* pInternalName:
Output: Der für den Benutzer sichtbare Funktionsname, wie er im Funktions-Assistenten erscheint. Umlaute sind hier zulässig.
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: Nummer der Funktion innerhalb der Bibliothek zwischen 0 und nCount-1.
USHORT& nParam:
Input: Gibt an, für welchen Parameter die Beschreibung geliefert werden soll, Parameter beginnen bei 1. Ist nParam 0, soll die Beschreibung der Funktion an sich in pDesc geliefert werden, pName ist in diesem Fall bedeutungslos.
char* pName:
Output: Nimmt den Namen oder die Art des Parameters auf, beispielsweise das Wort "Zahl" oder "Zeichenkette" oder "Datum" und so weiter. In LibreOffice Calc implementiert als char[256].
char* pDesc:
Output: Nimmt die Beschreibung des Parameters auf, beispielsweise "Wert, zu dem das Universum berechnet werden soll". In LibreOffice Calc implementiert als 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 |
Beschreibung |
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 |
Beschreibung |
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 |
Beschreibung |
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 |