Complemento para programación en LibreOffice Calc

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 para 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 para que el complemento pueda adjuntarse adecuadamente.

$[nombre de la oficina] busca en la carpeta añadir en la configuración una adecuada. Para ser reconocida por $[nombre de la oficina], la debe tener ciertas propiedades, como se explica a continuación. Esta información le permite programar su propio añadir en para el Asistente de funciones de $[nombre de la oficina] 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

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

A continuación encontrará una descripción de esas funciones, que se llaman en la .

Para todas las funciones , se aplica lo siguiente:

void CALLTYPE fn(out, in1, in2, ...)

Salida: Valor resultante

Entrada: Cualquier número de tipos (doble&, carácter*, doble*, carácter**, Área de celdas), donde el Área de celdas es una matriz de los tipos matriz doble, matriz de cadenas, o matriz de celda.

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:

Salida: Referencia a una variable, que se supone que contiene el número de funciones del Add-In. Por ejemplo: Si el Add-In proporciona 5 funciones para $[nombre de la oficina] Calc, entonces nContar=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:

Entrada: Número de función entre 0 y nCount-1, inclusive.

char* pFuncName:

Salida: Nombra la función tal y como la ve el programador, tal y como se nombra en la . Este nombre no determina el nombre utilizado en el Asistente para funciones.

USHORT& nParamCount:

Salida: Número de parámetros de la función Add-In. Este número debe ser mayor que 0, porque siempre hay un valor de resultado; el valor máximo es 16.

Paramtype* peType:

Salida: Puntero a una matriz de exactamente 16 variables de tipo de parámetro. Las primeras entradas de nContar parámetro se llenan con el tipo de parámetro adecuado.

char* pInternalName:

Salida: Nombre de la función tal y como lo ve el usuario, tal y como aparece en el Asistente de funciones. Puede contener diéresis.

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

Tipo de llamada luna descripción de parámetros(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Parámetro

USHORT& nNo:

Entrada: Número de la función en la biblioteca; entre 0 y nCount-1.

USHORT& nParam:

Input: Indica, para qué parámetro se proporciona la descripción; los parámetros comienzan en 1. Si nParam es 0, se supone que la propia descripción se proporciona en pDesc; en este caso, pName no tiene ningún significado.

char* pName:

Output: Toma el nombre o tipo de parámetro, por ejemplo, la palabra "Número" o "Cadena" o "Fecha", etc. Implementado en LibreOffice Calc como carácter[256].

char* pDesc:

Salida: recoge la descripción del parámetro; por ejemplo: «Valor al que se va a calcular el universo». Implementado en LibreOffice Calc como 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:

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

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

Desplazamiento	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	Valor o 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 o 26+Len	...	Elemento siguiente