Ajuda do LibreOffice 25.2
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 libraryexternal DLL so that the Add-In can be successfully attached.
LibreOffice searches the Add-in folder defined in the configuration for a suitable shared libraryDLL. To be recognized by LibreOffice, the shared libraryDLL 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.
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.
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.
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 | 
Following you will find a description of those functions, which are called at the Shared Libraryexternal DLL.
For all Shared LibraryDLL 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.
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.
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 LibraryDLL. 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.
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.
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.
É 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 | 
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 | 
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 |