Add-in zu LibreOffice Calc programmieren

Warnsymbol

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 Plug-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 Plug-in. Wenn Sie selbst Plug-ins programmieren möchten, erfahren Sie hier, welche Funktionen fĂŒr eine erfolgreiche Implementierung von Plug-ins aus der exportiert werden mĂŒssen.

LibreOffice durchsucht den in der Konfiguration festgelegten Plug-in-Ordner nach einer passenden . Um von LibreOffice erkannt zu werden, muss die bestimmte Eigenschaften aufweisen, wie im Folgenden erklĂ€rt wird. Mit diesen Informationen können Sie Ihr eigenes Plug-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

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


Funktionen der

Im folgenden finden Sie eine Beschreibung der Funktionen, die von der aufgerufen werden.

FĂŒr alle Funktionen der 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 Plug-in-Funktionen enthalten soll. Stellt das Plug-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 darstellt. Dieser Name legt nicht den Namen fest, der im Funktions-Assistenten verwendet wird.

USHORT& nParamCount:

Output: Anzahl der Parameter der Plug-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 entsprechenden 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", "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


Bitte unterstĂŒtzen Sie uns!