Add-in per la programmazione in LibreOffice Calc
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 può essere espanso con uno o più add-in, cioè moduli di programmazione esterni che forniscono funzioni supplementari di calcolo per i fogli elettronici. Queste funzioni aggiuntive vengono elencate nella categoria Add-in della Creazione guidata funzione. Se desiderate programmare autonomamente un add-in, seguendo la procedura illustrata di seguito potrete apprendere quali funzioni occorre esportare dalla libreria condivisaDLL esterna per poter aggiungere correttamente il vostro add-in.
LibreOffice cerca una libreria condivisa DLL adatta nella cartella degli add-in configurata. Affinché sia riconosciuta da LibreOffice, la libreria condivisa DLL deve possedere le proprietà descritte di seguito. Queste informazioni permettono di programmare i propri add-in per la Creazione guidata funzione di 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.
Funzioni della libreria condivisaadd-in DLL
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 |
Funzioni di libreria condivisaDLL
Di seguito viene riportata una descrizione delle funzioni che vengono richiamate nella libreria condivisaDLL esterna.
Per tutte le funzioni della libreria condivisaDLL si applicano le seguenti regole:
void CALLTYPE fn(out, in1, in2, ...)
Output: valore del risultato
Input: qualsiasi numero dei tipi double&, char*, double*, char**, area celle, dove area celle è una matrice del tipo double array (matrice doppia), string array (matrice di stringhe) o cell array (matrice di celle).
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: riferimento alla variabile che deve contenere il numero delle funzioni add-in. Se ad esempio add-in mette a disposizione 5 funzioni per LibreOffice Calc, nCount sarà uguale a 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: numero di funzione tra 0 e nCount-1 incluso.
char* pFuncName:
Output: nome della funzione nel programma, così come viene chiamata nella libreria condivisaDLL. Tale denominazione non influenza il nome della funzione visualizzato nella Creazione guidata funzione.
USHORT& nParamCount:
Output: numero dei parametri della funzione add-in. Questo numero deve essere maggiore di 0, in quanto c'è sempre un valore di risultato. Il valore massimo è 16.
Paramtype* peType:
Output: puntatore su array con 16 variabili esatte del tipo paramtype. Le prime voci nParamCount vengono riempite con il tipo del relativo parametro.
char* pInternalName:
Output: nome della funzione visto dall'utente, così come viene visualizzato nella Creazione guidata funzione. Può contenere accenti.
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: numero della funzione all'interno della biblioteca tra 0 e nCount-1.
USHORT& nParam:
Input: indica per quale parametro deve essere fornita la descrizione. I parametri partono da 1. Se nParam è uguale a 0, la descrizione della funzione viene fornita in pDesc, in questo caso pName è irrilevante.
char* pName:
Output: aggiunge il nome e il tipo di parametro, ad esempio la parola "numero", "stringa", "data", eccetera. Implementato in LibreOffice Calc come char[256].
char* pDesc:
Output: aggiunge la descrizione del parametro, ad esempio "valore in base al quale calcolare l'universo". Implementato in LibreOffice Calc come 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:
Scarto |
Nome |
Descrizione |
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:
Scarto |
Nome |
Descrizione |
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+Lunghezza |
... |
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:
Scarto |
Nome |
Descrizione |
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 |