Complemento para programación en LibreOffice Calc

LibreOffice Calc se puede expandir mediante Add-Ins, módulos externos de programación que proporcionan funciones adicionales para trabajar con las hojas de cálculo. Dichas funciones se muestran en el Asistente para funciones de la categoría Add-In. Si desea programar un add-in, aquí se indican las funciones que debe exportar la para poder adjuntar el add-in de forma satisfactoria.

LibreOffice busca en la carpeta de complementos definida en la configuración una adecuada. Para que LibreOffice la reconozca, la debe tener determinadas propiedades, tal como se explica a continuación. Esta información le permitirá programar su propio complemento para el asistente de funciones de 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

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

A continuación, se presenta una descripción de dichas funciones, que pueden activarse en la .

Las indicaciones siguientes se aplican a todas las funciones de :

void CALLTYPE fn(salida, entrada1, entrada2, ...)

Salida: Resultado

Entrada: Cualquier número de tipos (double&, char*, double*, char**, área de celdas), donde área de celdas es una matriz de tipos matriz de double (entero de doble precisión), matriz de cadenas o matriz de celdas.

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 debe contener el número de funciones Add-in. Por ejemplo, si Add-in ofrece 5 funciones en LibreOffice Calc, nCount=5.

GetFunctionData()

Determina toda la información importante acerca de una función Add-in.

Sintaxis

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

Parámetro

USHORT& nNo:

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

char* pFuncName:

Salida: Nombre de la función que ve el programador, como se denomina en la . Este nombre no determina el nombre que se utiliza en el Asistente para funciones.

USHORT& nParamCount:

Salida: Número de parámetros de la función Add-in. Dicho número debe ser superior a 0, ya que siempre hay un resultado; el valor máximo es 16.

Paramtype* peType:

Salida: Puntero sobre un array que contiene exactamente 16 variables del tipo paramtype. Las primeras entradas de nParamCount se completan con el tipo del parámetro correspondiente.

char* pInternalName:

Salida: Nombre de la función que ve el usuario, como aparece en el Asistente para funciones. Puede contener el carácter umlaut.

Los parámetros pFuncName y pInternalName son arrays de char que están implementados 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:

Entrada: Número de la función dentro de la biblioteca, comprendido entre 0 y nCount-1.

USHORT& nParam:

Entrada: Indica el parámetro al cual debe referirse la descripción; los parámetros comienzan por 1. Si el parámetro nParam es 0, debe ofrecerse la descripción de la propia función en pDesc; en este caso, pName carece de significado.

char* pName:

Salida: Acepta el nombre y el tipo de parámetro; por ejemplo, la palabra "número" o "cadena de caracteres" o "fecha", etc. En LibreOffice Calc está implementado como char[256].

char* pDesc:

Salida: Acepta la descripción del parámetro; por ejemplo, "valor según el cual debe calcularse el universo". En LibreOffice Calc está implementado 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 arrays diferentes.

Array de tipo doble

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

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	Row1	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	Count	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	Value	Variable IEEE de 8 bytes del tipo double/coma flotante
30	...	Elemento siguiente

String array

Un área de celdas que contiene valores de tipo texto es transmitido como string array. En LibreOffice Calc, un array de string se define como sigue:

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	Row1	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	Count	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+Largo	...	Elemento siguiente

Cell array

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	Row1	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	Count	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	String	Si el tipo == 1: Sucesión de caracteres con byte cero de cierre
32 or 26+Len	...	Elemento siguiente