Innehåll

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

LibreOffice Calc can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the shared library external DLL so that the Add-In can be successfully attached.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared library DLL. To be recognized by LibreOffice, the shared library DLL must have certain properties, as explained in the following. This information allows you to program your own Add-In for Function Wizard of 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.

### Functions of Shared Library AddIn DLL

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

## Shared Library DLL functions

Following you will find a description of those functions, which are called at the Shared Library external DLL.

For all Shared Library DLL functions, the following applies:

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

Output: Resulting value

Input: Any number of types (double&, char*, double*, char**, Cell area), where the Cell area is an array of types double array, string array, or cell array.

### 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: Reference to a variable, which is supposed to contain the number of Add-In functions. For example: If the Add-In provides 5 functions for LibreOffice Calc, then 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: Function number between 0 and nCount-1, inclusively.

char* pFuncName:

Output: Function name as seen by the programmer, as it is named in the Shared Library DLL. This name does not determine the name used in the Function Wizard.

USHORT& nParamCount:

Output: Number of parameters in AddIn function. This number must be greater than 0, because there is always a result value; the maximum value is 16.

Paramtype* peType:

Output: Pointer to an array of exactly 16 variables of type Paramtype. The first nParamCount entries are filled with the suitable type of parameter.

char* pInternalName:

Output: Function name as seen by the user, as it appears in the Function Wizard. May contain umlauts.

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: Number of the function in the library; between 0 and nCount-1.

USHORT& nParam:

Input: Indicates, for which parameter the description is provided; parameters start at 1. If nParam is 0, the description itself is supposed to be provided in pDesc; in this case, pName does not have any meaning.

char* pName:

Output: Takes up the parameter name or type, for example, the word "Number" or "String" or "Date", and so on. Implemented in LibreOffice Calc as char[256].

char* pDesc:

Output: Takes up the description of the parameter, for example, "Value, at which the universe is to be calculated." Implemented in LibreOffice Calc as char[256].

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 | Name | Description
--- | --- | ---
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 | Name | Description
--- | --- | ---
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 | Name | Description
--- | --- | ---
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