Addin voor programmering in LibreOffice Calc
De hieronder beschreven methode voor uitbreiding van Calc met addins is verouderd. De interfaces zijn nog steeds functioneel en worden nog steeds ondersteund om compatibiliteit met bestaande addins te verzekeren. Voor het programmeren van nieuwe addins moet u echter de nieuwe API-functies gebruiken.
LibreOffice Calc kan uitgebreid worden met Addins. Dit zijn externe programmeermodules die extra functies bieden voor werkbladen. Ze staan in de Functie-Assistent in de categorie Addin. Wilt u zelf een addin programmeren, dan kunt u hier te weten komen welke functies geëxporteerd moeten worden door de gedeelde bibliotheek externe DLL zodat de Add-in gekoppeld kan worden.
LibreOffice zoekt in de map Addins die in de configuratie is opgegeven naar een geschikte gedeelde bibliotheekDLL. De gedeelde bibliotheek DLL moet bepaalde eigenschappen hebben om herkend te worden door LibreOffice, zoals hieronder uitgelegd. Met behulp van deze informatie kunt u uw eigen add-in programmeren voor de Functie-assistent van LibreOffice Calc.
Het addin-concept
Elke addin-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 gedeelde bibliotheek addin-DLL
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 van gedeelde bibliotheek DLL
Hieronder vindt u een beschrijving van de functies, die aangeroepen worden bij de gedeelde bibliotheek externe DLL.
Het volgende is van toepassing op alle functies van de gedeelde bibliotheek DLL:
void CALLTYPE fn(uitvoer, invoer1, invoer2, ...)
Uitvoer: Resulterende waarde
Invoer: Een willekeurig aantal typen (double&, char*, double*, char**, celgebied), waar het Celgebied een matrix is van het type double array, string array of cell array.
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 het aantal addin-functies zou moeten bevatten. Voorbeeld: Als de addin 5 functies voor LibreOffice Calc biedt, is de 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 tot en met nCount-1.
char* pFuncName:
Uitvoer: Functienaam zoals gezien door de programmeur, zoals deze is genoemd in de gedeelde bibliotheek DLL. Deze naam bepaalt niet welke naam in de Functie-Assistent wordt gebruikt.
USHORT& nParamCount:
Uitvoer: Aantal parameters in addin-functie. Dit getal moet groter zijn dan 0, omdat er altijd een resultaatwaarde is; de maximumwaarde is 16.
Paramtype* peType:
Uitvoer: Pointer naar een matrix van precies 16 variabelen van het type Paramtype. De eerste nParamCount-ingangen worden gevuld met het geschikte type parameter.
char* pInternalName:
Uitvoer: Functienaam zoals de gebruiker deze ziet, zoals deze in de Functie-Assistent verschijnt. Kan umlauten 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:
Invoer: Getal 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, dient de beschrijving zelf in pDesc gegeven te worden; in dat geval heeft pName geen betekenis.
char* pName:
Uitvoer: Gebruikt de parameternaam of het parametertype, bijvoorbeeld het woord Getal of Tekenreeks of Datum. Geïmplementeerd in LibreOffice Calc als teken[256].
char* pDesc:
Uitvoer: Neemt de beschrijving van de parameter op, bijvoorbeeld, 'Waarde, waarbij het universum berekend moet worden'. Geïmplementeerd in LibreOffice Calc als teken[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.
Double Array
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+Lengte |
... |
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 |