Tillägg för programmering i LibreOffice Calc
Metoden med att utöka Calc med tillägg på det sätt som beskrivs nedan används inte längre. Gränssnitten finns fortfarande kvar och stöds, för att säkerställa kompatibiliteten med befintliga tillägg. Om du vill programmera nya tillägg ska du i stället använda de nya API-funktionerna.
Du kan utöka LibreOffice Calc med add-ins, som är externa programmeringsmoduler som ger ytterligare funktioner för tabeller. De visas i Funktionsguiden i kategorin Tillägg. Om du vill programmera ett tillägg själv kan du här lära dig vilka funktioner som måste exporteras av det gemensamma biblioteketden externa DLL-filen så att tillägget kan anslutas.
LibreOffice söker i tilläggsmappen som definieras i konfigurationen efter en lämplig delad biblioteks-DLL-fil. För att identifieras av LibreOffice måste den delade biblioteks-DLL-filen ha vissa egenskaper, vilka förklaras nedan. Med den här informationen kan du programmera ditt eget tillägg för Funktionsguiden för LibreOffice Calc.
Add-in-konceptet
Varje add-inbibliotek ger flera funktioner. En del funktioner används för administrativa ändamål. Du kan ge de här funktionerna nästan vilka namn som helst. De måste dock följa vissa regler gällande ersättning av värde. De exakta namn- och anropskonventionerna varierar mellan olika plattformar.
Funktioner i det gemensamma biblioteketDLL-filen för tillägg
Som ett minimum måste de adminstrativa funktionerna GetFunctionCount och GetFunctionData finnas. Om du använder dessa går det att bestämma funktioner samt parametertyper och returvärden. Som returvärden stöds typerna Dubbel och Sträng. Som parametrar stöds dessutom cellområdena Double Array, String Array och Cell Array.
Parametrar överlämnas per referens. Därför kan du i allmänhet ändra värdena. Detta stöds dock inte av LibreOffice Calc, eftersom det inte är meningsfullt i ett kalkylprogram.
Bibliotek kan laddas om under körning och innehållet kan analyseras med de administrativa funktionerna. För varje funktion finns information om antal och parametertyp, interna och externa funktionsnamn och ett administrativt nummer.
Funktionerna anropas synkront och returnerar omedelbart sina resultat. Realtimefunktioner (asynkrona funktioner) är visserligen också möjliga, men de är för komplexa för att närmare förklaras här.
Allmänt om gränssnittet
Det maximala antalet parametrar i en add-infunktion som är kopplad till LibreOffice Calc är 16: ett returvärde och högst 15 funktionsindataparametrar.
Datatyperna är definierade på följande sätt:
Datatyp |
Definition |
CALLTYPE |
under Windows: FAR PASCAL (_far _pascal) annars: default (operativsystemsspecifik standard) |
USHORT |
2 byte unsigned Integer |
double |
8 byte plattformsberoende format |
Paramtype |
plattformsberoende som int PTR_DOUBLE =0 pekare på en double PTR_STRING =1 pekare på en noll-terminerad teckenkedja PTR_DOUBLE_ARR =2 pekare på en Double Array PTR_DOUBLE_ARR =3 pekare på en String Array PTR_DOUBLE_ARR =4 pekare på en Cell Array NONE =5 |
Gemensamt bibliotekDLL-funktioner
Nedan finns en beskrivning av dessa funktioner, som anropas via det gemensamma biblioteketden externa DLL-filen.
Följande gäller för alla funktioner för Shared LibraryDLL-filen:
void CALLTYPE fn(out, in1, in2, ...)
Output: Resultatvärde
Inmatning: Ett antal typer (dubbel&, tecken*, dubbel*, tecken**, cellområde), där cellområde är en matris av typen dubbelmatris, strängmatris eller cellmatris.
GetFunctionCount()
Returnerar antalet funktioner utan förvaltningsfunktionerna i referensparametern. Varje funktion har ett entydigt nummet mellan 0 och nCount-1. Detta nummer används senare för funktionerna GetFunctionData och GetParameterDescription.
Syntax
void CALLTYPE GetFunctionCount(USHORT& nCount)
Parameter
USHORT &nCount:
Output: Referens till variabel, som ska innehålla antalet AddIn-funktioner. Om AddIn-programmet t ex ställer 5 funktioner till LibreOffice Calcs förfogande är nCount=5.
GetFunctionData()
Bestämmer all viktig information om en add-infunktion.
Syntax
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Parameter
USHORT& nNo:
Input: Funktionsnummer mellan 0 och nCount-1 inklusive.
char* pFuncName:
Utdata: Funktionsnamn som programmeraren ser det, med namnet den har i Shared LibraryDLL-filen. Det här namnet bestämmer inte namnet som används i Funktionsguiden.
USHORT& nParamCount:
Output: Antal parametrar för AddIn-funktionen. Detta antal ska vara större än 0, eftersom det alltid finns ett resultatvärde. Maximivärdet är 16.
Paramtype* peType:
Output: Pekare på en Array med exakt 16 variabler av typen Paramtype. De första nParaCount-posterna fylls med typen för respektive parameter.
char* pInternalName:
Utdata: Funktionsnamn som användaren ser det, som det visas i Funktionsguiden. Kan innehålla omljud.
Parametrarna pFuncName och pInternalName är char Arrays som implementerats med storleken 256 i LibreOffice Calc.
GetParameterDescription()
Ger en kort beskrivning av add-infunktionen och dess parametrar. Som ett alternativ kan den här funktionen användas för att visa en funktions- och parameterbeskrivning i Funktionsguiden.
Syntax
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Parameter
USHORT& nNo:
Input: Funktionens nummer i biblioteket mellan 0 och nCount-1.
USHORT& nParam:
Input: Anger för vilken parameter beskrivningen ska levereras. Parametrar börjar vid 1. Om nParam är 0 ska beskrivningen av funktionen i sig ges i pDesc. pName är i detta fall betydelselös.
char* pName:
Output: Upptar namnet respektive parametertypen, t ex ordet "Tal" eller "Teckenkedja" eller "Datum" eller liknande. Implementeras som char[256] i LibreOffice Calc.
char* pDesc:
Output: Antar parameterns beskrivning, t ex "Värde med vilket universum ska beräknas". Implementeras som char[256] i LibreOffice Calc.
pName och pDesc är teckenmatriser som implementeras i LibreOffice Calc med storleken 256. Observera att utrymmet i Funktionsguiden är begränsat och att alla 256 tecken kan inte användas.
Cellområden
I följande tabell ser Du vilka datastrukturer en extern programmodul måste tillhandahålla för att överlämna cellområden. LibreOffice Calc skiljer mellan tre olika Arrays, beroende på datatyp.
Double Array
Du kan överlämna ett cellområde med värden av typen tal/double som parameter. En Double Array definieras på följande sätt i LibreOffice Calc:
Offset |
Namn |
Beskrivning |
0 |
Col1 |
Kolumnnummer i cellområdets övre vänstra hörn. Numreringen börjar med 0. |
2 |
Row1 |
Radnummer i cellområdets övre vänstra hörn, räknat från 0. |
4 |
Tab1 |
Tabellnummer i cellområdets övre vänstra hörn, räknat från 0. |
6 |
Col2 |
Kolumnnummer i cellområdets nedre högra hörn. Räkningen börjar med 0. |
8 |
Row2 |
Radnummer i cellområdets nedre högra hörn, räknat från 0. |
10 |
Tab2 |
Tabellnummer i cellområdets nedre högra hörn, räknat från 0. |
12 |
Count |
Antal följande element. Tomma celler räknas inte och överlämnas inte. |
14 |
Col |
Elementets kolumnnummer. Räkningen börjar med 0. |
16 |
Rad |
Elementets radnummer, räknat från 0. |
18 |
Tab |
Elementets tabellnummer, räknat från 0. |
20 |
Error |
Felnummer, varvid värdet 0 för "inget fel" är belagt. När elementet kommer från en formelcell, bestäms felvärdet av formeln. |
22 |
Value |
8 byte IEEE-variabel av typen double/flytande komma |
30 |
... |
Nästa element |
String Array
Ett cellområde, som innehåller värden av datatypen Text överlämnas som String Array. En String Array definieras på följande sätt i LibreOffice Calc:
Offset |
Namn |
Beskrivning |
0 |
Col1 |
Kolumnnummer i cellområdets övre vänstra hörn. Numreringen börjar med 0. |
2 |
Row1 |
Radnummer i cellområdets övre vänstra hörn, räknat från 0. |
4 |
Tab1 |
Tabellnummer i cellområdets övre vänstra hörn, räknat från 0. |
6 |
Col2 |
Kolumnnummer i cellområdets nedre högra hörn. Räkningen börjar med 0. |
8 |
Row2 |
Radnummer i cellområdets nedre högra hörn, räknat från 0. |
10 |
Tab2 |
Tabellnummer i cellområdets nedre högra hörn, räknat från 0. |
12 |
Count |
Antal följande element. Tomma celler räknas inte och överlämnas inte. |
14 |
Col |
Elementets kolumnnummer. Räkningen börjar med 0. |
16 |
Rad |
Elementets radnummer, räknat från 0. |
18 |
Tab |
Elementets tabellnummer, räknat från 0. |
20 |
Error |
Felnummer, varvid värdet 0 för "inget fel" är belagt. När elementet kommer från en formelcell, bestäms felvärdet av formeln. |
22 |
Len |
Längden hos den följande strängen, inklusive avslutande noll-byte. När längden inklusive avslutande noll-byte ger ett udda värde läggs ytterligare en noll-byte till värdet, så att ett jämnt värde fås. Därför beräknas Len med ((StrLen+2)&~1). |
24 |
String |
Teckenföljd med avslutande noll-byte. |
24+Len |
... |
Nästa element |
Cell Array
Cellmatriser används för att anropa cellområden som innehåller text respektive tal. En cellmatris i LibreOffice Calc definieras så här:
Offset |
Namn |
Beskrivning |
0 |
Col1 |
Kolumnnummer i cellområdets övre vänstra hörn. Numreringen börjar med 0. |
2 |
Row1 |
Radnummer i cellområdets övre vänstra hörn, räknat från 0. |
4 |
Tab1 |
Tabellnummer i cellområdets övre vänstra hörn, räknat från 0. |
6 |
Col2 |
Kolumnnummer i cellområdets nedre högra hörn. Räkningen börjar med 0. |
8 |
Row2 |
Radnummer i cellområdets nedre högra hörn, räknat från 0. |
10 |
Tab2 |
Tabellnummer i cellområdets nedre högra hörn, räknat från 0. |
12 |
Count |
Antal följande element. Tomma celler räknas inte och överlämnas inte. |
14 |
Col |
Elementets kolumnnummer. Räkningen börjar med 0. |
16 |
Rad |
Elementets radnummer, räknat från 0. |
18 |
Tab |
Elementets tabellnummer, räknat från 0. |
20 |
Error |
Felnummer, varvid värdet 0 för "inget fel" är belagt. När elementet kommer från en formelcell, bestäms felvärdet av formeln. |
22 |
Type |
Cellinnehållets typ, 0 == Double, 1 == String |
24 |
Value or Len |
När typ == 0: 8 byte IEEE-variabel av typen double/flytande komma När typ == 1: Längden hos den följande strängen, inklusive avslutande noll-byte. När längden inklusive avslutande noll-byte ger ett udda värde läggs ytterligare en noll-byte till värdet, så att ett jämnt värde fås. Därför beräknas Len med ((StrLen+2)&~1). |
26 if Type==1 |
String |
När typ == 1: Teckenföljd med avslutande noll-byte. |
32 or 26+Len |
... |
Nästa element |