Modulo
Contenuto
Indice 🔎︎

# 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 condivisa DLL 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 condivisa add-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 condivisa DLL

Di seguito viene riportata una descrizione delle funzioni che vengono richiamate nella libreria condivisa DLL esterna
.

Per tutte le funzioni della libreria condivisa DLL
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 condivisa DLL
. 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