Suplemento (add-in) para programação no LibreOffice Calc

O LibreOffice Calc pode ser expandido através de suplementos (add-ins), ou seja, módulos de programação externos que oferecem funções adicionais para o trabalho com planilhas. Eles são listados no Assistente de funções, na categoria Suplemento (add-in). Se desejar programar um suplemento (add-in), você poderá aprender aqui quais funções devem ser exportadas pela para que o suplemento possa ser anexado com sucesso.

O LibreOffice procura na pasta Suplementos definida na configuração por uma adequada. Para ser reconhecida pelo LibreOffice, a deve possuir certas propriedades, conforme explicado a seguir. Essa informação permite que você programe seu próprio suplemento (add-in) para o Assistente de funções do LibreOffice Calc.

O Conceito de Suplemento

Cada biblioteca dos Suplementos oferece várias funções. Algumas funções são usadas para propósitos administrativos. Você pode escolher qualquer nome para as funções. Entretanto, elas devem também seguir certas regras no que diz respeito às exigências de parâmetro. As convenções de nome e chamada variam para plataformas diferentes.

Funções da

No mínimo, as funções administrativas GetFunctionCount e GetFunctionData devem existir. Com o uso dessas funções, as funções e os tipos de parâmetros e valores de retorno podem ser determinados. Como valores de retorno, os tipos Double e String possuem suporte. Além disso, como parâmetros, as áreas de célula Double Array, String Array, e Cell Array possuem suporte.

Os parâmetros são transmitidos com o uso de referências. Assim, uma alteração de valores é basicamente possível. Entretanto, essa ação não possui suporte no LibreOffice Calc, pois ela não faria sentido dentro de planilhas.

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

As funções são acionadas em sincronia e retornam seus valores imediatamente. Funções em tempo real (assíncronas) também são possíveis; entretanto, elas não estão explicitadas em detalhes em função de sua complexidade.

Informações gerais sobre a interface

O número máximo de parâmetros em uma função de Suplemento anexada ao LibreOffice Calc é 16: um valor de retorno e um máximo de 15 parâmetros de entrada de função.

Os tipos de dados são definidos como segue:

Tipos de dados	Definição
CALLTYPE	No Windows: FAR PASCAL (_far _pascal) Outros: padrão (padrão específico do sistema operacional)
USHORT	Número inteiro de 2 bytes sem sinal
DOUBLE	Formato de 8 bytes dependente da plataforma
Paramtype	Dependente da plataforma como int PTR_DOUBLE =0 ponteiro para um duplo PTR_STRING =1 ponteiro para uma cadeia de caracteres terminada por zero PTR_DOUBLE_ARR =2 aponta para um vetor duplo PTR_STRING_ARR =3 aponta para a matriz de cadeias de caracteres PTR_CELL_ARR =4 aponta para um vetor de célula NONE =5

Funções da

A seguir, você encontrará uma descrição dessas funções, que são chamadas na .

As regras a seguir se aplicam a todas as funções da :

void CALLTYPE fn(out, in1, in2, ...)

Saída: valor resultante

Entrada: qualquer número dos tipos (double&, char*, double*, char**, Área de célula), onde a Área de célula é um vetor de tipos double array, string array ou cell array.

GetFunctionCount()

Retorna o número de funções sem as funções de gerência do parâmetro de referência. Cada função possui um número exclusivo entre 0 e nCount-1. Esse número será necessário para as funções GetFunctionData e GetParameterDescription mais tarde.

Sintaxe

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parâmetro

USHORT &nCount:

Saída: referência a uma variável que deve conter o número de funções do Suplemento. Por exemplo: Se o Suplemento oferecer 5 funções para o LibreOffice Calc, então nCount=5.

GetFunctionData()

Determina todas as informações importantes sobre uma função de suplemento.

Sintaxe

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

Parâmetro

USHORT& nNo:

Entrada: número da função entre 0 e nCount-1, inclusive.

char* pFuncName:

Saída: Nome da função conforme visto pelo programador e nomeado na . Esse nome não determina o nome usado no Assistente de Funções.

USHORT& nParamCount:

Saída: número de parâmetros na função de Suplemento. Esse número precisa ser maior do que 0, pois sempre há um valor de resultado; o valor máximo é 16.

Paramtype* peType:

Saída: ponteiro para um vetor de exatamente 16 variáveis do tipo Paramtype. As primeiras entradas nParamCount são preenchidas com o tipo adequado de parâmetro.

char* pInternalName:

Saída: nome de função visto pelo usuário como ele aparece no Assistente de Funções. Pode conter tremas.

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

GetParameterDescription()

Fornece uma breve descrição da função Suplemento (add-in) e de seus parâmetros. Opcionalmente, essa função pode ser usada 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:

Entrada: número da função na biblioteca; entre 0 e nCount-1.

USHORT& nParam:

Entrada: indica para qual parâmetro a descrição será oferecida; parâmetros começam em 1. Se nParam for 0, a descrição deverá ser oferecida em pDesc; nesse caso, pName não possui significado.

char* pName:

Saída: Aceita o nome do parâmetro ou o tipo, por exemplo, a palavra "Número" ou "Sequência" ou "Data" e assim por diante. Implementado no LibreOffice Calc como char[256].

char* pDesc:

