Contenido
Índice 🔎︎

# Complemento para programación en LibreOffice Calc

El método que se describe a continuación para ampliar Calc mediante complementos es obsoleto. Para garantizar la compatibilidad con los complementos existentes, las interfaces siguen siendo válidas y reciben servicio técnico. Sin embargo, para programar complementos nuevos se deben emplear las funciones nuevas de la API.

LibreOffice Calc puede ampliarse por medio de complementos, módulos de programación externos que brindan prestaciones adicionales para trabajar con hojas de cálculo. El asistente de funciones enumera estos en la categoría Complemento. Si quiere programar su propio complemento, aquí encontrará las funciones que deben exportarse a través de la biblioteca compartidaDLL externa para que el complemento pueda adjuntarse adecuadamente.

LibreOffice searches the Add-in folder defined in the configuration for a suitable shared libraryDLL. To be recognized by LibreOffice, the shared libraryDLL 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 concepto de «complemento»

Cada biblioteca Add-in incluye diversas funciones. Algunas funciones se utilizan con fines administrativos. Puede elegir casi cualquier nombre para sus propias funciones. No obstante, se han de seguir reglas específicas relativas al paso de parámetros. Los convenios exactos de asignación de nombres y llamada de las funciones varían de una plataforma a otra.

### Funciones de la biblioteca compartidaDLL de complementos

Como mínimo deben existir las funciones administrativas GetFunctionCount y GetFunctionData. Con ellas se pueden determinar las funciones, los tipos de parámetros y los valores de retorno. Como valores de retorno se admiten los tipos Doble y Cadena. Como parámetros, las áreas de celdas doble matriz, matriz de cadenas y matriz de celdas se admiten adicionalmente.

Los parámetros se transmiten por referencia. Por tanto, en principio los valores podrían ser modificados. Sin embargo, LibreOffice Calc no admite ningún cambio, dado que no es recomendable que se produzcan modificaciones dentro de una hoja de cálculo.

Las bibliotecas se pueden volver a cargar durante el tiempo de ejecución y su contenido lo pueden analizar las funciones administrativas. Para cada función hay información disponible sobre el número y los tipos de parámetros, los nombres de funciones internas y externas, así como un número administrativo.

Las funciones se activan simultáneamente y devuelven el resultado de modo inmediato. También es posible utilizar funciones de tiempo real (funciones asíncronas), pero debido a su complejidad no serán abordadas en esta Ayuda.

## Aspectos generales sobre la interfaz

El número máximo de parámetros en una función Add-in acoplada a LibreOffice Calc es 16: un valor de retorno y un máximo de 15 parámetros de entrada de funciones.

Los tipos de datos se definen del modo siguiente:

Tipos de datos | Definición
CALLTYPE | con Windows: FAR PASCAL (_far _pascal) en los demás casos: Predeterminado (según el sistema operativo)
USHORT | entero sin signo de 2 bytes
DOUBLE | formato dependiente de la plataforma, de 8 bytes
Paramtype | dependiente de la plataforma, como int PTR_DOUBLE =0 puntero a un double PTR_STRING =1 puntero sobre una cadena de caracteres limitada temporalmente a cero PTR_DOUBLE_ARR =2 puntero a un array de tipo double PTR_STRING_ARR =3 puntero a un array de tipo string PTR_CELL_ARR =4 puntero a un array de tipo cell NINGUNO =5

## Funciones de la biblioteca compartidaDLL

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

For all Shared LibraryDLL 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()

Origina un número de funciones que no incluyen las de administración, en el parámetro de referencia. Cada función tiene asignado un número único comprendido entre 0 y nCount-1. Este código se utiliza posteriormente para las funciones GetFunctionData y GetParameterDescription.

Sintaxis

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parámetro

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 toda la información importante acerca de una función de complemento.

Sintaxis

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

Parámetro

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 LibraryDLL. 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 matrices de caracteres que están implementadas en LibreOffice Calc con el tamaño 256.

### GetParameterDescription()

Proporciona una breve descripción de la función Add-in y de sus parámetros. Si lo desea, esta función puede utilizar para mostrar una descripción de función y parámetros en el Asistente para funciones.

Sintaxis

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

Parámetro

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 caracteres de tamaño 256, implementadas en LibreOffice Calc. Tenga en cuenta que el espacio disponible en el Asistente para funciones es limitado y que no es posible utilizar la totalidad de los 256 caracteres.

## Áreas de celdas

Las tablas siguientes contienen información sobre las estructuras de datos que debe ofrecer un módulo de programa externo para poder transmitir áreas de celdas. En función del tipo de datos, LibreOffice Calc distingue entre tres matrices diferentes.

### Matriz doble

Un área de celda puede transmitirse como parámetro con los valores del tipo número/doble. En LibreOffice Calc, una matriz doble se define de la forma siguiente:

