Add-in para programação no LibreOffice Calc

LibreOffice Calc can be expanded by Add-Ins, which are external programming modules providing additional functions for working with spreadsheets. These are listed in the Function Wizard in the Add-In category. If you would like to program an Add-In yourself, you can learn here which functions must be exported by the so that the Add-In can be successfully attached.

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.

O conceito de Add-in

Cada biblioteca add-in disponibiliza diversas funções. Algumas dessas funções são utilizadas para fins administrativos. Pode escolher praticamente qualquer nome para as funções do utilizador. No entanto, estas devem seguir algumas regras relativas à transferência de parâmetros. As convenções exatas relativas aos nomes e às formas de invocação variam conforme a plataforma.

Functions of

Devem existir, pelo menos, as funções administrativas GetFunctionCount e GetFunctionData. Através destas funções, é possível determinar não só as funções como também os tipos de parâmetros e valores de resposta. Em relação aos valores de resposta, são permitidos os tipos Double e String. Adicionalmente, são também aceites como parâmetros as áreas de células Double Array, String Array e Cell Array.

Os parâmetros são transferidos utilizando referências. Assim, é possível alterar estes valores. No entanto, não é permitido no LibreOffice Calc porque não faz sentido no contexto das folhas de cálculo.

As bibliotecas podem ser recarregadas durante a execução e os seu conteúdo pode ser analisado pelas funções administrativas. Para cada função, estão disponíveis informações sobre a contagem e tipo de parâmetros, nomes das funções internas e externas e um número administrativo.

As funções são invocadas em sincronia e devolvem os resultados imediatamente. Também são permitidas funções em tempo real (funções assíncronas); no entanto, não são explicadas em pormenor devido à sua complexidade.

Informações gerais sobre a interface

O número máximo de parâmetros numa função add-in do LibreOffice Calc é 16: um valor de resposta e um máximo de 15 parâmetros de entrada da função.

Os tipos de dados são definidos da seguinte forma:

Tipos de dados	Definição
CALLTYPE	No Windows: FAR PASCAL (_far _pascal) Outros: padrão (padrão específico do sistema operativo)
USHORT	Inteiros positivos de 2 Bytes
DOUBLE	formato dependente de plataforma de 8 bytes
Paramtype	Dependente da plataforma, como int PTR_DOUBLE =0 ponteiro para um duplo PTR_STRING =1 ponteiro para uma cadeia terminada em 0 PTR_DOUBLE_ARR =2 ponteiro para uma matriz dupla PTR_STRING_ARR =3 ponteiro para uma matriz de cadeia PTR_CELL_ARR =4 ponteiro para uma matriz de células NONE =5

functions

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()

Devolve o número de funções sem contar com as funções de gestão do parâmetro de referência. Cada função tem um número exclusivo entre 0 e nCount-1. Este número será necessário para as funções GetFunctionData e GetParameterDescription, posteriormente.

Sintaxe

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 todas as informações importantes sobre uma função add-in.

Sintaxe

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.

Os parâmetros pFuncName e pInternalName são matrizes de caracteres, implementadas com o tamanho 256 no LibreOffice Calc.

GetParameterDescription()

Disponibiliza uma breve descrição da função e dos seus parâmetros. Como opção, esta função pode ser utilizada para mostrar uma descrição de função e parâmetro no Assistente de funções.

Sintaxe

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 e pDesc são matrizes de caracteres; implementadas no LibreOffice Calc com o tamanho 256. Tenha em atenção que o espaço disponível no Assistente de funções é limitado e que não é possível utilizar os 256 caracteres na totalidade.

Áreas de células

As seguintes tabelas contêm informações que permitem determinar as estruturas de dados a fornecer por um módulo de programa externo de forma a transferir áreas de células. LibreOffice Calc distingue entre três matrizes diferentes, dependendo do tipo de dados.

Matriz dupla

É possível transferir uma área de células com valores do tipo Número/Duplo como parâmetro. Uma matriz dupla no LibreOffice Calc é definida da seguinte forma:

