Tillägg för programmering i LibreOffice Calc

Varningssymbol

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 så att tillägget kan anslutas.

LibreOffice söker i tilläggsmappen som definieras i konfigurationen efter en lämplig -fil. För att identifieras av LibreOffice måste -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

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


-funktioner

Nedan finns en beskrivning av dessa funktioner, som anropas via .

Följande gäller för alla funktioner för :

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 . 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