Conteúdo

# Add-in para programação no LibreOffice Calc

O método de expansão do Calc descrito nesta secção está desatualizado. As interfaces ainda são válidas e suportadas pelo programa com o objetivo de assegurar a compatibilidade com os suplementos existentes mas, para programar novos suplementos o utilizador deve utilizar as novas funções API.

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 shared library external DLL so that the Add-In can be successfully attached.

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

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

## Shared Library DLL functions

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

For all Shared Library DLL 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 Shared Library DLL. 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