Contenuto

# Componente aggiuntivo per la programmazione in LibreOffice Calc

Il metodo che consente di estendere le funzionalità di Calc mediante componenti aggiuntivi descritto qui di seguito è obsoleto. Le interfacce sono ancora valide e supportate per assicurare la compatibilità con i componenti aggiuntivi esistenti, ma per la programmazione dei nuovi componenti aggiuntivi si consiglia di usare le nuove funzioni API.

LibreOffice Calc può essere espanso con uno o più componenti aggiuntivi, cioè moduli di programmazione esterni che forniscono funzioni supplementari di calcolo per i fogli elettronici. Queste funzioni aggiuntive vengono elencate nella categoria Componente aggiuntivo della Creazione guidata funzione. Se desiderate programmare autonomamente un componente aggiuntivo, seguendo la procedura illustrata di seguito potrete apprendere quali funzioni occorre esportare dalla libreria condivisa DLL esterna per poter aggiungere correttamente il vostro componente aggiuntivo.

LibreOffice cerca una libreria condivisa DLL adatta nella cartella dei componenti aggiuntivi configurata. Affinché sia riconosciuta da LibreOffice, la libreria condivisa DLL deve possedere le proprietà descritte di seguito. Queste informazioni permettono di programmare i propri componenti aggiuntivi per la Creazione guidata funzione di LibreOffice Calc.

## Il concetto di componente aggiuntivo

Ciascuna libreria di componente aggiuntivo include svariate funzioni. Alcune funzioni vengono usate per scopi amministrativi. È possibile 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 DLL dei componenti aggiuntivi

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 aggiuntive 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 | Intero non firmato a 2 byte
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 aggiuntive. Se ad esempio il componente aggiuntivo mette a disposizione 5 funzioni per LibreOffice Calc, nCount sarà uguale a 5.

### GetFunctionData()

Stabilisce tutte le informazioni importanti su una funzione aggiuntiva.

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 di parametri nella funzione aggiuntiva. Questo numero deve essere maggiore di 0 in quanto esiste sempre un 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 adatto del parametro.

char* pInternalName:

Output: nome della funzione visto dall'utente, così come viene visualizzato nella Creazione guidata funzione. Può contenere umlaut.

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 aggiuntiva e dei relativi parametri. Volendo, è possibile 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 di stringhe

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+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:

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