Contingut

# Complement de programació del LibreOffice Calc

El mètode que es descriu tot seguit per ampliar el Calc amb complements no està actualitzat. Les interfícies segueixen sent vàlides i compatibles per assegurar la compatibilitat amb els complements existents; no obstant això, si voleu programar complements nous, cal que utilitzeu les noves funcions API.

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.

## El concepte de complement

Cada biblioteca de complement proporciona diverses funcions. Algunes funcions s'utilitzen per a l'administració. Podeu triar gairebé qualsevol nom per a les vostres funcions. No obstant això, també han de seguir certes regles pel que fa a l'entrada de paràmetres. Les restriccions de noms i de crida varien entre diferents plataformes.

### Functions of Shared Library AddIn DLL

En tots els casos, les funcions administratives GetFunctionCount i GetFunctionData han d'existir. Gràcies a aquestes funcions, es poden determinar les funcions, els tipus de paràmetres i els valors de retorn. Com a valors de retorn, s'admeten els tipus Doble i Cadena. Com a paràmetres, s'admeten les àrees de cel·les Matriu doble, Matriu de cadena i Matriu de cel·les.

Els paràmetres es transmeten mitjançant referències; per tant, en teoria és possible modificar aquests valors. No obstant això, el LibreOffice Calc no ho permet perquè no té sentit fer-ho en fulls de càlcul.

Les biblioteques es poden actualitzar durant el temps d'execució i les funcions administratives en poden analitzar els continguts. Disposeu d'informació sobre cada funció: nombre i tipus de paràmetres, noms de les funcions internes i externes i un número administratiu.

Es criden les funcions de manera sincronitzada i es retornen els resultats immediatament. També es poden cridar funcions de temps real (funcions asíncrones); tanmateix, no s'expliquen detalladament a causa de la seva complexitat.

## Informació general de la interfície

El nombre màxim de paràmetres en una funció de complement adjunta al LibreOffice Calc és 16: un valor de retorn i un màxim de 15 paràmetres d'entrada.

Els tipus de dades es defineixen de la manera següent:

Tipus de dades | Definició
--- | ---
CALLTYPE | En el Windows: FAR PASCAL (_far _pascal) Altrament: per defecte (valor per defecte del sistema operatiu)
USHORT | Enter sense signe de 2 bytes
DOUBLE | format dependent de la plataforma, de 8 bytes
Paramtype | Dependent de la plataforma, com int PTR_DOUBLE =0 busca en un doble PTR_STRING =1 busca en una cadena que acaba amb 0 PTR_DOUBLE_ARR =2 busca en una matriu doble PTR_STRING_ARR =3 busca en una matriu de cadenes PTR_CELL_ARR =4 busca en una matriu de cel·la 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()

Retorna el nombre de funcions sense les funcions de gestió del paràmetre de referència. Cada funció té un número únic entre el 0 i nCount-1. Aquest número és necessari per a les funcions GetFunctionData i GetParameterDescription.

Sintaxi

void CALLTYPE GetFunctionCount(USHORT& nCount)

Paràmetre

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()

Determina tota la informació important sobre una funció de complement.

Sintaxi

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

Paràmetre

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.

Els paràmetres pFuncName i pInternalName són matrius de caràcters, implementats al LibreOffice Calc amb una mida de 256.

### GetParameterDescription()

Proporciona una descripció breu de la funció de complement i dels paràmetres que la componen. Com a opció, la funció es pot utilitzar per mostrar una descripció d'una funció i dels paràmetres a l'Auxiliar de funcions.

Sintaxi

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

Paràmetre

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

Les matrius de caràcters pName i pDesc s'han implementat al LibreOffice Calc amb una mida de 256. Tingueu en compte que l'espai disponible a l'Auxiliar de funcions és limitat i, per tant, no es poden utilitzar els 256 caràcters.

## Àrees de cel·les

Les taules següents contenen informació sobre quines estructures de dades han de proporcionar-se a un mòdul de programa extern per passar les àrees de les cel·les. El LibreOffice Calc distingeix entre tres matrius diferents, segons el tipus de dades.

### Matriu doble

Com a paràmetre, es pot introduir una àrea de cel·les amb valors del tipus Nombre/Doble. Al LibreOffice Calc, les matrius dobles es defineixen de la manera següent:

Offset | Nom | Descripció
--- | --- | ---
0 | Col1 | Número de columna de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
2 | Fila1 | Número de fila de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
4 | Tab1 | Número de taula de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
6 | Col2 | Número de columna de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
8 | Fila2 | Número de fila de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
10 | Tab2 | Número de taula de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
12 | Comptatge | Nombre dels elements següents. Les cel·les buides no es tenen en compte ni es calculen.
14 | Col | Número de columna de l'element. Numeració a partir de 0.
16 | Fila | Número de fila de l'element; numeració a partir de 0.
18 | Pestanya | Número de taula de l'element; numeració a partir de 0.
20 | Error | Número d'error, on el valor 0 es defineix com a "no error." Si l'element ve d'una cel·la de fórmula, la fórmula determina el valor d'error.
22 | Valor | Variable IEEE de 8 bytes del tipus doble/punt flotant
30 | ... | Element següent

### Matriu de cadenes

Una àrea de cel·les, que conté valors de tipus de dades Text i es considera com a matriu de cadenes. Una matriu de cadenes al LibreOffice Calc es defineix de la manera següent:

Offset | Nom | Descripció
--- | --- | ---
0 | Col1 | Número de columna de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
2 | Fila1 | Número de fila de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
4 | Tab1 | Número de taula de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
6 | Col2 | Número de columna de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
8 | Fila2 | Número de fila de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
10 | Tab2 | Número de taula de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
12 | Comptatge | Nombre dels elements següents. Les cel·les buides no es tenen en compte ni es calculen.
14 | Col | Número de columna de l'element. Numeració a partir de 0.
16 | Fila | Número de fila de l'element; numeració a partir de 0.
18 | Pestanya | Número de taula de l'element; numeració a partir de 0.
20 | Error | Número d'error, on el valor 0 es defineix com a "no error." Si l'element ve d'una cel·la de fórmula, la fórmula determina el valor d'error.
22 | Len | Longitud de la cadena següent, inclòs el byte zero de tancament. Si la longitud (el byte zero de tancament inclòs) és igual a un valor inexacte, s'afegeix un segon byte zero a la cadena per a obtenir un valor exacte. Per tant, Len es calcula mitjançant ((StrLen+2)&~1).
24 | Cadena | Cadena amb byte de tancament zero
24+Len | ... | Element següent

### Matriu de cel·les

Les matrius de cel·les s'utilitzen per cridar les àrees de cel·les que contenen tant text com nombres. Una matriu de cel·les al LibreOffice Calc es defineix de la manera següent:

Offset | Nom | Descripció
--- | --- | ---
0 | Col1 | Número de columna de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
2 | Fila1 | Número de fila de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
4 | Tab1 | Número de taula de la cantonada superior esquerra de l'àrea de cel·les; numeració a partir de 0.
6 | Col2 | Número de columna de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
8 | Fila2 | Número de fila de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
10 | Tab2 | Número de taula de la cantonada inferior dreta de l'àrea de cel·les; numeració a partir de 0.
12 | Comptatge | Nombre dels elements següents. Les cel·les buides no es tenen en compte ni es calculen.
14 | Col | Número de columna de l'element. Numeració a partir de 0.
16 | Fila | Número de fila de l'element; numeració a partir de 0.
18 | Pestanya | Número de taula de l'element; numeració a partir de 0.
20 | Error | Número d'error, on el valor 0 es defineix com a "no error." Si l'element ve d'una cel·la de fórmula, la fórmula determina el valor d'error.
22 | Tipus | Tipus de contingut de la cel·la, 0 == Doble, 1 == Cadena
24 | Value o Len | Si Tipus == 0: variable IEEE de tipus doble/punt flotant de 8 bytes Si Tipus == 1: longitud de la cadena següent, inclòs el byte zero de tancament. Si la longitud (el byte zero de tancament inclòs) és igual a un valor inexacte, s'afegeix un segon byte zero a la cadena per a obtenir un valor exacte. Per tant, Len es calcula mitjançant ((StrLen+2)&~1).
26 if Type==1 | Cadena | Si Tipus == 1: la cadena acaba en un byte 0.
32 o 26+Len | ... | Element següent