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

LibreOffice searches the Add-in folder defined in the configuration for a suitable . To be recognized by LibreOffice, the 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

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

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

For all 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 Add-in.

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

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

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

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


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:

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

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!