Add-in per la programmazione in LibreOffice Calc

Icona di avvertenza

Il metodo che consente di estendere le funzionalità di Calc mediante add-in descritto qui di seguito è obsoleto. Le interfacce sono ancora valide e supportate per assicurare la compatibilità con gli add-in esistenti, ma per la programmazione dei nuovi add-in si consiglia di usare le nuove funzioni 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 so that the Add-In can be successfully attached.

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

Il concetto di add-in

Ciascuna libreria add-in include svariate funzioni. Alcune funzioni vengono usate per scopi amministrativi. Potete attribuire qualsiasi nome alle vostre funzioni. È tuttavia necessario seguire determinate regole per quanto concerne la trasmissione dei parametri. Le convenzioni relative a nomi e modi di chiamata variano a seconda della piattaforma.

Functions of

Il requisito minimo è che siano presenti almeno le funzioni amministrative GetFunctionCount e GetFunctionData. In questo modo è possibile determinare le funzioni, i tipi di parametri e i valori da restituire. Per i valori da restituire, sono supportati i tipi Double e String. Per i parametri, sono supportate anche le aree di celle Double Array, String Array e Cell Array.

I parametri vengono trasmessi come riferimento e quindi in linea di massima potete modificare i valori. Tuttavia questa funzione non viene supportata da LibreOffice Calc poiché non è logico eseguire un'operazione di questo tipo in un foglio elettronico.

Le librerie possono essere ricaricate al momento dell'esecuzione (runtime) e il loro contenuto può essere analizzato con le funzioni amministrative. Per ogni funzione, vengono indicati il numero e il tipo dei parametri, i nomi delle funzioni interne ed esterne e un numero amministrativo.

Le funzioni vengono avviate contemporaneamente e restituiscono immediatamente il risultato ottenuto. Potete utilizzare anche funzioni di tipo realtime (funzioni asincrone), ma a causa della loro complessità non è possibile procedere a una spiegazione in questa sede.

Informazioni generali d'interfacciamento con le funzioni

Il numero massimo di parametri delle funzioni add-in collegate a LibreOffice Calc è 16: un valore restituito e un massimo di 15 parametri.

I tipi di dati vengono definiti nella seguente maniera:

Tipi di dati

Definizione

CALLTYPE

in Windows: FAR PASCAL (_far _pascal)

altri sistemi operativi: default (predefinito specifico in base al sistema operativo)

USHORT

2 Byte unsigned Integer

DOUBLE

Formato a 8 byte a seconda della piattaforma

Paramtype

in base alla piattaforma come int

PTR_DOUBLE =0 puntatore a un double

PTR_STRING =1 puntatore a una stringa che termina con zero

PTR_DOUBLE_ARR =2 puntatore a un double array

PTR_STRING_ARR =3 puntatore a uno string array

PTR_CELL_ARR =4 puntatore a un cell array

NONE =5


functions

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

For all 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()

Fornisce il numero delle funzioni senza le funzioni di gestione nel parametro di riferimento. Ogni funzione ha un numero univoco tra 0 e nCount-1. Questo numero servirà successivamente per le funzioni GetFunctionData e GetParameterDescription.

Sintassi

void CALLTYPE GetFunctionCount(USHORT& nCount)

Parametro

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()

Stabilisce tutte le informazioni importanti su una funzione add-in.

Sintassi

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

Parametro

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

I parametri pFuncName e pInternalName sono char array a cui LibreOffice Calc assegna una dimensione di 256 caratteri.

GetParameterDescription()

Fornisce una breve descrizione della funzione add-in e dei relativi parametri. Volendo, potete utilizzare questa funzione per mostrare la descrizione di una funzione e dei relativi parametri nella Creazione guidata funzione.

Sintassi

void CALLTYPE GetParameterDescription(USHORT& nNo, USHORT& nParam, char* pName, char* pDesc)

Parametro

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 sono matrici di caratteri (char array), che in LibreOffice Calc vengono implementate con una dimensione di 256 caratteri. Osservate, tuttavia, che lo spazio disponibile nella Creazione guidata funzione è limitato e che i 256 caratteri non possono essere interamente utilizzati.

Aree di celle

Le seguenti tabelle forniscono le informazioni necessarie sulle strutture di dati che devono essere messe a disposizione da un modulo di programma esterno per trasmettere le aree di celle. LibreOffice Calc esegue una distinzione in base al tipo di dati tra tre diverse matrici.

