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.
El funcionament del LibreOffice Calc es pot ampliar mitjançant els complements, mòduls de programació externs que ofereixen funcions addicionals per treballar amb els fulls de cà lcul. A l'Auxiliar de funcions, a la categoria Complement, s'enumeren els complements disponibles. Si voleu programar un complement, acà trobareu informació sobre les funcions que s'han d'exportar des de la biblioteca compartida DLL externa per poder adjuntar correctament el complement.
El LibreOffice busca una biblioteca compartida DLL a la carpeta de complements que s'ha definit a la configuració. Perquè el LibreOffice la detecti, la biblioteca compartida DLL ha de tindre determinades propietats, tal com s'explica tot seguit. Esta informació vos permet programar el vostre propi complement per a l'Auxiliar de funcions del 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.
Funcions de la biblioteca compartida DLL de complement
En tots els casos, les funcions administratives GetFunctionCount i GetFunctionData han d'existir. Grà cies a estes 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 estos 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 seua 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 |
DOBLE |
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 |
Biblioteca compartida DLL: funcions
Tot seguit trobareu una descripció d'estes funcions, que es criden a la biblioteca DLL externa.
Les regles següents s'apliquen a totes les funcions de biblioteca compartida DLL:
void CALLTYPE fn(out, in1, in2, ...)
Resultat: valor del resultat
Entrada: qualsevol nombre de tipus (doble&, car*, doble*, car**, à rea de cel·les), on l'à rea de cel·les és una matriu de tipus doble, de cadena o de cel·la.
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. Este número és necessari per a les funcions GetFunctionData i GetParameterDescription.
Sintaxi
void CALLTYPE GetFunctionCount(USHORT& nCount)
Parà metre
USHORT &nCount:
Eixida: referència a una variable, que ha de contindre el nombre de funcions de complements. Per exemple: si el complement proporciona 5 funcions per al LibreOffice Calc, 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:
Entrada: número de funció, entre 0 i nCount-1 (inclosos).
char* pFuncName:
Resultat: el nom de la funció tal com el veu el programador, tal com s'anomena a la biblioteca compartida DLL. Este nom no determina el nom que s'utilitza en l'Auxiliar de funcions.
USHORT& nParamCount:
Eixida: nombre de parà metres de la funció de complement. Este nombre ha de ser més gran que 0, ja que sempre hi ha un valor resultant; el valor mà xim és 16.
Paramtype* peType:
Resultat: busca a una matriu d'exactament 16 variables del tipus Paramtype. Les primeres entrades nParamCount s'omplen amb el tipus de parà metre corresponent.
char* pInternalName:
Resultat: el nom de la funció tal com el veu l'usuari, tal com apareix a l'Auxiliar de funcions. Pot contindre dièresis.
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:
Entrada: número de la funció a la biblioteca, entre 0 i nCount-1.
USHORT& nParam:
Entrada: indica per a quin parà metre es proporciona la descripció; els parà metres comencen per l'1. Si nParam és 0, s'ha d'introduir la mateixa descripció a pDesc; en este cas, pName no té cap significat.
char* pName:
Resultat: afig el nom o el tipus de parà metre, per exemple la paraula "Nombre" o "Cadena" o "Data", etc. S'ha implementat al LibreOffice Calc com a char[256].
char* pDesc:
Resultat: afig la descripció del parà metre, per exemple, "Valor del qual s'ha de calcular la suma." S'ha implementat al LibreOffice Calc com a 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:
Desplaçament |
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:
Desplaçament |
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'afig un segon byte zero a la cadena per obtindre 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:
Desplaçament |
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'afig un segon byte zero a la cadena per obtindre 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 |