Difference between revisions of "EN/Documentation/BASIC Guide/StarDesktop"

Revision as of 18:21, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

Quando si utilizzano i documenti, due servizi in particolare vengono impiegati molto frequentemente:

• Il servizio com.sun.star.frame.Desktop, simile al servizio core di Apache OpenOffice, fornisce le funzioni per l'oggetto cornice di Apache OpenOffice, in cui sono

classificate tutte le finestre dei documenti. Tramite questo servizio potrete inoltre creare, aprire e importare documenti.

• Le funzionalità di base per i singoli oggetti documento sono garantite dal servizio com.sun.star.document.OfficeDocument, che fornisce metodi per salvare, esportare e stampare i documenti.

Il servizio com.sun.star.frame.Desktop si apre automaticamente all'avvio di Apache OpenOffice. Per eseguire questa attività, Apache OpenOffice Basic crea un oggetto raggiungibile tramite il nome globale StarDesktop.

L'interfaccia più importante delloStarDesktop è com.sun.star.frame.XComponentLoader, che include il metodo loadComponentFromURL, responsabile della creazione, dell'importazione e dell'apertura dei documenti.

Il nome dell'oggetto StarDesktop risale a StarOffice 5, in cui tutte le finestre dei documenti erano integrate in un'unica applicazione comune denominata StarDesktop. Nella presente versione di Apache OpenOffice, lo StarDesktop non è più visibile. Il nome StarDesktop è stato tuttavia mantenuto per l'oggetto cornice di Apache OpenOffice, poiché indica chiaramente che si tratta dell'oggetto base dell'intera applicazione.

L'oggetto StarDesktop sostituisce l'oggetto Application di StarOffice 5, che in precedenza fungeva da oggetto radice. A differenza del vecchio oggetto Application, questo oggetto è tuttavia principalmente responsabile dell'apertura di nuovi documenti. Le funzioni residenti nel vecchio oggetto Application per il controllo della rappresentazione su schermo di Apache OpenOffice (ad esempio FullScreen, FunctionBarVisible, Height, Width, Top, Visible) non sono più utilizzate.

Template:Documentation/Note

ThisComponent

ThisComponent in genere restituisce lo stesso oggetto di StarDesktop.CurrentComponent, con un vantaggio fondamentale: durante l'esecuzione dall'ambiente di sviluppo integrato di Basic, il debug o l'esplorazione, StarDesktop restituisce l'ambiente di sviluppo integrato di Basic. Probabilmente questa non rappresenta la soluzione ideale. ThisComponent restituisce il documento attivo più recente.

Informazioni di base sui documenti in Apache OpenOffice

Quando si utilizzano documenti Apache OpenOffice, è utile conoscere alcune informazioni di base sulla gestione dei documenti in Apache OpenOffice. Tra queste, le modalità di strutturazione dei nomi dei file per i documenti Apache OpenOffice, nonché il formato di salvataggio dei file.

Nomi dei file nella notazione URL

Poiché Apache OpenOffice è un'applicazione indipendente dalla piattaforma, per i nomi di file utilizza la notazione URL (che è indipendente da qualsiasi sistema operativo) come definito nell'Internet Standard RFC 1738. I nomi di file standard che utilizzano questo sistema iniziano con il prefisso file:/// seguito dal percorso locale. Se il nome del file contiene sottodirectory, queste sono separate da una singola barra, non dalla barra retroversa generalmente utilizzata in Windows. Il seguente percorso fa riferimento al file test.odt nella directory doc sull'unità C:.

file:///C:/doc/test.odt

Per convertire i nomi di file locali in URL, Apache OpenOffice dispone della funzione ConvertToUrl. Per convertire un URL in un nome di file locale, Apache OpenOffice dispone della funzione ConvertFromUrl:

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' supplies file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  supplies (under Windows) c:\doc\test.odt

L'esempio converte un nome di file locale in un URL e lo visualizza in una finestra di messaggio, quindi converte un URL in un nome di file locale e visualizza anche quest'ultimo.

Lo standard Internet RFC 1738, su cui si basa, consente l'uso dei caratteri 0-9, a-z e A-Z. Tutti gli altri caratteri sono inseriti negli URL come codici di escape. Per eseguire questa operazione, vengono convertiti nei relativi valori esadecimali nel set di caratteri ISO 8859-1 (ISO-Latin) e sono preceduti da un segno di percentuale. Pertanto, uno spazio in un nome di file locale diventa ad esempio %20 nell'URL.

Formato XML

Apache OpenOffice utilizza un formato di file basato su XML. Tramite l'uso di XML, l'utente ha la possibilità di aprire e modificare i file anche in altri programmi.

Compressione dei file

Poiché il linguaggio XML si basa su un normale file di testo, i file risultanti sono generalmente di grandi dimensioni. Apache OpenOffice, quindi, li comprime e li salva in formato ZIP. Per mezzo delle opzioni del metodo storeAsURL, l'utente può salvare direttamente i file XML originali. Vedere Opzioni del metodo storeAsURL.

Creazione, apertura e importazione di documenti

I documenti vengono aperti, importati e creati utilizzando il metodo

StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)

Il primo parametro di loadComponentFromURL specifica l'URL del file associato.

Come secondo parametro, loadComponentFromURL prevede un nome per l'oggetto cornice della finestra che Apache OpenOffice crea internamente a scopo di amministrazione. Il nome predefinito _blank è generalmente specificato in questo punto e ciò garantisce che Apache OpenOffice crei una nuova finestra. In alternativa, potete specificare anche _hidden, che garantisce che il documento corrispondente sia caricato ma rimanga invisibile.

Utilizzando questi parametri, l'utente può aprire un documento di Apache OpenOffice, poiché agli ultimi due parametri si possono assegnare segnaposto (valori di esempio):

Dim Doc As Object
Dim Url As String
Dim Dummy() 'It is an (empty) array of PropertyValues
 
Url = "file:///C:/test.odt"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)

La chiamata precedente apre il file text.odt e lo visualizza in una nuova finestra.

In questo modo potete aprire in Apache OpenOffice Basic un numero qualsiasi di documenti, che potrete quindi modificare utilizzando gli oggetti documento restituiti.

Template:Documentation/Note

Sostituzione del contenuto della finestra del documento

I valori _blank e _hidden per il parametro Frame assicurano che Apache OpenOffice crei una nuova finestra per ogni chiamata da loadComponentFromURL. In alcune situazioni, è utile sostituire il contenuto di una finestra già esistente. In questo caso, l'oggetto cornice della finestra dovrebbe contenere un nome esplicito. Tale nome non deve iniziare con un trattino di sottolineatura. Inoltre, il parametro SearchFlags deve essere impostato in modo che venga creata la struttura corrispondente, qualora non esista già. La costante corrispondente per SearchFlags è:

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL

L'esempio seguente mostra come sostituire il contenuto di una finestra aperta con l'ausilio del parametro di cornice e di SearchFlags:

Dim Doc As Object
Dim Dummy() 
Dim Url As String
Dim SearchFlags As Long
 
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL
Url = "file:///C:/test.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)
MsgBox "Press OK to display the second document."
 
Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

L'esempio apre prima il file test.odt in una nuova finestra con il nome MyFrame. Una volta confermata la finestra di messaggio, sostituisce il contenuto della finestra con il file test2.odt.

Opzioni del metodo loadComponentFromURL

Il quarto parametro della funzione loadComponentFromURL è un campo di dati PropertyValue, che offre a Apache OpenOffice diverse opzioni per aprire e creare documenti. Il campo di dati deve fornire una struttura PropertyValue per ogni opzione in cui il nome dell'opzione nonché il valore associato sono salvati come stringa.

loadComponentFromURL supporta le opzioni seguenti:

AsTemplate (Boolean)

Se il valore è True, carica un nuovo documento senza titolo dall'URL dato. Se il valore è False, i file dei modelli vengono caricati per la modifica.

