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

warning

O método de estender o Calc usando suplementos (add-ins) descrito a seguir está desatualizado. As interfaces ainda estão válidas e ainda há suporte, para garantir a compatibilidade com suplementos (add-ins) existentes, mas para programar novos, você deve usar as novas funções API.


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

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


♥ Doe para nosso projeto! ♥