Addin voor programmering in LibreOffice Calc

LibreOffice Calc kan worden uitgebreid met Add-Ins, dit zijn externe programmeermodules die extra functies bieden voor het werken met werkbladen. Deze worden vermeld in de Functie-assistent in de categorie Invoegtoepassing. Als u zelf een Add-In wilt programmeren, kunt u hier leren welke functies moeten worden geëxporteerd door de zodat de Add-In succesvol kan worden toegevoegd.

LibreOffice zoekt in de Add-in-map die in de configuratie is gedefinieerd naar een geschikte . Om herkend te worden door LibreOffice, moet de bepaalde eigenschappen hebben, zoals uitgelegd in het volgende. Met deze informatie kunt u uw eigen Add-In programmeren voor de Functie-assistent of LibreOffice Calc.

Het addin-concept

Elke add-in-bibliotheek biedt verschillende functies. Sommige functies worden voor administratieve doeleinden gebruikt. U kunt voor uw eigen functies vrijwel elke naam kiezen. Ze moeten echter bepaalde regels volgen betreffende het doorgeven van parameters. De exacte naam- en aanroepconventies verschillen per platform.

Functies van de

Op zijn minst moeten de administratieve functies GetFunctionCount en GetFunctionData bestaan. Met behulp hiervan kunnen de functies evenals parametertypen en retourwaarden bepaald worden. Als retourwaarden worden de types Double en String ondersteund. Als parameters worden daarnaast de celbereiken voor Double Array, String Array en Cell Array ondersteund.

Parameters worden met behulp van verwijzingen doorgegeven. Daarom is het in feite mogelijk deze waarden te wijzigen. Dit wordt echter niet ondersteund in LibreOffice Calc omdat het in werkbladen geen zin heeft.

Bibliotheken kunnen opnieuw geladen worden terwijl het programma uitgevoerd wordt en hun inhoud kan door de administratieve functies geanalyseerd worden. Voor elke functie is informatie beschikbaar over aantal en type parameters, interne en externe functienamen, evenals een administratief nummer.

De functies worden synchroon aangeroepen en geven hun resultaten onmiddellijk. Realtime-functies (asynchrone functies) zijn ook mogelijk; deze worden echter niet in detail uitgelegd vanwege hun complexiteit.

Algemene informatie over de interface

Het maximumaantal parameters in een met LibreOffice Calc verbonden addin-functie is 16: één retourwaarde en maximaal 15 functie-invoerparameters.

De gegevenstypen worden als volgt gedefinieerd:

Gegevenstypen	Definitie
CALLTYPE	Onder Windows: FAR PASCAL (_far _pascal) Andere: standaard (besturingssysteem-specifieke standaard)
USHORT	2-byte niet-ondertekend geheel getal
DOUBLE	8-byte platformafhankelijke opmaak
Paramtype	Platformafhankelijk als int PTR_DOUBLE =0 aanwijzer naar een double PTR_STRING =1 aanwijzer naar een tekenreeks die op een nul eindigt PTR_DOUBLE_ARR =2 aanwijzer naar een double array PTR_STRING_ARR =3 pointer naar een tekenreeksarray PTR_CELL_ARR =4 aanwijzer naar een cell array NONE =5

functies

Hieronder vindt u een beschrijving van die functies, die worden aangeroepen op de .

Voor alle functies geldt het volgende:

void CALLTYPE fn(out, in1, in2, ...)

Uitvoer: Resulterende waarde

Invoer: Elk type getal (dubbel&, teken*, dubbel*, teken**, Celbereik), waarbij de Cell area een matrix is van het type dubbele matrix, stringmatrix of celmatrix.

GetFunctionCount()

Geeft het aantal functies zonder de beheerfuncties van de verwijzingsparameter. Elke functie heeft een uniek getal tussen 0 en nCount-1. Dit getal is later nodig voor de functies GetFunctionData en GetParameterDescription.

Syntaxis

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parameter

USHORT &nCount:

Uitvoer: Verwijzing naar een variabele, die verondersteld wordt het aantal add-in-functies te bevatten. Bijvoorbeeld: als de invoegtoepassing 5 functies biedt voor LibreOffice Calc, dan is nCount=5.

GetFunctionData()

Bepaalt alle belangrijke informatie over een addin-functie.

Syntaxis

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

Parameter

USHORT& nNo:

Invoer: Functienummer tussen 0 en nCount-1, inclusief.

char* pFuncName:

Uitvoer: Functienaam zoals gezien door de programmeur, zoals deze genoemd wordt in de . Deze naam bepaalt niet de naam die wordt gebruikt in de Functie-assistent.

USHORT& nParamCount:

Uitvoer: Aantal parameters in AddIn-functie. Dit aantal moet groter zijn dan 0, omdat er altijd een resultaatwaarde is; de maximale waarde is 16.

Paramtype* peType:

Uitvoer: Pointer naar een matrix van precies 16 variabelen van het type Paramtype. De eerste nParamCount-vermeldingen zijn gevuld met het geschikte type parameter.

char* pInternalName:

Uitvoer: Functienaam zoals gezien door de gebruiker, zoals deze verschijnt in de Functie-assistent. Kan umlauts bevatten.

De parameters pFuncName en pInternalName zijn tekenmatrices, die met grootte 256 in LibreOffice Calc geïmplementeerd worden.

GetParameterDescription()

Geeft een korte beschrijving van de addin-functie en bijbehorende parameters. Deze functie kan als optie gebruikt worden om een functie- en parameterbeschrijving weer te geven in de Functie-Assistent.

Syntaxis

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

Parameter

USHORT& nNo:

Input: Nummer van de functie in de bibliotheek; tussen 0 en nCount-1.

USHORT& nParam:

Invoer: Geeft aan voor welke parameter de beschrijving wordt gegeven; parameters beginnen bij 1. Als nParam 0 is, wordt verondersteld dat de beschrijving zelf in pDesc wordt geleverd; in dit geval heeft pName geen betekenis.

char* pName:

Uitvoer: Neemt de parameternaam of het type op, bijvoorbeeld het woord "Getal" of "Tekenreeks" of "Datum", enzovoort. Geïmplementeerd in LibreOffice Calc als char[256].

char* pDesc:

Uitvoer: neemt de beschrijving op van de parameter, bijvoorbeeld "Waarde waarmee de universeel moet worden berekend". Geïmplementeerd in LibreOffice Calc als char[256].

pName en pDesc zijn char arrays; geïmplementeerd in LibreOffice Calc met grootte 256. De beschikbare ruimte in de Functie-Assistent is beperkt waardoor de 256 tekens niet volledig gebruikt kunnen worden.

Celbereiken

De volgende tabellen bevatten informatie over welke gegevensstructuren een externe programmamodule moet leveren om celbereiken door te kunnen geven. In LibreOffice Calc wordt een onderscheid gemaakt tussen drie verschillende matrices, afhankelijk van het gegevenstype.

Dubbele matrix

Als parameter kan een celgebied met waarden van het type Getal/Dubbel doorgegeven worden. In LibreOffice Calc wordt een double array als volgt gedefinieerd:

Verschuiving	Naam	Beschrijving
0	Kol1	Kolomnummer in de linkerbovenhoek van het celgebied. Nummering begint bij 0.
2	Rij1	Rijnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
4	Tab1	Tabelnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
6	Kol2	Kolomnummer in de rechterbenedenhoek van het celgebied. Nummering begint bij 0.
8	Rij2	Rijnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
10	Tab2	Tabelnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
12	Aantal	Aantal van de volgende elementen. Lege cellen worden niet geteld of doorgegeven.
14	Kol	Kolomnummer van het element. Nummering begint bij 0.
16	Rij	Rijnummer van het element; nummering begint bij 0.
18	Tab	Tabelnummer van het element; nummering begint bij 0.
20	Fout	Foutnummer, waarbij de waarde 0 gedefinieerd wordt als 'Geen fout'. Als het element uit een formulecel komt, wordt de foutwaarde door de formule bepaald.
22	Waarde	8-byte IEEE-variabele van het type dubbele/drijvende komma
30	...	Volgend element