CharacterSet (String)

Definisce il set di caratteri su cui si basa un documento.

FilterName (String)

Specifica un filtro speciale per la funzione loadComponentFromURL. I nomi di filtro disponibili sono definiti nel file \share\config\registry\instance\org\openoffice\office\TypeDetection.xml.

FilterOptions (String)

Definisce le opzioni aggiuntive per i filtri.

JumpMark (String)

Una volta aperto un documento, passa alla posizione definita in JumpMark.

Password (String)

Trasferisce una password per un file protetto.

ReadOnly (Boolean)

Carica un documento in sola lettura.

L'esempio seguente mostra come aprire un file di testo separato da virgole in Apache OpenOffice Calc utilizzando l'opzione FilterName.

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
 
Url = "file:///C:/csv.doc"
FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv ({{OOo}} Calc)"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

Il campo di dati FileProperties copre precisamente un valore perché registra un'opzione. La proprietà Filtername definisce se Apache OpenOffice utilizza un filtro di testo di Apache OpenOffice Calc per aprire i file.

Creazione di nuovi documenti

Apache OpenOffice crea automaticamente un nuovo documento se il documento specificato nell'URL è un modello.

In alternativa, se è necessario solo un documento vuoto senza alcun adattamento, potete specificare un URL private:factory:

Dim Dummy() 
Dim Url As String
Dim Doc As Object
 
Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

La chiamata crea un documento vuoto di Apache OpenOffice Writer.

Oggetti documento

La funzione loadComponentFromURL presentata nella sezione precedente restituisce un oggetto documento. Supporta il servizio com.sun.star.document.OfficeDocument, che a sua volta fornisce due interfacce centrali:

• L'interfaccia com.sun.star.frame.XStorable, responsabile del salvataggio dei documenti.
• L'interfaccia com.sun.star.view.XPrintable, che contiene i metodi per la stampa dei documenti.

Salvataggio ed esportazione di documenti

                   I documenti di Apache OpenOffice vengono salvati direttamente tramite l'oggetto documento. A tale scopo è disponibile il metodo store dell'interfaccia com.sun.star.frame.XStorable:

Doc.store()

La chiamata funziona solo se al documento è già stata assegnata una quantità di memoria, tuttavia ciò non avviene con i nuovi documenti. In questo esempio, è utilizzato il metodo storeAsURL. Tale metodo è definito anche in com.sun.star.frame.XStorable e può essere utilizzato per definire la posizione del documento:

Dim URL As String
Dim Dummy()
 
Url = "file:///C:/test3.odt"
Doc.storeAsURL(URL, Dummy())

Oltre ai metodi sopracitati, com.sun.star.frame.XStorable fornisce anche alcuni metodi utili per il salvataggio dei documenti. Tali metodi sono:

hasLocation()

Specifica se al documento è già stato assegnato un URL.

isReadonly()

Specifica se un documento ha la protezione di sola lettura.

isModified()

Specifica se un documento è stato modificato dall'ultimo salvataggio.

Il codice per il salvataggio di un documento può essere ampliato da queste opzioni in modo che il documento venga salvato solo se l'oggetto è stato effettivamente modificato e il nome del file viene ricercato solo se effettivamente necessario:

If (Doc.isModified) Then
  If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
    Doc.store()
  Else
    Doc.storeAsURL(URL, Dummy())
  End If
End If

L'esempio controlla prima se il documento pertinente è stato modificato dall'ultimo salvataggio. Il processo di salvataggio prosegue solo in caso di esito positivo. Se al documento è già stato assegnato un URL e non si tratta di un documento in sola lettura, viene salvato nell'URL preesistente. Se invece non ha un URL o è stato aperto in sola lettura, verrà salvato in un nuovo URL.

Opzioni del metodo storeAsURL

