View source for IT/Calc/Add-In/Simple Calc Add-In (Italian)

{{Extensions_it}}

=Un semplice add-in per Calc=
Questa è una guida passo passo su come scrivere un semplice componente (un add-in di Calc) per OpenOffice.org (OOo) utilizzando il linguaggio C++. Anche se le istruzioni qui presenti sono scritte per GNU/Linux, questa guida può fornire un'idea su come scrivere componenti anche per altri sistemi operativi.

==Requisiti==
Assicuratevi di aver installato un compilatore C++ e le librerie di sviluppo C standard. È preferibile utilizzare il GNU C++ e le librerie di sviluppo GNU C. La maggior parte delle distribuzioni GNU/Linux li hanno già installati o li forniscono all'interno del loro repository. Per esempio per sistemi Debian GNU/Linux e derivati i pacchetti sono i seguenti: g++, libc6-dev. Per installarli: 
  # apt-get install g++ libc6-dev

Occorre inoltre avere installato anche OOo 2.0 o superiore. La maggior parte delle distribuzioni GNU/Linux lo hanno già di default. Per esempio per sistemi Debian GNU/Linux e derivati è possibile visualizzare tutti i pacchetti di OpenOffice.org presenti con il seguente comando:
  $ apt-cache search openoffice
I pacchetti necessari dovrebbero essere: openoffice.org, openoffice.org-calc 
  # apt-get install openoffice.org openoffice.org-calc

Il pacchetto principale per questo corso è OOo SDK che può essere reperito probabilmente dal repository della propria distribuzione GNU/Linux o da http://download.openoffice.org/680/sdk.html. Per Debian GNU/Linux e derivate dovrebbe essere il pacchetto openoffice.org-dev (la documentazione è openoffice.org-dev-doc)
  # apt-get install openoffice.org-dev

