View source for IT/Documentation/BASIC Guide/Interface Overview

{{DISPLAYTITLE:Presentazione generale di alcune interfacce centrali}}
{{IT/Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/UNO Tools
|NextPage=Documentation/BASIC Guide/Documents
|api=block
}}
 
Alcune interfacce di {{OOo}} sono reperibili in molte parti dell'API di {{OOo}}. Definiscono gruppi di metodi per le operazioni astratte, applicabili a diversi problemi. Di seguito è fornita una presentazione generale di alcune delle interfacce più diffuse. 

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 {{OOo}} fornisce delle interfacce centrali.

== Creazione di oggetti dipendenti dal contesto ==

L'API di {{OOo}} fornisce due opzioni per la creazione di oggetti. Una è reperibile nella funzione <tt>createUnoService</tt> menzionata all'inizio di questo capitolo. <tt>createUnoService</tt> 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 <tt>com.sun.star.lang.XMultiServiceFactory</tt>===

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

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

<source lang="oobas">
Dim RectangleShape As Object
RectangleShape = _
  Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")
</source>

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

<source lang="oobas">
Dim Style as Object
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")
</source>

== Accesso con nome ad oggetti subordinati ==

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

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

===                     Interfaccia <tt>com.sun.star.container.XNameAccess</tt>===

Un esempio di utilizzo di <tt>XNameAccess</tt> è 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 <tt>getByName</tt> da <tt>XNameAccess</tt>: 

<source lang="oobas">
Dim Sheets As Object
Dim Sheet As Object

Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")
</source>

Il metodo <tt>getElementNames</tt> 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: 

<source lang="oobas">
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
</source>

Il metodo <tt>hasByName</tt> dell'interfaccia <tt>XNameAccess</tt> 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 <tt>Spreadsheet</tt> contiene una pagina di nome <tt>Sheet1</tt>.

<source lang="oobas">
Dim Sheets As Object

Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
  MsgBox " Sheet1 available"
Else
  MsgBox "Sheet1 not available"
End If
</source>

===                     Interfaccia <tt>com.sun.star.container.XNameContainer</tt>===

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

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

<source lang="oobas">
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")            
</source>

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

== Accesso basato su indice a oggetti subordinati ==

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

<tt>XIndexAccess</tt> fornisce i metodi per accedere ai singoli oggetti. <tt>XIndexContainer</tt> fornisce i metodi per inserire e rimuovere elementi.

===                     Interfaccia <tt>com.sun.star.container.XIndexAccess</tt>===

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

<source lang="oobas">
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
</source>

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 <tt>Sheet</tt>. Quando si lavora con gli indici,  <tt>getCount</tt> restituisce il numero di elementi. Gli elementi in <tt>getByIndex</tt> sono tuttavia numerati a partire da 0. La variabile conteggio del ciclo pertanto esegue da 0 a <tt>getCount()-1</tt>.

===                     Interfaccia <tt>com.sun.star.container.XIndexContainer</tt>===

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

== 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 <tt>XEnumeration</tt> e <tt>XenumerationAccess</tt>, 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 <tt>com.sun.star.container.XEnumeration</tt> e <tt>XenumerationAccess</tt>===

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

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

<source lang="oobas">
Dim ParagraphEnumeration As Object
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements()
  Paragraph = ParagraphEnumeration.nextElement()
Wend
</source>

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

{{PDL1}}
{{InterWiki_Languages_BasicGuide|articletitle=Documentation/BASIC Guide/Interface Overview}}