Offset | Nombre | Descripción
0 | Col1 | Número de columna de la esquina superior izquierda del área de celdas. La numeración comienza por 0.
2 | Fila1 | Número de fila de la esquina superior izquierda del área de celdas, contado a partir de 0.
4 | Tab1 | Número de hoja de la esquina superior izquierda del área de celdas, contado a partir de 0.
6 | Col2 | Número de columna de la esquina inferior derecha del área de celdas. La numeración comienza por 0.
8 | Fila2 | Número de fila de la esquina inferior derecha del área de celdas, contado a partir de 0.
10 | Tab2 | Número de hoja de la esquina inferior derecha del área de celdas, contado a partir de 0.
12 | Recuento | Número total de cada uno de los elementos siguientes. Las celdas vacías no se incluyen en el recuento ni se transmiten.
14 | Col | Número de columna del elemento. La numeración comienza por 0.
16 | Fila | Número de fila del elemento, contado a partir de 0.
18 | Tab | Número de hoja del elemento, contado a partir de 0.
20 | Error | Número de error; el valor 0 está reservado para «ningún error». Si el elemento procede de una celda de fórmula, el valor del error está determinado por la fórmula.
22 | Valor | Variable IEEE de 8 bytes del tipo doble/coma flotante
30 | ... | Elemento siguiente

### Matriz de cadenas

Un área de celdas que contiene valores de tipo texto y se transmite como matriz de cadenas. En LibreOffice Calc, una matriz de cadenas se define como sigue:

Offset | Nombre | Descripción
0 | Col1 | Número de columna de la esquina superior izquierda del área de celdas. La numeración comienza por 0.
2 | Fila1 | Número de fila de la esquina superior izquierda del área de celdas, contado a partir de 0.
4 | Tab1 | Número de hoja de la esquina superior izquierda del área de celdas, contado a partir de 0.
6 | Col2 | Número de columna de la esquina inferior derecha del área de celdas. La numeración comienza por 0.
8 | Fila2 | Número de fila de la esquina inferior derecha del área de celdas, contado a partir de 0.
10 | Tab2 | Número de hoja de la esquina inferior derecha del área de celdas, contado a partir de 0.
12 | Recuento | Número total de cada uno de los siguientes elementos. Las celdas vacías no están incluidas en el recuento y no se transmiten.
14 | Col | Número de columna del elemento. La numeración comienza por 0.
16 | Fila | Número de fila del elemento, contado a partir de 0.
18 | Tab | Número de hoja del elemento, contado a partir de 0.
20 | Error | Número de error; el valor 0 está reservado para «ningún error». Si el elemento procede de una celda de fórmula, el valor del error está determinado por la fórmula.
22 | Len | Tamaño del siguiente string, incluido el byte cero de cierre. Si el tamaño es un valor impar, incluido el byte cero de cierre, se añade al string un segundo byte cero para convertirlo en par. Por tanto, Len se calcula con la fórmula ((StrLen+2)&~1).
24 | String | Sucesión de caracteres con byte cero de cierre
24+Len | ... | Elemento siguiente

### Matriz de celdas

Se utilizan matrices de celdas para llamar a áreas de celdas que contienen tanto datos de texto como numéricos. En LibreOffice Calc una matriz de celdas se define de la siguiente forma:

Offset | Nombre | Descripción
0 | Col1 | Número de columna de la esquina superior izquierda del área de celdas. La numeración comienza por 0.
2 | Fila1 | Número de fila de la esquina superior izquierda del área de celdas, contado a partir de 0.
4 | Tab1 | Número de hoja de la esquina superior izquierda del área de celdas, contado a partir de 0.
6 | Col2 | Número de columna de la esquina inferior derecha del área de celdas. La numeración comienza por 0.
8 | Fila2 | Número de fila de la esquina inferior derecha del área de celdas, contado a partir de 0.
10 | Tab2 | Número de hoja de la esquina inferior derecha del área de celdas, contado a partir de 0.
12 | Recuento | Número total de cada uno de los siguientes elementos. Las celdas vacías no están incluidas en el recuento y no se transmiten.
14 | Col | Número de columna del elemento. La numeración comienza por 0.
16 | Fila | Número de fila del elemento, contado a partir de 0.
18 | Tab | Número de hoja del elemento, contado a partir de 0.
20 | Error | Número de error; el valor 0 está reservado para «ningún error». Si el elemento procede de una celda de fórmula, el valor del error está determinado por la fórmula.
22 | Tipo | Tipo de contenido de la celda, 0 == double, 1 == string
24 | Value or Len | Si el tipo == 0: Variable IEEE de 8 bytes del tipo double/coma flotante Si el tipo == 1: Tamaño del siguiente string, incluido el byte cero de cierre. Si el tamaño es un valor impar, incluido el byte cero de cierre, se añade al string un segundo byte cero para convertirlo en par. Por tanto, Len se calcula con la fórmula ((StrLen+2)&~1).
26 if Type==1 | Cadena | Si el tipo == 1: Sucesión de caracteres con byte cero de cierre
32 or 26+Len | ... | Elemento siguiente