Se viene scaricato il pacchetto .tar.gz, allora occorre decomprimerlo da qualche parte dove avete il permesso di scrittura. Dopo tale operazione il pacchetto .tar.gz può essere cancellato per recuperare spazio su disco. Il file [http://download.openoffice.org/project/development/index.html index.html], presente sul quel sito, è la pagina principale per la documentazione OOo SDK (per chi usa Debian o derivate può installare il pacchetto openoffice.org-dev-doc per avere la documentazione in locale. In questo caso la documentazione si trova sotto /usr/share/doc/openoffice.org-dev/docs e gli esempio sono sotto /usr/lib/openoffice/sdk/examples). È consigliato leggere completamente la documentazione SDK o per lo meno le parti principali prima di provare a scrivere del codice per OOo (per ora ignorate la parte riguardante "La guida d'installazione"). Userete principalmente le seguenti: "Guida di sviluppo", "IDL Reference" e "C++ Reference".

Aprite un terminale, spostatevi nella directory contenente l'SDK (su Debian è: /usr/lib/openoffice/sdk)
Nota: sostituire qui sotto la directory /usr/lib/openoffice (percorso per Debian) con il percorso assoluto dove OOo è stato installato.
Eseguire le seguenti istruzioni (se si è installato il pacchetto Debian occorre essere root o utilizzare il comando sudo se l'utente è autorizzato a farlo):

  echo export OOoSDK='"'`pwd`'"' > OOoSetenv
  echo export PATH='"$OOoSDK/linux/bin:$PATH"' >> OOoSetenv
  echo export OOo='"/usr/lib/openoffice/program"' >> OOoSetenv
  echo export LD_LIBRARY_PATH='"$OOo:$LD_LIBRARY_PATH"' >> OOoSetenv

Nota: controllare che l'utente che poi utilizzerete per l'uso dell'SDK abbia i permessi di lettura su tale file (OOoSetenv).

Questi comandi creano uno script che serve ad impostare i parametri d'ambiente necessari per poter utilizzare l'SDK. Per poter eseguire i comandi contenuti nel file OOoSetenv occorre eseguire:
  $ source OOoSetenv
Potete ora provare per verificare se tutto funziona correttamente; in questo caso non verrà visualizzato nessun messaggio.

Successivamente creeremo un link alla libreria libcppuhelpergcc3.so che dovrebbe essere nella directory $OOo. Per verificare che tutto sia settato correttamente eseguire la seguente istruzione:
  $ ls $OOo/*cppuhelper*
Se viene visualizzato il file libcppuhelpergcc3.so, allora tutto è andato per il verso giusto :-)
Se non si vede tale file, allora ci dovrebbe essere il file libcppuhelpergcc3.so.3, in questo caso eseguire il comando (da root o utilizzando sudo se si è utilizzato il pacchetto Debian):
   ln -s $OOo/libcppuhelpergcc3.so.3 $OOo/libcppuhelpergcc3.so
Questo comando crea il file ricercato con l'istruzione precedente.
Se invece mancano entrambi i file, allora è stato commesso qualche errore nella creazione del file OOoSetenv o non ci si è posizionati nella directory giusta per create tale file.

Infine creare una directory myProjects fornendo all'utente che poi utilizzerete i permessi completi su di essa Nota: le due istruzioni vanno eseguita da root o con sudo se si è installato il pacchetto Debian
  mkdir myProjects
Se si è installato il pacchetto Debian, allora occorre eseguire anche la seguente (sempre da root o con sudo) sostituendo a UtenteNormale la login dell'utente che userete per le esercitazioni
  chown UtenteNormale:UtenteNormale myProjects

In questa directory collocheremo i progetti creati. Ora si può chiudere la shell.

==Introduzione==
Un componente è un add-on (Merriam-Webster dice "add-on: qualcosa (come un accessorio o una funzionalità addizionale) che migliora la cosa a cui è aggiunta") per OOo. Gli add-on sono più specificatamente chiamati componenti di UNO (vedere "3 UNO professionale" e "4 scrivere componenti di UNO" nella "Guida allo sviluppo" dell'SDK). È possibile scrivere componenti per OOo in molti linguaggi di programmazione, tra i quali: C++ e [[JavaEclipseTuto_it|Java]].

Calc è l'applicazione del foglio elettronico di OOo. Ora scriveremo un add-in per Calc, cioè uno speciale componente di UNO, che fornisce un generatore pseudocasuale di numeri (RNG: Random Number Generator).
Per esempio, la funzione "RAND( )" di Calc è un RNG che ritorna un numero pseudocasuale compreso tra 0 e 1. Così facciamo qualcosa di nuovo e scriviamo un RNG che ritorna numero pseudocasuali distribuiti esponenzialmente. In questa guida faremo le stesse operazioni che sono necessarie per generare un componente di UNO e/o un add-in di Calc scritto in C++, così non faremo nulla di specifico agli RNG, ma è giusto un esempio che possiamo implementare per Calc. Per maggiori informazioni si possono vedere i dettagli dei numero pseudocasuali distribuiti esponenzialmente su [http://en.wikipedia.org/wiki/Inverse_transform_sampling_method wikipedia] o [http://mathworld.wolfram.com/ExponentialDistribution.html mathworld].

==Preparazione==
Apriamo una shell, andiamo nella directory dell'SDK (per Debian: $ cd /usr/lib/openoffice/sdk) e impostiamo le variabili d'ambiente con il seguente comando:<br>
Nota: eseguire tutti i comandi seguenti con l'utente normale
  $ source OOoSetenv
e poi entriamo nella directory dei nostri progetti:
  $ cd myProjects
scarichiamo il file [[Media:MyRNG.tar.gz|MyRNG.tar.gz]] (direttamente dal link, salvandolo nella directory myProjects, o con il comando seguente)
  $ wget http://wiki.services.openoffice.org/mwiki/images/3/32/MyRNG.tar.gz
estraiamo il file
  $ tar zxvf MyRNG.tar.gz
entriamo nella directory appena creata
  $ cd myRNG
dove troviamo sei file

==IDL==
Scrivere un componente per OOo inizia sempre con scrivere la sua "specificazione dell'interfaccia". La specificazione dell'interfaccia è semplicemente definire il proprio componente in modo che sia indipendente dal linguaggio utilizzato per implementarlo (come C++ o Java). Per OOo c'è uno speciale linguaggio chiamato UNOIDL (UNO Interface Definition Language: Linguaggio di Definizione di interfacce di UNO) che permette di scrivere le specifiche delle interfacce (vedere "4.2 Usare UNOIDL per specificare nuovi componenti" nella "Guida dello sviluppatore" dell'SDK). UNOIDL è veramente semplice e molto simile al C++. Come puoi aver indovinato, il file RNG.idl è la nostra specifica di interfaccia. Ecco cosa contiene all'interno:

<code>[unoidl]
#ifndef _org_openoffice_sheet_addin_RNG_idl_
#define _org_openoffice_sheet_addin_RNG_idl_

#include <com/sun/star/uno/XInterface.idl>

module org { module openoffice { module sheet { module addin {
	interface XRNG : com::sun::star::uno::XInterface
	{
		double expo( [in] double m );
	};

	service RNG : XRNG;
}; }; }; };
#endif
</code>

Prima cosa è definire un'interfaccia. La nostra interfaccia è XRNG (derivata da XInterface che è l'interfaccia base per qualsiasi componente) che contiene la definizione per la nostra funzione RNG (expo), la quale produce numeri pseudocasuali distribuiti esponenzialmente. Per convenzione i nomi di interfacce iniziano con la lettera X. Poi abbiamo un servizio: RNG, che utilizza la nostra interfaccia XRNG. Leggete il 3° e 4° capitolo della "Guida dello sviluppatore" per maggiori informazioni circa i moduli, le interfacce e i servizi. I componenti di UNO sono collocati sotto il modulo org.openoffice, mentre gli add-in di Calc sono posti sotto org.openoffice.sheet.addin.

==Implementazione==
Un componente di UNO deve contenere le seguenti interfacce: XInterface, XTypeProvider, XServiceInfo e XWeak (vedere "4.4 Interfacce basilari da implementare" della "Gida dello sviluppatore"). Fortunatamente ci sono d'aiuto i template delle classi per il C++ (vedere "4.6 Componenti del C++" della "Guida dello sviluppatore" e WeakImplHelper* under cppu in "C++ Reference") che si prendono cura dell'implementazione di XInterface, XTypeProvider e XWeak. In aggiunta a queste interfacce, che ogni componente UNO deve implementare, un add-in di Calc deve implementare anche le interfacce: XAddIn e XServiceName (Vedere "8.6  Add-in per il foglio di calcolo" della "Guida dello sviluppatore"). Leggendo la documentazione dell'SDK tutti questi concetti diventeranno più chiari. Il file RNG_impl.cxx è la nostra implementazione. In esso è presenta la classe RNG_impl, la definizione della classe con il template WeakImplHelper4

  :class RNG_impl : public ::cppu::WeakImplHelper4< ::org::openoffice::sheet::addin::XRNG,
  ::sheet::XAddIn, lang::XServiceName, lang::XServiceInfo > //4-parameter template

e l'implementazione delle classi XRNG, XAddIn, XServiceName, XServiceInfo e XLocalizable (solo un piccolo dettaglio). In aggiunta a queste sono presenti le funzioni create_RNG_impl (crea una singola istanza del nostro servizio RNG), component_getImplementationEnvironment, component_writeInfo, component_getFactory e la struttura s_component_entries (vedere "4.6  Componendi del C++" della "Guida dello sviluppatore"). Dopo aver letto la documentazione SDK e aver analizzato in maggior dettaglio il file RNG_impl.cxx tutto sarà ragionevolmente più chiaro :).

==Altri file==
Per facilitare lo sviluppo c'è uno script di build con il nome "build" nella directory myRNG. Tale file contiene:

<code>
rm -rf com org *.rdb *.urd

idlc -C -I$OOoSDK/idl RNG.idl

regmerge RNG.rdb /UCR RNG.urd

cppumaker -BUCR -Torg.openoffice.sheet.addin.XRNG -Tcom.sun.star.sheet.XAddIn -Tcom.sun.star.lang.XServiceName -Tcom.sun.star.lang.XServiceInfo -Tcom.sun.star.lang.XTypeProvider -Tcom.sun.star.uno.XWeak -Tcom.sun.star.uno.XAggregation -Tcom.sun.star.lang.XMultiServiceFactory -Tcom.sun.star.uno.XComponentContext -Tcom.sun.star.lang.XSingleComponentFactory -Tcom.sun.star.lang.XSingleServiceFactory -Tcom.sun.star.registry.XRegistryKey 
$OOo/types.rdb RNG.rdb

g++ -O2 -fomit-frame-pointer -c -o RNG_impl.o -DUNX -DGCC -DLINUX -DCPPU_ENV=gcc3 -I. -I$OOoSDK/include RNG_impl.cxx

ld -o libRNG.so -shared -L$OOo --retain-symbols-file symbols.txt RNG_impl.o -lcppuhelpergcc3

rm -rf com org *.urd RNG_impl.o

regcomp -register -r *.rdb -c *.so
</code>

Per i dettagli circa gli strumenti: Idlc, regmerge, cppumaker e regcomp, vedere "4.2.2 Generando il codice sorgente, da definizioni UNOIDL" presente nella guida dello sviluppatore e "Strumenti di sviluppo". Un componente deve esportare solo tre simboli: i nomi delle funzioni che iniziano con "component_" e l'opzione "--retain-symbols-file symbols.txt" passata al linker ld serve proprio per questo scopo. Nel tuo terminale puoi scrivere: 
  man ld
per leggere circa l'opzione --retain-symbols-file.

==Compilazione e test==
Se tutto ha funzionato correttamente basta digitare a terminale:
  $ ./build
Questo comando dovrebbe produrre, senza errori, i file libRNG.so e RNG.rdb; altrimenti abbiamo solo i file _libRNG.so_ e RNG.rdb_ :).\\
Ora bisogna copiare i due file nella directory $OOo:
  # cp *.so *.rdb $OOo
Modifichiamo il file $OOo/unorc:
  # vi $OOo/unorc
aggiungendo la linea:
  $ORIGIN/RNG.rdb
alla fine delle linee inizianti con UNO_TYPES e UNO_SERVICES (vedere "4.6.10 Compilare e testare i componenti C++" nella guida dello sviluppatore). Queste due linee dovrebbero apparire simili a queste:
  :UNO_TYPES=$ORIGIN/types.rdb $ORIGIN/RNG.rdb
  :UNO_SERVICES=$ORIGIN/services.rdb $ORIGIN/RNG.rdb
Salvare ed uscire da vi.

Ora è possibile provare il nostro RNG. Apri OOoCalc, vai nel menù:
  Strumenti -> Macro -> Organizza Macro -> OpenOffice.org Basic
e premi il bottone Modifica nella finestra che si è aperta. Infine copia ed incolla le seguenti linee di codice Basic sovrascrivendo tutto quello già presente:

<code>[oobas]
Sub Main
	mgr = getProcessServiceManager()
	o = mgr.createInstance("org.openoffice.sheet.addin.RNG")
	MsgBox o.expo(10)
End Sub
</code>

Salva ed esegui la tua macro Basic. Dovresti vedre qualcosa del genere:

[[Image:RNG shot.png]]


[[Category:Extensions]]
[[Category:Source_directories]]
[[Category:It.openoffice.org]]