Latest revision as of 18:20, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

Alcune interfacce di Apache OpenOffice sono reperibili in molte parti dell'API di Apache OpenOffice. Definiscono gruppi di metodi per le operazioni astratte, applicabili a diversi problemi. Di seguito è fornita una presentazione generale delle più diffuse tra queste interfacce.

L'origine degli oggetti viene invece spiegata in maggiore dettaglio più avanti nel corso del manuale. In questa fase, vengono presentati solo alcuni aspetti astratti degli oggetti per i quali l'API di Apache OpenOffice fornisce delle interfacce centrali.

Creazione di oggetti dipendenti dal contesto

L'API di Apache OpenOffice fornisce due opzioni per la creazione di oggetti. Una è reperibile nella funzione createUnoService menzionata all'inizio di questo capitolo. createUnoService crea un oggetto di uso universale. Questi oggetti e servizi sono noti anche come servizi indipendenti dal contesto.

Oltre ai servizi indipendenti dal contesto, esistono anche i servizi dipendenti dal contesto, i cui oggetti sono utili solo quando utilizzati assieme a un altro oggetto. Un oggetto disegno per un foglio elettronico, ad esempio, può esistere solo insieme a questo documento.

=

                   Interfaccia com.sun.star.lang.XMultiServiceFactory===

Gli oggetti dipendenti dal contesto sono generalmente creati per mezzo di un metodo dell'oggetto, dal quale dipende l'oggetto. Il metodo createInstance, definito nell'interfaccia XMultiServiceFactory, è utilizzato in particolare negli oggetti documento.

L'oggetto disegno di cui sopra, ad esempio, può essere creato come segue utilizzando un oggetto foglio elettronico:

Dim RectangleShape As Object
RectangleShape = _
  Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

Analogamente, potete creare un modello di paragrafo in un documento di testo:

Dim Style as Object
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")

Accesso con nome ad oggetti subordinati

Le interfacce XNameAccess e XNameContainer sono utilizzate negli oggetti che contengono oggetti subordinati, che possono essere identificati utilizzando un nome del linguaggio naturale.

Mentre XNamedAccess consente di accedere ai singoli oggetti, XNameContainer esegue l'inserimento, la modifica e l'eliminazione degli elementi.

=

                   Interfaccia com.sun.star.container.XNameAccess===

Un esempio di utilizzo di XNameAccess è rappresentato dall'oggetto foglio di un foglio elettronico, che combina tutte le pagine all'interno del foglio elettronico. Alle singole pagine si accede utilizzando il metodo getByName da XNameAccess:

Dim Sheets As Object
Dim Sheet As Object
 
Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")

Il metodo getElementNames fornisce una presentazione generale dei nomi di tutti gli elementi e restituisce come risultato un campo di dati contenente i nomi. L'esempio seguente mostra come determinare e visualizzare in un ciclo tutti i nomi degli elementi di un foglio elettronico:

Dim Sheets As Object
Dim SheetNames
Dim I As Integer
 
Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames
 
For I=LBound(SheetNames) To UBound(SheetNames)
  MsgBox SheetNames(I)
Next I

Il metodo hasByName dell'interfaccia XNameAccess rivela se esiste un oggetto subordinato con un particolare nome all'interno dell'oggetto base. L'esempio seguente visualizza quindi un messaggio che informa l'utente se l'oggetto Spreadsheet contiene una pagina di nome Sheet1.

Dim Sheets As Object
 
Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
  MsgBox " Sheet1 available"
Else
  MsgBox "Sheet1 not available"
End If

=

                   Interfaccia com.sun.star.container.XNameContainer===

L'interfaccia XNameContainer esegue l'inserimento, l'eliminazione e la modifica degli elementi subordinati in un oggetto base. Le funzioni responsabili sono insertByName, removeByName e replaceByName.

Di seguito viene riportato un esempio pratico di queste operazioni, che richiama un documento di testo contenente un oggetto StyleFamilies e lo utilizza per rendere disponibili i modelli di paragrafo (ParagraphStyles) del documento.

Dim StyleFamilies As Object
Dim ParagraphStyles As Object
Dim NewStyle As Object   
 
StyleFamilies = Textdoc.StyleFamilies
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")
ParagraphStyles.insertByName("NewStyle", NewStyle)      
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)   
ParagraphStyles.removeByName("OldStyle")

La riga insertByName inserisce lo stile NewStyle sotto al nome dello stesso nome nell'oggetto ParagraphStyles. La riga replaceByName modifica l'oggetto dietro a ChangingStyle in NewStyle. Infine, la chiamata removeByName rimuove l'oggetto dietro ad OldStyle da ParagraphStyles.

Accesso basato su indice a oggetti subordinati

Le interfacce XIndexAccess e XIndexContainer sono utilizzate negli oggetti che contengono oggetti subordinati e che possono essere identificati utilizzando un indice.

XIndexAccess fornisce i metodi per accedere ai singoli oggetti. XIndexContainer fornisce i metodi per inserire e rimuovere elementi.

=

                   Interfaccia com.sun.star.container.XIndexAccess===

XIndexAccess fornisce i metodi getByIndex e getCount per richiamare gli oggetti subordinati. getByIndex fornisce un oggetto con un indice specifico. getCount restituisce il numero di oggetti disponibili.

Dim Sheets As Object
Dim Sheet As Object
Dim I As Integer
 
Sheets = Spreadsheet.Sheets
 
For I = 0 to Sheets.getCount() - 1
  Sheet = Sheets.getByIndex(I)
  ' Editing sheet
Next I

L'esempio mostra un ciclo che viene eseguito attraverso tutti gli elementi del foglio, uno dopo l'altro, e salva un riferimento verso ciascuno nella variabile oggetto Sheet. Quando si lavora con gli indici, getCount restituisce il numero di elementi. Gli elementi in getByIndex sono tuttavia numerati a partire da 0. La variabile conteggio del ciclo pertanto esegue da 0 a getCount()-1.

=

                   Interfaccia com.sun.star.container.XIndexContainer===

L'interfaccia XIndexContainer fornisce le funzioni insertByIndex e removeByIndex. I parametri sono strutturati nello stesso modo delle funzioni corrispondenti in XNameContainer.

Accesso iterativo ad oggetti subordinati

In alcuni casi, un oggetto può contenere un elenco di oggetti subordinati non identificabili tramite un nome o un indice. In queste situazioni, sono idonee le interfacce XEnumeration e XenumerationAccess, che forniscono un meccanismo tramite il quale è possibile passare passo per passo tutti gli elementi subordinati di un oggetto, senza dover utilizzare l'identificazione diretta.

=

                   Interfacce com.sun.star.container.XEnumeration e XenumerationAccess===

L'oggetto base deve fornire l'interfaccia XEnumerationAccess, che contiene solo un metodo createEnumeration. Questo restituisce un oggetto ausiliario, che a sua volta fornisce l'interfaccia XEnumeration con i metodi hasMoreElements e nextElement. Attraverso di essi è possibile accedere agli oggetti subordinati.

L'esempio seguente attraversa tutti i paragrafi di un testo:

Dim ParagraphEnumeration As Object
Dim Paragraph As Object
 
ParagraphEnumeration = Textdoc.Text.createEnumeration
 
While ParagraphEnumeration.hasMoreElements()
  Paragraph = ParagraphEnumeration.nextElement()
Wend

L'esempio crea prima un oggetto ausiliario ParagraphEnumeration. Questo restituisce gradualmente i singoli paragrafi del testo in un ciclo. Il ciclo viene terminato non appena il metodo hasMoreElements restituisce il valore False, che segnala il raggiungimento della fine del testo.