Matrice doppia

Potete trasmettere come parametro un'area di celle con valori del tipo numero/double. In LibreOffice Calc una matrice doppia è definita come segue:

Offset

Name

Description

0

Col1

Numero di colonna dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

2

Riga1

Numero di riga dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

4

Tab1

Numero di tabella dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

6

Col2

Numero di colonna dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

8

Riga2

Numero di riga dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

10

Tab2

Numero di tabella dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

12

Conta

Numero dei seguenti elementi. Le celle vuote non vengono conteggiate, né trasmesse.

14

Col

Numero di colonna dell'elemento. La numerazione parte da 0.

16

Riga

Numero di riga dell'elemento. La numerazione parte da 0.

18

Tab

Numero di tabella dell'elemento. La numerazione parte da 0.

20

Errore

Numero di errore: il valore 0 significa "nessun errore". Se l'elemento proviene da una cella contenente una formula, il valore di errore viene stabilito dalla formula.

22

Valore

Variabile IEEE a 8 byte del tipo double/virgola mobile

30

...

Elemento successivo


Matrice stringa

Un'area di celle che contiene un testo viene trasmessa come una matrice stringa. In LibreOffice Calc una matrice stringa è definita nella seguente maniera:

Offset

Name

Description

0

Col1

Numero di colonna dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

2

Riga1

Numero di riga dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

4

Tab1

Numero di tabella dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

6

Col2

Numero di colonna dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

8

Riga2

Numero di riga dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

10

Tab2

Numero di tabella dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

12

Conta

Numero dei seguenti elementi. Le celle vuote non vengono conteggiate, né trasmesse.

14

Col

Numero di colonna dell'elemento. La numerazione parte da 0.

16

Riga

Numero di riga dell'elemento. La numerazione parte da 0.

18

Tab

Numero di tabella dell'elemento. La numerazione parte da 0.

20

Errore

Numero di errore: il valore 0 significa "nessun errore". Se l'elemento proviene da una cella contenente una formula, il valore di errore viene stabilito dalla formula.

22

Lunghezza

Lunghezza della stringa successiva, incluso il byte nullo di chiusura. Se la lunghezza del byte nullo di chiusura incluso è uguale a un valore dispari, viene aggiunto un secondo byte nullo di chiusura per ottenere un valore pari. La lunghezza viene calcolata con ((StrLen+2)&~1).

24

Stringa

Sequenza caratteri con byte nullo di chiusura

24+Len

...

Elemento successivo


Matrice cella

Le matrici di celle (cell array) vengono utilizzate per richiamare aree di celle contenenti testo e numeri. Una matrice di celle in LibreOffice Calc viene definita come segue:

Offset

Name

Description

0

Col1

Numero di colonna dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

2

Riga1

Numero di riga dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

4

Tab1

Numero di tabella dell'angolo superiore sinistro dell'area di celle. La numerazione parte da 0.

6

Col2

Numero di colonna dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

8

Riga2

Numero di riga dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

10

Tab2

Numero di tabella dell'angolo inferiore destro dell'area di celle. La numerazione parte da 0.

12

Conta

Numero dei seguenti elementi. Le celle vuote non vengono conteggiate, né trasmesse.

14

Col

Numero di colonna dell'elemento. La numerazione parte da 0.

16

Riga

Numero di riga dell'elemento. La numerazione parte da 0.

18

Tab

Numero di tabella dell'elemento. La numerazione parte da 0.

20

Errore

Numero di errore: il valore 0 significa "nessun errore". Se l'elemento proviene da una cella contenente una formula, il valore di errore viene stabilito dalla formula.

22

Tipo

Tipo di contenuto della cella, 0 == double, 1 == string

24

Valore o Lunghezza

Con il tipo == 0: Variabile IEEE a 8 byte del tipo double/virgola mobile

Con il tipo == 1: lunghezza stringa successiva, incluso il byte nullo di chiusura. Se la lunghezza del byte nullo di chiusura incluso è uguale a un valore dispari, viene aggiunto un secondo byte nullo di chiusura per ottenere un valore pari. La lunghezza viene calcolata con ((StrLen+2)&~1).

26 if type==1

Stringa

Con il tipo == 1: sequenza caratteri con byte nullo di chiusura

32 o 26+Lunghezza

...

Elemento successivo