String Array

Een celgebied dat waarden van het gegevenstype Tekst bevat en dat als een tekenreeksarray doorgegeven wordt. Een tekenreeksarray in LibreOffice Calc wordt als volgt gedefinieerd:

Verschuiving	Naam	Beschrijving
0	Kol1	Kolomnummer in de linkerbovenhoek van het celgebied. Nummering begint bij 0.
2	Rij1	Rijnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
4	Tab1	Tabelnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
6	Kol2	Kolomnummer in de rechterbenedenhoek van het celgebied. Nummering begint bij 0.
8	Rij2	Rijnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
10	Tab2	Tabelnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
12	Aantal	Aantal van de volgende elementen. Lege cellen worden niet geteld of doorgegeven.
14	Kol	Kolomnummer van het element. Nummering begint bij 0.
16	Rij	Rijnummer van het element; nummering begint bij 0.
18	Tab	Tabelnummer van het element; nummering begint bij 0.
20	Fout	Foutnummer, waarbij de waarde 0 gedefinieerd wordt als 'Geen fout'. Als het element uit een formulecel komt, wordt de foutwaarde door de formule bepaald.
22	Lengte	Lengte van de volgende tekenreeks, inclusief afsluitende nulbyte. Als de lengte inclusief afsluitende nulbyte gelijk is aan een oneven waarde, wordt er een tweede nulbyte aan de tekenreeks toegevoegd zodat er een even waarde wordt verkregen. Daarom wordt Lengte berekend met ((StrLen+2)&~1).
24	String	Tekenreeks met afsluitende nulbyte
24+Len	...	Volgend element

Celmatrix

Cell arrays worden gebruikt om celbereiken met zowel tekst als getallen aan te roepen. Een cell array in LibreOffice Calc wordt als volgt gedefinieerd:

Verschuiving	Naam	Beschrijving
0	Kol1	Kolomnummer in de linkerbovenhoek van het celgebied. Nummering begint bij 0.
2	Rij1	Rijnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
4	Tab1	Tabelnummer in de linkerbovenhoek van het celgebied; nummering begint bij 0.
6	Kol2	Kolomnummer in de rechterbenedenhoek van het celgebied. Nummering begint bij 0.
8	Rij2	Rijnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
10	Tab2	Tabelnummer in de rechterbenedenhoek van het celgebied; nummering begint bij 0.
12	Aantal	Aantal van de volgende elementen. Lege cellen worden niet geteld of doorgegeven.
14	Kol	Kolomnummer van het element. Nummering begint bij 0.
16	Rij	Rijnummer van het element; nummering begint bij 0.
18	Tab	Tabelnummer van het element; nummering begint bij 0.
20	Fout	Foutnummer, waarbij de waarde 0 gedefinieerd wordt als 'Geen fout'. Als het element uit een formulecel komt, wordt de foutwaarde door de formule bepaald.
22	Type	Type celinhoud , 0 == double, 1 == string
24	Waarde of Lengte	Als type == 0: 8-byte IEEE-variabele van het type double/drijvende komma Als type == 1: Lengte van de volgende tekenreeks, inclusief afsluitende nulbyte. Als de lengte inclusief afsluitende nulbyte gelijk is aan een oneven waarde, wordt er een tweede nulbyte aan de tekenreeks toegevoegd zodat er een even waarde wordt verkregen. Daarom wordt 'Lengte' berekend met ((StrLen+2)&~1).
26 als type==1	String	Als type == 1: Tekenreeks met afsluitende nulbyte
32 of 26+Lengte	...	Volgend element