Add-in para programação no LibreOffice Calc

O LibreOffice Calc pode ser expandido através de add-ins, que são módulos de programação externos que disponibilizam funções adicionais para trabalhar com folhas de cálculo. Estes add-ins estão incluídos na lista do Assistente de funções, na categoria Add-in. Se quiser programar um add-in, esta secção informa quais as funções que deverão ser exportadas pela para que o add-in seja anexado com êxito.

O LibreOffice procura a pasta Add-in definida na configuração da adequada. Para que seja reconhecida pelo LibreOffice, a terá de possuir determinadas propriedades, conforme descrito na secção seguinte. Estas informações permitem programar o seu Add-in para o Assistente de funções do 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.

Funções de

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
DUPLO	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

Funções da

De seguida, encontra uma descrição destas funções, que são todas invocadas na .

Para todas as funções da aplicam-se:

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

Saída: valor resultante

Entrada: qualquer número dos tipos (double&, char*, double*, char**, Cell area), em que Cell area corresponde a uma matriz de tipo matriz dupla, matriz em cadeia ou matriz de células.

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:

Saída: referência a uma variável, que deverá conter o número de funções add-in. Por exemplo: se o add-in disponibilizar 5 funções ao LibreOffice Calc, então 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:

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

char* pFuncName:

Saída: nome da função como visualizada pelo utilizador, tal como definido na . Este nome não corresponde ao nome utilizado no Assistente de funções.

USHORT& nParamCount:

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

Paramtype* peType:

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

char* pInternalName:

Saída: nome da função como visualizado pelo utilizador, tal como aparece no Assistente de funções. Pode incluir tremas.

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:

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

USHORT& nParam:

Entrada: indica qual o parâmetro ao qual se refere a descrição; os parâmetros iniciam-se no número 1. Se nParam tiver o valor 0, pressupõe-se que a descrição é facultada em nDesc; nesse caso, pName não tem qualquer significado.

char* pName:

Saída: Assume o nome ou tipo do parâmetro, por exemplo, a palavra "Número" ou "Cadeia" ou "Data" e semelhantes. Implementado no LibreOffice Calc como char[256].

char* pDesc:

Saída: assume a descrição do parâmetro, por exemplo "Valor em relação ao qual se pretende calcular o universo". Implementado no LibreOffice Calc como 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:

Deslocamento	Nome	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:

Deslocamento	Nome	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:

Deslocamento	Nome	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