Difference between revisions of "EN/Documentation/BASIC Guide/StarDesktop"
(New page: {{DISPLAYTITLE:StarDesktop}} {{EN/Documentation/BASICGuideTOC/v2 |ShowPrevNext=block |ShowPrevPage=block |PrevPage=Documentation/BASIC Guide/Documents |NextPage=Documentation/BASIC Guide/T...) |
|||
Line 1: | Line 1: | ||
− | {{DISPLAYTITLE:StarDesktop}} | + | {{DISPLAYTITLE:Lo StarDesktop}} |
{{EN/Documentation/BASICGuideTOC/v2 | {{EN/Documentation/BASICGuideTOC/v2 | ||
|ShowPrevNext=block | |ShowPrevNext=block | ||
Line 8: | Line 8: | ||
}} | }} | ||
− | + | Quando si utilizzano i documenti, due servizi in particolare vengono impiegati molto frequentemente: | |
− | *<idl>com.sun.star.frame.Desktop</idl> | + | * Il servizio <idl>com.sun.star.frame.Desktop</idl>, simile al servizio core di {{OOo}}, fornisce le funzioni per l'oggetto cornice di {{OOo}}, 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 <idl>com.sun.star.document.OfficeDocument</idl>, che fornisce metodi per salvare, esportare e stampare i documenti. | ||
− | <idl>com.sun.star.frame.Desktop</idl> | + | Il servizio <idl>com.sun.star.frame.Desktop</idl> si apre automaticamente all'avvio di {{OOo}}. Per eseguire questa attività, {{OOo}} Basic crea un oggetto raggiungibile tramite il nome globale <tt>StarDesktop</tt>. |
− | <tt>StarDesktop</tt> | + | L'interfaccia più importante dello<tt>StarDesktop</tt> è <idl>com.sun.star.frame.XComponentLoader</idl>, che include il metodo <tt>loadComponentFromURL</tt>, responsabile della creazione, dell'importazione e dell'apertura dei documenti. |
− | <tt>StarDesktop</tt> | + | Il nome dell'oggetto <tt>StarDesktop</tt> risale a StarOffice 5, in cui tutte le finestre dei documenti erano integrate in un'unica applicazione comune denominata <tt>StarDesktop</tt>. Nella presente versione di {{OOo}}, lo <tt>StarDesktop</tt> non è più visibile. Il nome <tt>StarDesktop</tt> è stato tuttavia mantenuto per l'oggetto cornice di {{OOo}}, poiché indica chiaramente che si tratta dell'oggetto base dell'intera applicazione. |
− | <tt>StarDesktop</tt> | + | L'oggetto <tt>StarDesktop</tt> sostituisce l'oggetto <tt>Application</tt> di StarOffice 5, che in precedenza fungeva da oggetto radice. A differenza del vecchio oggetto <tt>Application</tt>, questo oggetto è tuttavia principalmente responsabile dell'apertura di |
+ | nuovi documenti. Le funzioni residenti nel vecchio oggetto <tt>Application</tt> per il controllo della rappresentazione su schermo di {{OOo}} (ad esempio <tt>FullScreen</tt>, <tt>FunctionBarVisible</tt>, <tt>Height</tt>, <tt>Width</tt>, <tt>Top</tt>, <tt>Visible</tt>) non sono più utilizzate. | ||
− | {{Documentation/Note| | + | {{Documentation/Note|Mentre i documenti attivi sono accessibili in Word tramite <tt>Application.ActiveDocument</tt> e in Excel tramite <tt>Application.ActiveWorkbook,</tt>, in {{OOo}} è <tt>StarDesktop</tt> responsabile di |
+ | questa attività. L'accesso all'oggetto documento attivo in {{OOo}} è eseguito tramite la proprietà <tt>StarDesktop.CurrentComponent</tt> o mediante <tt>ThisComponent</tt>.}} | ||
== ThisComponent == | == ThisComponent == | ||
− | <tt>ThisComponent</tt> | + | <tt>ThisComponent</tt> in genere restituisce lo stesso oggetto di <tt>StarDesktop.CurrentComponent</tt>, con un vantaggio fondamentale: durante l'esecuzione dall'ambiente di sviluppo integrato di Basic, il debug o l'esplorazione, <tt>StarDesktop</tt> restituisce l'ambiente di sviluppo integrato di Basic. Probabilmente questa non rappresenta la soluzione ideale. <tt>ThisComponent</tt> restituisce il documento attivo più recente. |
− | =={{OOo}} | + | == Informazioni di base sui documenti in {{OOo}} == |
− | + | ||
− | {{OOo}} | + | Quando si utilizzano documenti {{OOo}}, è utile conoscere alcune informazioni di base sulla gestione dei documenti in {{OOo}}. Tra queste, le modalità di strutturazione dei nomi dei file per i documenti {{OOo}}, nonché il formato di salvataggio dei file. |
− | === | + | === Nomi dei file nella notazione URL === |
− | {{OOo}} | + | Poiché {{OOo}} è 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 <tt>file:///</tt> 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 <tt>test.odt</tt> nella directory doc sull'unità C:. | ||
file:///C:/doc/test.odt | file:///C:/doc/test.odt | ||
− | + | Per convertire i nomi di file locali in URL, {{OOo}} dispone della funzione <tt>ConvertToUrl</tt>. Per convertire un URL in un nome di file locale, {{OOo}} dispone | |
+ | della funzione <tt>ConvertFromUrl</tt>: | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 46: | Line 53: | ||
</source> | </source> | ||
− | + | 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. | |
− | Internet | + | Lo standard Internet RFC 1738, su cui si basa, consente l'uso dei caratteri <tt>0-9</tt>, <tt>a-z</tt> e <tt>A-Z</tt>. 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 <tt>%20</tt> nell'URL. |
− | |||
− | + | === Formato XML === | |
− | + | {{OOo}} 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. {{OOo}}, quindi, li comprime e li salva in formato ZIP. Per mezzo delle opzioni del metodo <tt>storeAsURL</tt>, l'utente può salvare direttamente i file XML originali. Vedere [[Documentation/BASIC Guide/StarDesktop#storeAsURL Method Options|Opzioni del metodo storeAsURL]]. | |
− | + | == Creazione, apertura e importazione di documenti == | |
+ | |||
+ | I documenti vengono aperti, importati e creati utilizzando il metodo | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 66: | Line 74: | ||
</source> | </source> | ||
− | + | Il primo parametro di <tt>loadComponentFromURL</tt> specifica l'URL del file associato. | |
− | <tt>loadComponentFromURL</tt> | + | Come secondo parametro, <tt>loadComponentFromURL</tt> prevede un nome per l'oggetto |
+ | cornice della finestra che {{OOo}} crea internamente a scopo di amministrazione. Il nome predefinito <tt>_blank</tt> è generalmente specificato in questo punto e ciò garantisce che {{OOo}} crei una nuova finestra. In alternativa, potete specificare anche <tt>_hidden</tt>, che garantisce che il documento corrispondente sia caricato ma rimanga invisibile. | ||
− | + | Utilizzando questi parametri, l'utente può aprire un documento di {{OOo}}, poiché | |
+ | agli ultimi due parametri si possono assegnare segnaposto (valori di esempio): | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 82: | Line 92: | ||
</source> | </source> | ||
− | + | La chiamata precedente apre il file <tt>text.odt</tt> e lo visualizza in una nuova finestra. | |
− | {{OOo}} Basic | + | In questo modo potete aprire in {{OOo}} Basic un numero qualsiasi di documenti, che potrete quindi modificare utilizzando gli oggetti documento restituiti. |
− | {{Documentation/Note|<tt>StarDesktop.loadComponentFromURL</tt> | + | {{Documentation/Note|<tt>StarDesktop.loadComponentFromURL</tt> sostituisce i metodi <tt>Documents.Add</tt> e <tt>Documents.Open</tt> della precedente API di {{OOo}}.}} |
− | === | + | === Sostituzione del contenuto della finestra del documento === |
− | + | I valori <tt>_blank</tt> e <tt>_hidden</tt> per il parametro <tt>Frame</tt> assicurano che {{OOo}} crei una nuova finestra per ogni chiamata da <tt>loadComponentFromURL</tt>. 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 <tt>SearchFlags</tt> deve essere impostato in modo che venga creata la struttura corrispondente, qualora | |
+ | non esista già. La costante corrispondente per <tt>SearchFlags</tt> è: | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 97: | Line 108: | ||
</source> | </source> | ||
− | + | L'esempio seguente mostra come sostituire il contenuto di una finestra aperta con l'ausilio del parametro di cornice e di <tt>SearchFlags</tt>: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 116: | Line 127: | ||
</source> | </source> | ||
− | + | L'esempio apre prima il file <tt>test.odt</tt> in una nuova finestra con il nome <tt>MyFrame</tt>. Una volta confermata la finestra di messaggio, sostituisce il contenuto della finestra con il file <tt>test2.odt</tt>. | |
− | === loadComponentFromURL | + | === Opzioni del metodo loadComponentFromURL === |
− | <tt>loadComponentFromURL</tt> | + | Il quarto parametro della funzione <tt>loadComponentFromURL</tt> è un campo di dati <tt>PropertyValue</tt>, che offre a {{OOo}} diverse opzioni per aprire e creare documenti. Il campo di dati deve fornire una struttura <tt>PropertyValue</tt> per ogni opzione in cui il nome dell'opzione nonché il valore associato sono salvati come stringa. |
− | <tt>loadComponentFromURL</tt> | + | <tt>loadComponentFromURL</tt> supporta le opzioni seguenti: |
− | ;<tt>AsTemplate (Boolean)</tt>: | + | ;<tt>AsTemplate (Boolean)</tt>: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. |
− | ;<tt>CharacterSet (String)</tt>: | + | ;<tt>CharacterSet (String)</tt>:Definisce il set di caratteri su cui si basa un documento. |
− | ;<tt>FilterName (String)</tt>:<tt>loadComponentFromURL</tt> | + | ;<tt>FilterName (String)</tt>:Specifica un filtro speciale per la funzione <tt>loadComponentFromURL</tt>. I nomi di filtro disponibili sono definiti nel file <tt>\share\config\registry\instance\org\openoffice\office\TypeDetection.xml</tt>. |
− | ;<tt>FilterOptions (String)</tt>: | + | ;<tt>FilterOptions (String)</tt>:Definisce le opzioni aggiuntive per i filtri. |
− | ;<tt>JumpMark (String)</tt>: | + | ;<tt>JumpMark (String)</tt>:Una volta aperto un documento, passa alla posizione definita in JumpMark. |
− | ;<tt>Password (String)</tt>: | + | ;<tt>Password (String)</tt>:Trasferisce una password per un file protetto. |
− | ;<tt>ReadOnly (Boolean)</tt>: | + | ;<tt>ReadOnly (Boolean)</tt>:Carica un documento in sola lettura. |
− | + | L'esempio seguente mostra come aprire un file di testo separato da virgole in {{OOo}} Calc utilizzando l'opzione <tt>FilterName</tt>. | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 146: | Line 157: | ||
</source> | </source> | ||
− | + | Il campo di dati <tt>FileProperties</tt> copre precisamente un valore perché registra un'opzione. La proprietà <tt>Filtername</tt> definisce se {{OOo}} utilizza un filtro di testo | |
+ | di {{OOo}} Calc per aprire i file. | ||
− | === | + | === Creazione di nuovi documenti === |
+ | {{OOo}} 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 <tt>private:factory</tt>: | |
− | + | ||
− | + | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 164: | Line 175: | ||
</source> | </source> | ||
− | + | La chiamata crea un documento vuoto di {{OOo}} Writer. | |
− | == | + | == Oggetti documento == |
− | + | La funzione <tt>loadComponentFromURL</tt> presentata nella sezione precedente restituisce un oggetto documento. Supporta il servizio <idl>com.sun.star.document.OfficeDocument</idl>, che a sua volta fornisce due interfacce centrali: | |
− | *<idl>com.sun.star.frame.XStorable</idl> | + | * L'interfaccia <idl>com.sun.star.frame.XStorable</idl>, responsabile del salvataggio dei documenti. |
− | *<idl>com.sun.star.view.XPrintable</idl> | + | * L'interfaccia <idl>com.sun.star.view.XPrintable</idl>, che contiene i metodi per la stampa dei documenti. |
− | === | + | === Salvataggio ed esportazione di documenti === |
− | {{OOo}} | + | |
+ | I documenti di {{OOo}} vengono salvati direttamente tramite l'oggetto documento. A tale scopo è disponibile il metodo <tt>store</tt> dell'interfaccia <idl>com.sun.star.frame.XStorable</idl>: | ||
<source lang="oobas"> | <source lang="oobas"> | ||
Line 181: | Line 193: | ||
</source> | </source> | ||
− | + | 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 <tt>storeAsURL</tt>. Tale metodo è definito anche in <idl>com.sun.star.frame.XStorable</idl> e può essere utilizzato per definire la posizione del documento: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 191: | Line 203: | ||
</source> | </source> | ||
− | + | Oltre ai metodi sopracitati, <idl>com.sun.star.frame.XStorable</idl> fornisce anche | |
+ | alcuni metodi utili per il salvataggio dei documenti. Tali metodi sono: | ||
− | ;<tt>hasLocation()</tt>: | + | ;<tt>hasLocation()</tt>:Specifica se al documento è già stato assegnato un URL. |
− | ;<tt>isReadonly()</tt>: | + | ;<tt>isReadonly()</tt>:Specifica se un documento ha la protezione di sola lettura. |
− | ;<tt>isModified()</tt>: | + | ;<tt>isModified()</tt>: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: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 209: | Line 222: | ||
</source> | </source> | ||
− | + | 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. | |
− | === storeAsURL | + | === Opzioni del metodo storeAsURL === |
− | <tt>loadComponentFromURL</tt> | + | In modo analogo a quanto avviene per il metodo <tt>loadComponentFromURL</tt>, potete specificare alcune opzioni anche sotto forma di campo di dati <tt>PropertyValue</tt> utilizzando il metodo <tt>storeAsURL</tt>. Tali opzioni determinano la procedura utilizzata da {{OOo}} per il salvataggio di un documento. <tt>storeAsURL</tt> dispone delle opzioni seguenti: |
− | ;<tt>CharacterSet (String)</tt>: | + | ;<tt>CharacterSet (String)</tt>:Definisce il set di caratteri su cui si basa un documento. |
− | ;<tt>FilterName (String)</tt>:<tt>loadComponentFromURL</tt> | + | ;<tt>FilterName (String)</tt>:Specifica un filtro speciale per la funzione <tt>loadComponentFromURL</tt>. I nomi di filtro disponibili sono definiti nel file <tt>\share\config\registry\instance\org\openoffice\office\TypeDetection.xml</tt>. |
− | ;<tt>FilterOptions (String)</tt>: | + | ;<tt>FilterOptions (String)</tt>:Definisce le opzioni aggiuntive per i filtri. |
− | ;<tt>Overwrite (Boolean)</tt>: | + | ;<tt>Overwrite (Boolean)</tt>:Consente la sovrascrittura di un file preesistente senza una ricerca. |
− | ;<tt>Password (String)</tt>: | + | ;<tt>Password (String)</tt>:Trasferisce la password per un file protetto. |
− | ;<tt>Unpacked (Boolean)</tt>: | + | ;<tt>Unpacked (Boolean)</tt>:Salva il documento (non compresso) nelle sottodirectory. |
− | + | L'esempio seguente mostra come potrete utilizzare l'opzione <tt>Overwrite</tt> insieme a <tt>storeAsURL</tt>: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 236: | Line 249: | ||
</source> | </source> | ||
− | + | L'esempio salva quindi <tt>Doc</tt> 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 <tt>Print</tt> dell'interfaccia <idl>com.sun.star.view.Xprintable</idl>. Nella sua forma più semplice, la chiamata print è: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 248: | Line 261: | ||
</source> | </source> | ||
− | <tt>loadComponentFromURL</tt> | + | Come nel caso del metodo <tt>loadComponentFromURL</tt>, il parametro Dummy è un campo di dati <tt>PropertyValue</tt> attraverso il quale {{OOo}} può specificare diverse opzioni di stampa. |
− | === print | + | === Opzioni del metodo print=== |
− | <tt>print</tt> | + | Il metodo <tt>print</tt> prevede un campo di dati <tt>PropertyValue</tt> come parametro, che riflette le impostazioni della finestra di stampa di {{OOo}}: |
− | ;<tt>CopyCount (Integer)</tt>: | + | ;<tt>CopyCount (Integer)</tt>:Specifica il numero di copie da stampare. |
− | ;<tt>FileName (String)</tt>: | + | ;<tt>FileName (String)</tt>:Stampa il documento nel file specificato. |
− | ;<tt>Collate (Boolean)</tt>: | + | ;<tt>Collate (Boolean)</tt>:Informa la stampante che le pagine delle copie devono essere ordinate. |
− | ;<tt>Sort (Boolean)</tt>: | + | ;<tt>Sort (Boolean)</tt>:Ordina le pagine quando si stampano diverse copie (<tt>CopyCount</tt> > 1). |
− | ;<tt>Pages (String)</tt>: | + | ;<tt>Pages (String)</tt>: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 <tt>Pages</tt>: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 271: | Line 284: | ||
</source> | </source> | ||
− | === | + | === Selezione e impostazioni della stampante === |
+ | |||
+ | L'interfaccia <idl>com.sun.star.view.XPrintable</idl> fornisce la proprietà <tt>Printer</tt>, che | ||
+ | seleziona la stampante. Tale proprietà accetta un campo di dati <tt>PropertyValue</tt> con le impostazioni seguenti: | ||
− | |||
− | ;<tt>Name (String)</tt>: | + | ;<tt>Name (String)</tt>:Specifica il nome della stampante. |
− | ;<tt>PaperOrientation (Enum)</tt>: | + | ;<tt>PaperOrientation (Enum)</tt>:Specifica l'orientamento del foglio (valori <idl>com.sun.star.view.PaperOrientation.PORTRAIT</idl> per il formato verticale e <idl>com.sun.star.view.PaperOrientation.LANDSCAPE</idl> per il formato orizzontale). |
− | ;<tt>PaperFormat (Enum)</tt>: | + | ;<tt>PaperFormat (Enum)</tt>:Specifica il formato del foglio di carta (ad esempio, <idl>com.sun.star.view.PaperFormat.A4</idl> per DIN A4 o <idl>com.sun.star.view.PaperFormat.Letter</idl> per US letter). |
− | ;<tt>PaperSize (Size)</tt>: | + | ;<tt>PaperSize (Size)</tt>: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à <tt>Printer</tt>. | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 296: | Line 311: | ||
</source> | </source> | ||
− | + | L'esempio definisce un oggetto denominato <tt>PaperSize</tt> con il tipo <idl>com.sun.star.awt.Size</idl>. Ciò è necessario per specificare il formato del foglio. Inoltre, crea un campo di dati per due voci di <tt>PropertyValue</tt> denominate <tt>PrinterProperties</tt>. Il campo di dati viene quindi inizializzato con i valori da impostare e assegnare alla proprietà <tt>Printer</tt>. Dal punto di vista di UNO, la | |
+ | stampante non è una proprietà reale, bensì imitata. | ||
{{PDL1}} | {{PDL1}} | ||
{{InterWiki_Languages_BasicGuide|articletitle=Documentation/BASIC Guide/StarDesktop}} | {{InterWiki_Languages_BasicGuide|articletitle=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.
Contents
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.
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.
Content on this page is licensed under the Public Documentation License (PDL). |