Offset	Name	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de células. A numeração inicia-se no 0.
2	Linha1	O número de linha no canto superior esquerdo da área de células; a numeração inicia-se no 0.
4	Tab1	O número de tabela no canto superior esquerdo da área de células; a numeração inicia-se no 0.
6	Col2	O número de coluna no canto inferior direito da área de células. A numeração inicia-se no 0.
8	Linha2	O número de linha no canto inferior direito da área de células; a numeração inicia-se no 0.
10	Tab2	O número de tabela no canto inferior direito da área de células; a numeração inicia-se no 0.
12	Contar	Número dos seguintes elementos. As células vazias não são consideradas na contagem nem transferidas.
14	Col	Número de coluna do elemento. A numeração inicia-se no 0.
16	Linha	Número de linha do elemento; a numeração inicia-se no 0.
18	Tabulação	Número de tabela do elemento; a numeração inicia-se no 0.
20	Erro	Número do erro, onde o valor 0 é definido como "sem erro." Se o elemento derivar de uma célula de fórmula, o valor do erro é determinado pela fórmula.
22	Valor	variável IEEE de 8 bytes do tipo double/floating point
30	...	Próximo elemento

Matriz de cadeia

Uma área de células que contém valores do tipo de dados Text e é transferida como cadeia. Uma matriz em cadeia do LibreOffice Calc define-se da seguinte forma:

Offset	Name	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de células. A numeração inicia-se no 0.
2	Linha1	O número de linha no canto superior esquerdo da área de células; a numeração inicia-se no 0.
4	Tab1	O número de tabela no canto superior esquerdo da área de células; a numeração inicia-se no 0.
6	Col2	O número de coluna no canto inferior direito da área de células. A numeração inicia-se no 0.
8	Linha2	O número de linha no canto inferior direito da área de células; a numeração inicia-se no 0.
10	Tab2	O número de tabela no canto inferior direito da área de células; a numeração inicia-se no 0.
12	Contar	Número dos seguintes elementos. As células vazias não são consideradas na contagem nem transferidas.
14	Col	Número de coluna do elemento. A numeração inicia-se no 0.
16	Linha	Número de linha do elemento; a numeração inicia-se no 0.
18	Tabulação	Número de tabela do elemento; a numeração inicia-se no 0.
20	Erro	Número do erro, onde o valor 0 é definido como "sem erro." Se o elemento derivar de uma célula de fórmula, o valor do erro é determinado pela fórmula.
22	Len	Comprimento da cadeia de texto seguinte, incluindo o byte zero final. Se o comprimento incluindo o byte zero final corresponder a um número ímpar, é adicionado um segundo byte zero para se conseguir um número par. Por conseguinte, Len é calculado utilizando ((StrLen+2)&~1).
24	Cadeia	Cadeia com byte zero final
24+Len	...	Próximo elemento

Matriz de célula

As matrizes de células são utilizadas para invocar áreas de células que contêm texto e números. Uma matriz de célula no LibreOffice Calc define-se da seguinte forma:

Offset	Name	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de células. A numeração inicia-se no 0.
2	Linha1	O número de linha no canto superior esquerdo da área de células; a numeração inicia-se no 0.
4	Tab1	O número de tabela no canto superior esquerdo da área de células; a numeração inicia-se no 0.
6	Col2	O número de coluna no canto inferior direito da área de células. A numeração inicia-se no 0.
8	Linha2	O número de linha no canto inferior direito da área de células; a numeração inicia-se no 0.
10	Tab2	O número de tabela no canto inferior direito da área de células; a numeração inicia-se no 0.
12	Contar	Número dos seguintes elementos. As células vazias não são consideradas na contagem nem transferidas.
14	Col	Número de coluna do elemento. A numeração inicia-se no 0.
16	Linha	Número de linha do elemento; a numeração inicia-se no 0.
18	Tabulação	Número de tabela do elemento; a numeração inicia-se no 0.
20	Erro	Número do erro, onde o valor 0 é definido como "sem erro." Se o elemento derivar de uma célula de fórmula, o valor do erro é determinado pela fórmula.
22	Tipo	Tipo do conteúdo da célula, 0 == Duplo, 1 == Cadeia
24	Value ou Len	Se type == 0: variável IEEE de 8 bytes do tipo double/floating point Se tipo == 1: comprimento da cadeia de texto seguinte, incluindo o byte zero final. Se o comprimento, incluindo o byte zero final, corresponder a um número ímpar, é adicionado à cadeia um segundo byte zero para se conseguir um número par. Por conseguinte, Len é calculado utilizando ((StrLen+2)&~1).
26 se type==1	Cadeia	Se tipo == 1: Cadeia de texto com byte zero final
32 ou 26+Len	...	Próximo elemento