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 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 per poter aggiungere correttamente il vostro add-in.

LibreOffice cerca una adatta nella cartella degli add-in configurata. Affinché sia riconosciuta da LibreOffice, la 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

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

Di seguito viene riportata una descrizione delle funzioni che vengono richiamate nella .

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