Complemento para programación en LibreOffice Calc

Icono de advertencia

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

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

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

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


¡Necesitamos su ayuda!