In modo analogo a quanto avviene per il metodo loadComponentFromURL, potete specificare alcune opzioni anche sotto forma di campo di dati PropertyValue utilizzando il metodo storeAsURL. Tali opzioni determinano la procedura utilizzata da Apache OpenOffice per il salvataggio di un documento. storeAsURL dispone delle opzioni seguenti:

CharacterSet (String)

Definisce il set di caratteri su cui si basa un documento.

FilterName (String)

Specifica un filtro speciale per la funzione loadComponentFromURL. I nomi di filtro disponibili sono definiti nel file \share\config\registry\instance\org\openoffice\office\TypeDetection.xml.

FilterOptions (String)

Definisce le opzioni aggiuntive per i filtri.

Overwrite (Boolean)

Consente la sovrascrittura di un file preesistente senza una ricerca.

Password (String)

Trasferisce la password per un file protetto.

Unpacked (Boolean)

Salva il documento (non compresso) nelle sottodirectory.

L'esempio seguente mostra come potrete utilizzare l'opzione Overwrite insieme a storeAsURL:

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
' ... Initialize Doc 
 
Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(sUrl, mFileProperties())

L'esempio salva quindi Doc con il nome specificato se esiste già un file con quel nome.

Stampa di documenti

Analogamente al salvataggio, è possibile stampare direttamente i documenti tramite l'oggetto documento. A tale scopo è disponibile il metodo Print dell'interfaccia com.sun.star.view.Xprintable. Nella sua forma più semplice, la chiamata print è:

Dim Dummy()
 
Doc.print(Dummy())

Come nel caso del metodo loadComponentFromURL, il parametro Dummy è un campo di dati PropertyValue attraverso il quale Apache OpenOffice può specificare diverse opzioni di stampa.

Opzioni del metodo print

Il metodo print prevede un campo di dati PropertyValue come parametro, che riflette le impostazioni della finestra di stampa di Apache OpenOffice:

CopyCount (Integer)

Specifica il numero di copie da stampare.

FileName (String)

Stampa il documento nel file specificato.

Collate (Boolean)

Informa la stampante che le pagine delle copie devono essere ordinate.

Sort (Boolean)

Ordina le pagine quando si stampano diverse copie (CopyCount > 1).

Pages (String)

Contiene l'elenco delle pagine da stampare (sintassi come specificata nella finestra di dialogo).

L'esempio seguente mostra come stampare diverse pagine di un documento utilizzando l'opzione Pages:

Dim Doc As Object
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue
 
PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
Doc.print(PrintProperties())

Selezione e impostazioni della stampante

L'interfaccia com.sun.star.view.XPrintable fornisce la proprietà Printer, che seleziona la stampante. Tale proprietà accetta un campo di dati PropertyValue con le impostazioni seguenti:

Name (String)

Specifica il nome della stampante.

PaperOrientation (Enum)

Specifica l'orientamento del foglio (valori com.sun.star.view.PaperOrientation.PORTRAIT per il formato verticale e com.sun.star.view.PaperOrientation.LANDSCAPE per il formato orizzontale).

PaperFormat (Enum)

Specifica il formato del foglio di carta (ad esempio, com.sun.star.view.PaperFormat.A4 per DIN A4 o com.sun.star.view.PaperFormat.Letter per US letter).

PaperSize (Size)

Specifica il formato del foglio in centesimi di millimetro.

L'esempio seguente mostra come cambiare stampante e impostare il formato del foglio con l'ausilio della proprietà Printer.

Dim Doc As Object
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size
 
PaperSize.Width = 20000   ' corresponds to 20 cm
PaperSize.Height = 20000   ' corresponds to 20 cm
PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"
PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize
Doc.Printer = PrinterProperties()

L'esempio definisce un oggetto denominato PaperSize con il tipo com.sun.star.awt.Size. Ciò è necessario per specificare il formato del foglio. Inoltre, crea un campo di dati per due voci di PropertyValue denominate PrinterProperties. Il campo di dati viene quindi inizializzato con i valori da impostare e assegnare alla proprietà Printer. Dal punto di vista di UNO, la stampante non è una proprietà reale, bensì imitata.