Conteníu

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

### Functions of Shared Library AddIn DLL

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

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

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ámetru

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 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ámetru

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.

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ámetru

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

Correición | 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 | Filera1 | 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 | Valor | 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:

Correición | 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 | Filera1 | 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+Len | ... | 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:

Correición | 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 | Filera1 | 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 | Triba | 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