Saída: Aceita a descrição do parâmetro, por exemplo, "Valor, no qual o universo deve ser calculado." Implementado no LibreOffice Calc como char[256].

pName e pDesc são matrizes de caracteres; implementados no LibreOffice Calc com o tamanho 256. O espaço disponível no Assistente de funções é limitado e os 256 caracteres não podem ser totalmente usados.

Áreas de células

As tabelas a seguir contêm informações sobre quais estruturas de dados devem ser oferecidas por um módulo de programa externo, para que áreas de células possam ser transmitidas. O LibreOffice Calc diferencia três vetores diferentes, dependendo do tipo de dados.

Matriz dupla

Como parâmetro, uma área de célula com valores do tipo Number/Double pode ser transmitida. Um vetor duplo no LibreOffice Calc é definido como a seguir:

Deslocamento	Nome	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de célula. A numeração começa em 0.
2	Linha1	Número de linha no canto superior esquerdo da área de célula. A numeração começa em 0.
4	Tab1	Número de tabela no canto superior esquerdo da área de célula. A numeração começa em 0.
6	Col2	Número de coluna no canto inferior esquerdo da área de célula. A numeração começa em 0.
8	Linha2	Número de linha no canto inferior direito da área de célula. A numeração começa em 0.
10	Tab2	Número de tabela no canto inferior direito da área de célula. A numeração começa em 0.
12	Contagem	Número dos elementos seguintes. Células vazias não são contadas ou passadas.
14	Col	Número da coluna do elemento. A numeração começa em 0.
16	Linha	Número da linha do elemento. A numeração começa em 0.
18	Tab	Número da tabela do elemento. A numeração começa em 0.
20	Erro	Número de erro, onde o valor 0 é definido como "nenhum erro". Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22	Valor	Variável de 8 bytes IEEE do tipo double/ponto flutuante
30	...	Próximo elemento

Matriz de cadeia de caracteres

Uma área de célula, que contém valores de tipo de dados Texto, e é transmitida como um vetor de cadeia de caracteres. Um vetor de cadeia de caracteres no LibreOffice Calc é definido como a seguir:

Deslocamento	Nome	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de célula. A numeração começa em 0.
2	Linha1	Número de linha no canto superior esquerdo da área de célula. A numeração começa em 0.
4	Tab1	Número de tabela no canto superior esquerdo da área de célula. A numeração começa em 0.
6	Col2	Número de coluna no canto inferior esquerdo da área de célula. A numeração começa em 0.
8	Linha2	Número de linha no canto inferior direito da área de célula. A numeração começa em 0.
10	Tab2	Número de tabela no canto inferior direito da área de célula. A numeração começa em 0.
12	Contagem	Número dos elementos seguintes. Células vazias não são contadas ou passadas.
14	Col	Número da coluna do elemento. A numeração começa em 0.
16	Linha	Número da linha do elemento. A numeração começa em 0.
18	Tab	Número da tabela do elemento. A numeração começa em 0.
20	Erro	Número de erro, onde o valor 0 é definido como "nenhum erro". Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22	Len	O comprimento da cadeia de caracteres a seguir, incluindo o byte zero de fechamento. Se o comprimento, incluindo o byte zero de fechamento, for igual a um valor ímpar, um segundo byte zero será adicionado à sequência, para que um valor par seja obtido. Assim, Len é calculado usando ((StrLen+2)&~1).
24	String	String com byte zero de fechamento
24+Len	...	Próximo elemento

Matriz de células

Vetores de células são usados para transmitir áreas de células contendo texto, bem como números. Um vetor de célula no LibreOffice Calc é definido como a seguir:

Deslocamento	Nome	Descrição
0	Col1	Número de coluna no canto superior esquerdo da área de célula. A numeração começa em 0.
2	Linha1	Número de linha no canto superior esquerdo da área de célula. A numeração começa em 0.
4	Tab1	Número de tabela no canto superior esquerdo da área de célula. A numeração começa em 0.
6	Col2	Número de coluna no canto inferior esquerdo da área de célula. A numeração começa em 0.
8	Linha2	Número de linha no canto inferior direito da área de célula. A numeração começa em 0.
10	Tab2	Número de tabela no canto inferior direito da área de célula. A numeração começa em 0.
12	Contagem	Número dos elementos seguintes. Células vazias não são contadas ou passadas.
14	Col	Número da coluna do elemento. A numeração começa em 0.
16	Linha	Número da linha do elemento. A numeração começa em 0.
18	Tab	Número da tabela do elemento. A numeração começa em 0.
20	Erro	Número de erro, onde o valor 0 é definido como "nenhum erro". Se o elemento vier de uma célula de fórmula, o valor de erro será determinado pela fórmula.
22	Tipo	Tipo de conteúdo da célula, 0 == Double, 1 == String
24	Valor ou Len	Se tipo == 0: variável IEEE de 8 bytes do tipo double/ponto flutuante Se tipo == 1: comprimento da cadeia de caracteres a seguir, incluindo o byte zero de fechamento. Se o comprimento incluindo o byte zero de fechamento for igual a um valor ímpar, um segundo byte zero será adicionado à sequência para que um valor par seja obtido. Portanto, Len será calculado utilizando ((StrLen+2)&~1).
26 se tipo==1	String	se tipo == 1: String com byte zero de fechamento
32 ou 26+Len	...	Próximo elemento