Tipi di dati: enumerazioni, strutture e sequenze
Le API consentono di accedere alla programmazione di OpenOffice.Org e di tutti i suoi servizi, con un'orientamento agli oggetti, che consentono di ottenere diversi servizi contemporaneamente. Sono fondamentali per l'utilizzo delle macro. Si trovano qui.
Questo è una esemplificazione di come è strutturata un'API:
com.sun.star--> è la radice comune a tutte le API di OpenOffice.Org
.sheet --> è il nome del modulo, che cataloga al suo interno i diversi servizi. Come un libro ha diverse sezioni, con all'interno i diversi capitoli, così le API hanno diversi moduli, con all'interno i diversi servizi.
.SpreadsheetDocument --> è il nome del servizio, di cui si possono utilizzare le diverse interfacce. Le interfacce sono chiamate Xqualcosa, e sono disponibili all'interno del servizio stesso in maniera immediata. Delle interfacce a noi interessano solo i comandi che ci offrono, definiti metodi. Il servizio inoltre dispone di proprietà. Per chiarire, mentre con i metodi si eseguono delle azioni, con le proprietà potremmo ad esempio decidere che il servizio sia rosso o giallo.
o, meglio, com.sun.star.sheet.SpreadsheetDocument
I servizi vengono dichiarati come una variabile qualsiasi e sono del tipo oggetto. Per fare un esempio terra-terra, rispetto alle altre variabili, che sono piatte per così dire, gli oggetti hanno invece diverse (inter)facce, come un cubo. E noi dei servizi usiamo proprio le interfacce. Per essere del tutto chiari (spero) dopo che abbiamo aperto un servizio possiamo utilizzare tutti i metodi delle interfacce collegate.
Ci sono servizi che devono essere inseriti all'interno di un contesto, tipo le celle esistono solo in un foglio di calcolo o in una tabella, e servizi che sono autonomi, tipo i colori definiti nell'OpenOffice.org. Mentre i servizi autonomi, o indipendenti, vengono richiamati con il comando CreateUnoService(NomeDelServizio), i servizi dipendenti si basano sul servizio generico Desktop, che fa parte del modulo frame, cioè: com.sun.star.frame.Desktop(), il quale comunque viene richiamato con il comando CreateUnoService.
I moduli principali di OOo sono:
com.sun.star.sheet --> contiene .SpreadsheetDocument() per i fogli di calcolo
com.sun.star.text --> contiene .TextDocument() per i fogli di scrittura
com.sun.star.table --> fornisce i servizi per le tabelle/fogli di calcolo sia nei fogli di calcolo che nei documenti di testo
com.sun.star.presentation --> per lavorare con le presentazioni
com.sun.star.drawing --> per usare la grafica
com.sun.star.chart --> contiene .ChartDocument() per i grafici
com.sun.star.frame --> contiene .Desktop() che serve per aprire file o crearne di nuovi.
I servizi dispongono, come detto sopra, di proprietà. Le proprietà hanno un nome ed un valore: ad esempio la proprietà di nome Colore può avere il Valore giallo, rosso, verde, ecc. Sono perciò matrici, che possiamo creare utilizzando le sequenze viste qui sotto.
Esistono tre tipi di dati nelle API: enumerazioni, strutture e sequenze.
consistono in una serie di costanti nominative, utilizzate per definire il comportamento dei metodi utilizzati: ad esempio com.sun.star.sheet.FillDirection è un'enumerazione che ha le seguenti costanti:
TO_BOTTOM , TO_TOP, TO_RIGHT, TO_LEFT
e quindi, quando si utilizza (come qui), si ha la possibilità di scegliere una delle quattro costanti, in caso si voglia riempire le celle del foglio di calcolo verso il basso (TO_BOTTOM), oppure verso l'alto (TO_TOP), ecc. Nelle pagine sulle API sono chiamate enum .
Le strutture servono a definire delle coppie di valori, o matrici, che vengono usate come opzioni durante l'uso di metodi: ad esempio, il metodo .print ha diverse opzioni, ognuna con un nome e un valore.
La struttura deve essere creata in maniera simile ad un servizio, cioè con:
Dim matrice_struttura(0) As New com.sun.star.beans.PropertyValue
ed assegnata ad una variabile matrice, con un indice pari al numero di opzioni che vogliamo definire. Se io voglio definire l'opzione CopyCount, devo quindi creare la matrice con indice 0, che equivale ad 1 coppia di nome-valore.
Quindi alla matrice devo dare il nome .Name e il valore .Value, come abbiamo fatto sopra. Per passare altri valori, basterà assegnare alla matrice un indice più alto, ed assegnare i successivi matrice_struttura(1).Name e matrice_struttura(1).Value . Alla fine avrò quindi:
option explicit
Sub Main
Dim oDoc As Object
Dim mArray(0) as New com.sun.star.beans.PropertyValue
oDoc = ThisComponent
mArray(0).Name = "CopyCount"
mArray(0).Value = 2
oDoc.print(mArray())
End Sub
Così stampiamo due copie del documento attivo.
Le sequenze forniscono (o richiedono) una matrice di valori: sono segnalate come sequence <tipo_di_variabile> , ad esempio:
Option Explicit
Sub Main
Dim oDoc As Object
Dim mServizi As Variant
Dim sServizi As String
Dim n As Integer
oDoc = ThisComponent
mServizi = oDoc.getAvailableServiceNames()
For n = LBound(mServizi) To UBound(mServizi)
sServizi = sServizi & " " & mServizi(n)
Next n
msgBox sServizi
End Sub
Otteniamo così una lista di tutti i servizi disponibili di oDoc.
Se invece dobbiamo creare una sequenza per passarla come parametro, dobbiamo utilizzare il comando New(), in maniera del tutto simile alle strutture viste sopra.
Esistono alcune interfacce che sono disponibili in tutti i servizi di OOo che possono supportarle, in funzione della tipologia del documento. Ad esempio, il documento Foglio_di_calcolo contiene come standard tre Tabelle, a cui è possibile accedere con il comando getByIndex() oppure getByName(). Queste interfacce quindi si possono usare dovunque ne abbiate bisogno. Qui di seguito ne indico alcune, che verranno utilizzate più avanti.
Con questa interfaccia, fornita dal servizio OfficeDocument, possiamo utilizzare alcuni comandi per il salvataggio dei file:
.store() --> esegue il salvataggio così com'è, però se il documento non è stato salvato in precedenza, e quindi non ha un nome, non funziona;
.storeAsURL ( sURL, array_vuota()) --> esegue il salvataggio assegnando un nome al documento: nella variabile array_vuota() è facoltativo l'inserimento di dati, può essere utile nel caso si voglia inserire un filtro (FilterName) oppure sovrascrivere file esistenti senza problemi (OverWrite);
.hasLocation() --> restituisce SI/NO se il documento è o non è stato salvato in precedenza;
.isReadOnly() --> restituisce SI/NO se il documento è o non è in sola lettura;
.isModified() --> come sopra se è o non è stato modificato dall'ultimo salvataggio.
ad esempio:
option explicit
Sub Main
Dim oDoc as Object
Dim sUrl as string
Dim mArray()
oDoc = ThisComponent
if oDoc.hasLocation() Then
oDoc.store()
else
sUrl = "file:///home/io/Desktop/" & inputBox ("Nome del file: ") & inputBox ("Estensione (.odt; .ods; ecc.): ")
oDoc.storeAsURL( sUrl , mArray())
endif
End Sub
salva il file corrente se era già stato salvato in precedenza, sennò chiede il nome e il tipo di estensione e lo salva.
Quest'interfaccia permette di accedere a servizi non supportati dal documento in cui si sta lavorando, con il metodo .createInstance("servizio")
Per esempio, in un foglio di calcolo, per utilizzare il modulo della grafica, faremo:
oggetto_grafico_che_vogliamo_creare = oFoglioDiCalcolo.createInstance("com.sun.star.drawing.servizio_a_cui_vogliamo_accedere")
il servizio potrebbe essere .EllipseShape oppure .RectangleShape ecc.
Fornisce il metodo .Print(matrice()), .setPrinter(matrice()) e
getPrinter(matrice()) e le proprietà .printer e .name
Il
metodo .Print richiede un matrice (che comunque si può creare
vuota) che accetta diverse opzioni, per esempio CopyCount, Sort e
Pages.
Sub Main
Dim oDoc As Object
oDoc = ThisComponent
Dim mArray(0) as New com.sun.star.beans.PropertyValue
mArray(0).Name = "CopyCount"
mArray(0).Value = 2
oDoc.print(mArray()) REM attenzione a passare la matrice senza indice
End Sub
stampa due copie del documento corrente.
Questa interfaccia consente l'accesso per nome a parti del documento che supportano di essere indicizzate, in particolare per i fogli di calcolo, e fornisce i seguenti comandi:
getByName() --> accede alla tabella di un documento foglio di calcolo (per esempio)
hasByName() --> verifica se esiste la tabella di un documento di foglio di calcolo (per esempio)
getElementNames --> fornisce un elenco di tutte le tabelle di un foglio di calcolo (per esempio)
Il primo si può usare così (vedi Sub di accesso ad un file):
oSheet = oDoc.Sheets.getByName ("Tabella1")
Il secondo può servire così:
If oDoc.Sheets.hasByName("Tabella1")
Then
oSheet = oDoc.Sheets.getByName ("Tabella1")
End
If
se non siamo sicuri che ci sia la Tabella1.
Il terzo deve essere usato con un costrutto ulteriore, per prelevare i vari nomi dalla lista creata:
Option Explicit
Sub Main
Dim oDoc As Object
Dim Lista
Dim Indice As Integer
oDoc = ThisComponent
Lista = oDoc.Sheets.getElementNames REM qui viene creata la lista e memorizzata nella variabile Lista
For Indice=LBound(Lista) To UBound(Lista) REM viene utilizzato un ciclo, che viene eseguito dall'indice più basso (LBound –> Lower) all'indice più alto (UBound –> Upper) di Lista, che legge uno per uno i dati presenti nella variabile Lista
MsgBox Lista(Indice) REM viene visualizzato il dato presente in Lista con l'Indice attuale
Next Indice
end Sub
Questa interfaccia permette l'utilizzo del metodo getByIndex() e getCount().
oSheet = oDoc.Sheets.getByIndex(0) --> assegna ad oSheet l'elemento con indice 0 del documento foglio di calcolo, quindi la prima tabella.
iNrTabelle = oDoc.Sheets.getCount() --> assegna ad iNrTabelle il numero delle tabelle del documento foglio di calcolo, quindi come standard 3.
Per accedere ad un file, ci sono alcune possibilità:
accedere ad un file già aperto, i cui servizi sono già in esecuzione, con il comando ThisComponent, per cui se abbiamo un foglio di calcolo già aperto e su una macro scriviamo il seguente comando:
Dim oFoglioDiCalcolo As Object REM far precedere il nome della variabile da una piccola o in caso sia un oggetto, è un modo semplice per ricordarsi che tipo di variabile è, alla stessa maniera s per stringa, i per intero, ecc. (La lista completa è la seguente: b = boolean, s = string, o = object/service/interface, m = array, n = integer/long, f = float/double, e = enumeration, a = structure, v = variant)
oFoglioDiCalcolo = ThisComponent
otteniamo tutti i servizi del foglio di calcolo, che sono quelli di com.sun.star.sheet.SpreadsheetDocument
possiamo aprile un file esistente, con i seguenti comandi:
REM dichiarazione variabili
Dim oFoglioDiCalcolo As Object
Dim oDesktop As Object
Dim sUrl As String
Dim mMatriceVuota() REM creiamo una matrice vuota, senza indicare il numero degli elementi
REM accesso ai servizi
oDesktop = createUnoService("com.sun.star.frame.Desktop") REM prima di tutto, otteniamo il servizio Desktop
sUrl = "file:///home/io/provediformulevarie.ods" REM in questa variabile inseriamo il percorso del file, in questo caso su un sistema Linux
sUrl = "file:///C:/documenti/io/provediformulevarie.ods" REM come sopra, ma in questo caso su un sistema win.
oFoglioDiCalcolo = oDesktop.loadComponentFromURL(sUrl,"_blank",0,mMatriceVuota()) REM Il servizio Desktop ci permette di caricare il foglio di calcolo (o il foglio di writer, o la presentazione, ecc.) con il metodo loadComponentFromURL()
end Sub
Il metodo loadComponentFromURL fornito dal servizio Desktop richiede alcuni parametri, che per i nostri fini semplifichiamo in: il primo parametro deve essere la stringa della locazione del file, il secondo "_blank", il terzo 0, il quarto la matrice vuota da noi creata.
Nota sugli Url: in caso di spazi, bisogna usare un carattere di escape, per cui per entrare nella directory C:\document and settings\io\ bisognerà tradurre il percorso del file nella notazione standard Url, dalla normale scrittura c:\bla\bla.ods, con la funzione ConvertToUrl("c:\bla\bla.ods")
possiamo creare un nuovo file, con lo stesso comando loadComponentFromURL usato sopra, sostituendo alla stringa sUrl la seguente:
sUrl = "private:factory/scalc" REM per creare un foglio di calcolo
sUrl = "private:factory/swriter" REM per creare un foglio di scrittura
ecc. per tutti gli altri tipi di file di OOo.
Dopo aver aperto un file, abbiamo accesso ai metodi forniti dalle interfacce del servizio specifico del file. Però la struttura dei servizi di OOo è molto ramificata, per cui:
un servizio può comprendere altri servizi dello stesso modulo o di altri moduli
un servizio può comprendere interfacce importate da altri servizi (ci sono infatti interfacce che sono comuni a più servizi).
Per comprendere meglio, dobbiamo utilizzare la funzione supportsService("servizio_da_verificare_se_è_attivo"), nel seguente modo (con un foglio di calcolo aperto):
Option Explicit
Sub Main
Dim oDoc As Object
Dim serv_1 As Boolean
Dim serv_2 As Boolean
Dim serv_3 As Boolean
Dim oSheet As Object
Dim oCursor As Object
REM qui apriamo il servizio "Documento foglio di calcolo" collegato al Desktop
oDoc = ThisComponent
serv_1 = oDoc.supportsService("com.sun.star.sheet.SpreadsheetDocument")
REM qui apriamo il servizio "Tabella 1 del foglio di calcolo" collegato al "Documento foglio di calcolo"
oSheet = oDoc.Sheets.getByIndex(0) REM in alternativa, si può utilizzare l'abbreviazione: oDoc.Sheets(0)
serv_2 = oSheet.supportsService("com.sun.star.sheet.Spreadsheet")
REM qui apriamo il servizio "Cursore del foglio di calcolo" collegato alla "Tabella 1 del foglio di calcolo" collegato al "Documento foglio di calcolo"
oCursor = oSheet.createCursor()
serv_3 = oCursor.supportsService("com.sun.star.table.CellCursor")
print serv_1 & ", " & serv_2 & ", " & serv_3
end Sub
La procedura sopra restituirà
Come si può notare dagli ultimi passaggi, il metodo createCursor() fornito dal servizio Spreadsheet, ci permette di aprire il servizio com.sun.star.table.CellCursor in maniera assolutamente rapida.
Per comprendere le pagine sulle API prendiamo ad esempio questa pagina.
Lasciamo perdere la prima riga, che comincia con Overview, e
prendiamo la seconda, che comincia con Methods' Summary. Questa riga
rimanda alla varie parti della stessa pagina.
La riga successiva
(com.sun.star.container) è il modulo che contiene
l'interfaccia XIndexAccess.
Sotto viene riportato che questa
interfaccia esporta l'interfaccia XElementAccess, per cui se è
disponibile la prima, è disponibile anche la seconda.
Poi
c'è una breve descrizione, quindi c'è Methods' Summary,
in cui sono indicati i vari metodi possibili, e quindi Methods'
Details, con il dettaglio sull'uso dei metodi:
- getCount fornisce
un risultato di tipo Long e non richiede alcun parametro (le () sono
vuote).
- getByIndex invece fornisce un elemento di qualsiasi
tipo, richiede un parametro di tipo Long che viene definito nella
guida Index, e può restituire i segnali di errore
com.sun.star.lang.eccetera.
Per non rendere la panoramica troppo lunga e complicata, le altre spiegazioni generali verranno fornite all'interno delle sezioni relative ai fogli di calcolo, ai fogli di scrittura, ecc., in base alla necessità.
Ultima modifica: