Add-in pa programar en LibreOffice Calc
El métodu p'ampliar Calc por aciu add-ins que se describe de siguío nun ta anováu. Pa garantizar la compatibilidá colos add-ins esistentes, les interfaces siguen siendo válides y compatibles. Sicasí, pa programar add-ins nuevos ríquense nueves funciones API.
LibreOffice Calc pue espandise por aciu Add-Ins, módulos esternos de programación qu'apurren funciones adicionales pa trabayar coles fueyes de cálculu. Diches funciones amosar nel Asistente pa funciones de la categoría Add-In. Si deseya programar un add-in, equí indíquense les funciones que tien d'esportar la biblioteca compartida DLL esterna pa poder axuntar el add-in de forma satisfactoria.
LibreOffice busca na carpeta de complementos definida na configuración una biblioteca compartida DLL. Pa que LibreOffice la reconoza, la biblioteca compartida DLL tien de tener ciertes propiedaes, como s'esplica de siguío. Esta información permite-y programar los sos propios complementos pal Asistente pa funciones de LibreOffice Calc.
El conceutu de Add-in
Cada biblioteca Add-in inclúi diverses funciones. Delles funciones utilizar con fines alministrativos. Pue escoyer casi cualquier nome pa les sos propies funciones. Sicasí, hanse de siguir regles específiques relatives al pasu de parámetros. Los convenios esactos de asignación de nomes y llamada de les funciones varien d'una plataforma a otra.
Funciones de la biblioteca compartidaDLL de add-in
A lo menos tienen d'esistir les funciones alministratives GetFunctionCount y GetFunctionData. Con elles puédense determinar les funciones, los tipos de parámetros y los valores de torna. Como valores de torna almiten los tipos Doble y Cadena. Como parámetros, les árees de caxelles doble matriz, matriz de cadenes y matriz de caxelles almítense adicionalmente.
Los parámetros tresmitir por referencia. Por tanto, en principiu los valores podríen ser modificaos. Sicasí, LibreOffice Calc nun almite nengún cambéu, cuidao que nun ye recomendable que se produzan cambeos dientro d'una fueya de cálculu.
Les biblioteques puen volvese a cargar mientres el tiempu d'execución y el so conteníu puédenlo analizar les funciones alministratives. Pa cada función hai información disponible sobre'l númberu y los tipos de parámetros, los nomes de funciones internes y esternes, según un númberu alministrativu.
Les funciones actívense simultáneamente y devuelven la resultancia de mou inmediatu. Tamién ye posible utilizar funciones de tiempu real (funciones asíncronas), pero por cuenta de la so complexidá nun van ser encetaes nesta Ayuda.
Aspeutos xenerales sobre la interfaz
El númberu máximu de parámetros nuna función Add-in acoplada a LibreOffice Calc ye 16: un valor de torna y un máximu de 15 parámetros d'entrada de funciones.
Los tipos de datos definir del mou siguiente:
Tipos de datos |
Definición |
CALLTYPE |
con Windows: FAR PASCAL (_far _pascal) nos demás casos: Predetermináu (según el sistema operativu) |
USHORT |
enteru ensin signu de 2 bytes |
double |
formatu dependiente de la plataforma, de 8 bytes |
Paramtype |
dependiente de la plataforma, como int PTR_DOUBLE =0 punteru a un double PTR_STRING =1 piqueru sobre una cadena de caráuteres llindada temporalmente a cero PTR_DOUBLE_ARR =2 punteru a un array de tipu double PTR_STRING_ARR =3 punteru a un array de tipu string PTR_CELL_ARR =4 punteru a un array de tipu cell NENGÚN =5 |
Biblioteca compartidaFunciones de DLL
De siguío, preséntase una descripción de diches funciones, que puen activase na biblioteca compartida DLL esterna.
Les indicaciones siguientes aplicar a toles funciones de biblioteca compartida DLL:
void CALLTYPE fn(salida, entrada1, entrada2, ...)
Salida: Resultancia
Entrada: Cualquier númberu de tipos (double&, char*, double*, char**, área de caxelles), onde área de caxelles ye una matriz de tipos matriz de double (enteru de doble precisión), matriz de cadenes o matriz de caxelles.
GetFunctionCount()
Anicia un númberu de funciones que nun inclúin les d'alministración, nel parámetru de referencia. Cada función tien asignáu un númberu únicu entendíu ente 0 y nCount-1. Esti códigu utilízase darréu pa les funciones GetFunctionData y GetParameterDescription.
Sintaxis
void CALLTYPE GetFunctionCount(USHORT& nCount)
Parámetros
USHORT &nCount:
Salida: Referencia a una variable que tien de contener el númberu de funciones Add-in. Por exemplu, si Add-in ufierta 5 funciones en LibreOffice Calc, nCount=5.
GetFunctionData()
Determina tola información importante alrodiu d'una función Add-in.
Sintaxis
void CALLTYPE GetFunctionData(USHORT& nNo, char* pFuncName, USHORT& nParamCount, Paramtype* peType, char* pInternalName)
Parámetros
USHORT& nNo:
Entrada: Númberu de función entendíu ente 0 y nCount-1, dambos incluyíos.
char* pFuncName:
Salida: Nome de la función que ve'l programador, como se denomina na biblioteca compartidaDLL. Esti nome nun determina'l nome que s'utiliza nel Asistente pa funciones.
USHORT& nParamCount:
Salida: Númberu de parámetros de la función Add-in. Dichu númberu tien de ser cimeru a 0, yá que siempres hai una resultancia; el valor máximu ye 16.
Paramtype* peType:
Salida: Piqueru sobre un array que contién esactamente 16 variables del tipu paramtype. Les primeres entraes de nParamCount completar col tipu del parámetru correspondiente.
char* pInternalName:
Salida: Nome de la función que ve l'usuariu, como apaez nel Asistente pa funciones. Pue contener el caráuter umlaut.
Los parámetros pFuncName y pInternalName son arrays de char que tán implementaos en LibreOffice Calc col tamañu 256.
GetParameterDescription()
Apurre una curtia descripción de la función Add-in y de los sos parámetros. Si deseyar, esta función pue utilizar p'amosar una descripción de función y parámetros nel Asistente pa funciones.
Sintaxis
void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)
Parámetros
USHORT& nNo:
Entrada: Númberu de la función dientro de la biblioteca, entendíu ente 0 y nCount-1.
USHORT& nParam:
Entrada: Indica'l parámetru al cual tien de referise la descripción; los parámetros empiecen por 1. Si'l parámetru nParam ye 0, tien d'ufiertase la descripción de la mesma función en pDesc; nesti casu, pName escarez de significáu.
char* pName:
Salida: Aceuta'l nome y el tipu de parámetru; por exemplu, la pallabra "númberu" o "cadena de caráuteres" o "fecha", etc. En LibreOffice Calc ta implementáu como char[256].
char* pDesc:
Salida: Aceuta la descripción del parámetru; por exemplu, "valor según el cual tien de calculase l'universu". En LibreOffice Calc ta implementáu como char[256].
pName y pDesc son matrices de caráuteres de tamañu 256, implementaes en LibreOffice Calc. Tenga en cuenta que l'espaciu disponible nel Asistente pa funciones ye llindáu y que nun ye posible utilizar la totalidá de los 256 caráuteres.
Árees de caxelles
Les tables siguientes contienen información sobre les estructures de datos que tien d'ufiertar un módulu de programa esternu pa poder tresmitir árees de caxelles. En función del tipu de datos, LibreOffice Calc estrema ente trés arrays distintos.
Array de tipu doble
Una área de caxella pue tresmitise como parámetru colos valores del tipu númberu/double. En LibreOffice Calc, un double array definir de la forma siguiente:
Desplazamientu |
Nome |
Descripción |
0 |
Col1 |
Númberu de columna de la esquina cimera esquierda del área de caxelles. La numberación empieza por 0. |
2 |
Row1 |
Númberu de filera de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
4 |
Tab1 |
Númberu de fueya de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
6 |
Col2 |
Númberu de columna de la esquina inferior derecha del área de caxelles. La numberación empieza por 0. |
8 |
Filera2 |
Númberu de filera de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
10 |
Tab2 |
Númberu de fueya de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
12 |
Count |
Númberu total de cada unu de los siguientes elementos. Les caxelles baleres nun tán incluyíes nel recuentu y nun se tresmiten. |
14 |
Col |
Númberu de columna del elementu. La numberación empieza por 0. |
16 |
Filera |
Númberu de filera del elementu, cuntáu a partir de 0. |
18 |
Tab |
Númberu de fueya del elementu, cuntáu a partir de 0. |
20 |
Fallu |
Númberu de fallu; el valor 0 ta reserváu pa "nengún fallu". Si l'elementu vien d'una caxella de fórmula, el valor del fallu ta determináu pola fórmula. |
22 |
Value |
Variable IEEE de 8 bytes del tipu double/coma flotante |
30 |
... |
Elementu siguiente |
String array
Una área de caxelles que contién valores de tipu testu ye tresmitíu como string array. En LibreOffice Calc, un array de string defínese como sigue:
Desplazamientu |
Nome |
Descripción |
0 |
Col1 |
Númberu de columna de la esquina cimera esquierda del área de caxelles. La numberación empieza por 0. |
2 |
Row1 |
Númberu de filera de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
4 |
Tab1 |
Númberu de fueya de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
6 |
Col2 |
Númberu de columna de la esquina inferior derecha del área de caxelles. La numberación empieza por 0. |
8 |
Filera2 |
Númberu de filera de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
10 |
Tab2 |
Númberu de fueya de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
12 |
Count |
Númberu total de cada unu de los siguientes elementos. Les caxelles baleres nun tán incluyíes nel recuentu y nun se tresmiten. |
14 |
Col |
Númberu de columna del elementu. La numberación empieza por 0. |
16 |
Filera |
Númberu de filera del elementu, cuntáu a partir de 0. |
18 |
Tab |
Númberu de fueya del elementu, cuntáu a partir de 0. |
20 |
Fallu |
Númberu de fallu; el valor 0 ta reserváu pa "nengún fallu". Si l'elementu vien d'una caxella de fórmula, el valor del fallu ta determináu pola fórmula. |
22 |
Len |
Tamañu del siguiente string, incluyíu'l byte cero de zarru. Si'l tamañu ye un valor impar, incluyíu'l byte cero de zarru, amestar al string un segundu byte cero pa convertilo en par. Por tanto, Len calcular cola fórmula ((StrLen+2)&~1). |
24 |
String |
Sucesión de caráuteres con byte cero de zarru |
24+Llongura |
... |
Elementu siguiente |
Cell array
Utilícense matrices de caxelles pa llamar a árees de caxelles que contienen tantu datos de testu como numbéricos. En LibreOffice Calc una matriz de caxelles definir de la siguiente forma:
Desplazamientu |
Nome |
Descripción |
0 |
Col1 |
Númberu de columna de la esquina cimera esquierda del área de caxelles. La numberación empieza por 0. |
2 |
Row1 |
Númberu de filera de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
4 |
Tab1 |
Númberu de fueya de la esquina cimera esquierda del área de caxelles, cuntáu a partir de 0. |
6 |
Col2 |
Númberu de columna de la esquina inferior derecha del área de caxelles. La numberación empieza por 0. |
8 |
Filera2 |
Númberu de filera de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
10 |
Tab2 |
Númberu de fueya de la esquina inferior derecha del área de caxelles, cuntáu a partir de 0. |
12 |
Count |
Númberu total de cada unu de los siguientes elementos. Les caxelles baleres nun tán incluyíes nel recuentu y nun se tresmiten. |
14 |
Col |
Númberu de columna del elementu. La numberación empieza por 0. |
16 |
Filera |
Númberu de filera del elementu, cuntáu a partir de 0. |
18 |
Tab |
Númberu de fueya del elementu, cuntáu a partir de 0. |
20 |
Fallu |
Númberu de fallu; el valor 0 ta reserváu pa "nengún fallu". Si l'elementu vien d'una caxella de fórmula, el valor del fallu ta determináu pola fórmula. |
22 |
Tipu |
Tipu de conteníu de la caxella, 0 == double, 1 == string |
24 |
Value or Len |
Si'l tipu == 0: Variable IEEE de 8 bytes del tipu double/coma flotante Si'l tipu == 1: Tamañu del siguiente string, incluyíu'l byte cero de zarru. Si'l tamañu ye un valor impar, incluyíu'l byte cero de zarru, amestar al string un segundu byte cero pa convertilo en par. Por tanto, Len calcular cola fórmula ((StrLen+2)&~1). |
26 if Type==1 |
String |
Si'l tipu == 1: Sucesión de caráuteres con byte cero de zarru |
32 or 26+Len |
... |
Elementu siguiente |